/ktor-api-key

Ktor API Key Authentication Provider

Primary LanguageKotlinMIT LicenseMIT

Ktor API Key Authentication Provider

Simple authentication provider for Ktor that verifies presence of the API key in the header. Useful if you want to use X-Api-Key or similar approaches for request authentication.

Notice:

Active development was moved to LukasForst/ktor-plugins repository.

Installation

Include following in your build.gradle.kts:

implementation("dev.forst", "ktor-api-key", "1.1.0")

Versions >= 1.1.0 have implementation for Ktor >= 2.0.0, use 1.0.0 if you need support for older versions of Ktor.

Usage

This is minimal implementation of the Ktor app that uses API Key authentication:

/**
 * Minimal Ktor application with API Key authentication.
 */
fun Application.minimalExample() {
    // key that will be used to authenticate requests
    val expectedApiKey = "this-is-expected-key"

    // principal for the app
    data class AppPrincipal(val key: String) : Principal
    // now we install authentication feature
    install(Authentication) {
        // and then api key provider
        apiKey {
            // set function that is used to verify request
            validate { keyFromHeader ->
                keyFromHeader
                    .takeIf { it == expectedApiKey }
                    ?.let { AppPrincipal(it) }
            }
        }
    }

    routing {
        authenticate {
            get {
                val p = call.principal<AppPrincipal>()!!
                call.respondText("Key: ${p.key}")
            }
        }
    }
}

For details see MinimalExampleApp.kt with this example application and TestMinimalExampleApp.kt which verifies that this app works as expected.

For more advanced configuration see TestApiKeyAuth.kt.