feat: replace custom Ktor route plugin with AuthenticationProvider

This is more semantically correct and also plays more nicely with the
native Ktor authentication constructs, e.g. custom authorization plugins with
`on(AuthenticationChecked)`, `ApplicationCall.principal()` and so on.

Author: tronghn

build.gradle.kts

@@ -64,6 +64,7 @@ subprojects {
     dependencies {
         implementation(kotlin("stdlib"))
         implementation("io.ktor:ktor-server:${ktorVersion}")
+        implementation("io.ktor:ktor-server-auth:${ktorVersion}")
         implementation("io.ktor:ktor-server-cio:${ktorVersion}")
         implementation("io.ktor:ktor-server-content-negotiation:${ktorVersion}")
         implementation("io.ktor:ktor-serialization-jackson:${ktorVersion}")

wonderwalled-azure/src/main/kotlin/io/nais/Wonderwalled.kt

@@ -1,75 +1,82 @@
 package io.nais
 
 import io.ktor.http.HttpStatusCode
+import io.ktor.server.application.install
+import io.ktor.server.auth.Authentication
+import io.ktor.server.auth.authenticate
+import io.ktor.server.auth.principal
 import io.ktor.server.response.respond
 import io.ktor.server.routing.get
 import io.ktor.server.routing.route
 import io.ktor.server.routing.routing
 import io.nais.common.AuthClient
 import io.nais.common.IdentityProvider
-import io.nais.common.NaisAuth
+import io.nais.common.TexasPrincipal
 import io.nais.common.TokenResponse
 import io.nais.common.bearerToken
 import io.nais.common.requestHeaders
 import io.nais.common.server
+import io.nais.common.texas
 
 fun main() {
     server { config ->
         val azure = AuthClient(config.auth, IdentityProvider.AZURE_AD)
 
-        routing {
-            route("api") {
-                install(NaisAuth) {
-                    client = azure
-                    ingress = config.ingress
-                }
-
-                get("headers") {
-                    call.respond(call.requestHeaders())
-                }
+        install(Authentication) {
+            texas {
+                client = azure
+                ingress = config.ingress
+            }
+        }
 
-                get("me") {
-                    val token = call.bearerToken()
-                    if (token == null) {
-                        call.respond(HttpStatusCode.Unauthorized, "missing bearer token in Authorization header")
-                        return@get
+        routing {
+            authenticate {
+                route("api") {
+                    get("headers") {
+                        call.respond(call.requestHeaders())
                     }
 
-                    val introspection = azure.introspect(token)
-                    call.respond(introspection)
-                }
-
-                get("obo") {
-                    val token = call.bearerToken()
-                    if (token == null) {
-                        call.respond(HttpStatusCode.Unauthorized, "missing bearer token in Authorization header")
-                        return@get
+                    get("me") {
+                        val principal = call.principal<TexasPrincipal>()
+                        if (principal == null) {
+                            call.respond(HttpStatusCode.Unauthorized, "missing principal")
+                            return@get
+                        }
+                        call.respond(principal.claims)
                     }
 
-                    val audience = call.request.queryParameters["aud"]
-                    if (audience == null) {
-                        call.respond(HttpStatusCode.BadRequest, "missing 'aud' query parameter")
-                        return@get
-                    }
+                    get("obo") {
+                        val token = call.bearerToken()
+                        if (token == null) {
+                            call.respond(HttpStatusCode.Unauthorized, "missing bearer token in Authorization header")
+                            return@get
+                        }
 
-                    val target = audience.toScope()
-                    when (val response = azure.exchange(target, token)) {
-                        is TokenResponse.Success -> call.respond(response)
-                        is TokenResponse.Error -> call.respond(response.status, response.error)
-                    }
-                }
+                        val audience = call.request.queryParameters["aud"]
+                        if (audience == null) {
+                            call.respond(HttpStatusCode.BadRequest, "missing 'aud' query parameter")
+                            return@get
+                        }
 
-                get("m2m") {
-                    val audience = call.request.queryParameters["aud"]
-                    if (audience == null) {
-                        call.respond(HttpStatusCode.BadRequest, "missing 'aud' query parameter")
-                        return@get
+                        val target = audience.toScope()
+                        when (val response = azure.exchange(target, token)) {
+                            is TokenResponse.Success -> call.respond(response)
+                            is TokenResponse.Error -> call.respond(response.status, response.error)
+                        }
                     }
 
-                    val target = audience.toScope()
-                    when (val response = azure.token(target)) {
-                        is TokenResponse.Success -> call.respond(response)
-                        is TokenResponse.Error -> call.respond(response.status, response.error)
+                    get("m2m") {
+                        val audience = call.request.queryParameters["aud"]
+                        if (audience == null) {
+                            call.respond(HttpStatusCode.BadRequest, "missing 'aud' query parameter")
+                            return@get
+                        }
+
+                        val target = audience.toScope()
+                        when (val response = azure.token(target)) {
+                            is TokenResponse.Success -> call.respond(response)
+                            is TokenResponse.Error -> call.respond(response.status, response.error)
+                        }
                     }
                 }
             }

wonderwalled-common/src/main/kotlin/io/nais/common/Auth.kt

@@ -12,7 +12,10 @@ import io.ktor.client.request.forms.submitForm
 import io.ktor.http.HttpStatusCode
 import io.ktor.http.parameters
 import io.ktor.server.application.ApplicationCall
-import io.ktor.server.application.createRouteScopedPlugin
+import io.ktor.server.auth.AuthenticationConfig
+import io.ktor.server.auth.AuthenticationContext
+import io.ktor.server.auth.AuthenticationFailedCause
+import io.ktor.server.auth.AuthenticationProvider
 import io.ktor.server.request.host
 import io.ktor.server.request.uri
 import io.ktor.server.response.respondRedirect
@@ -57,8 +60,8 @@ data class TokenErrorResponse(
  *
  * The `other` field is a generic map that contains an arbitrary combination of additional claims contained in the token.
  *
- * If you know the exact claims to expect, you should instead explicitly define these as fields on the
- * data class itself, for example:
+ * TODO(user): If you know the exact claims to expect, you should instead explicitly define these as fields on the
+ *  data class itself and ignore everything else, for example:
  *
  * ```kotlin
  * data class TokenIntrospectionResponse(
@@ -79,6 +82,9 @@ data class TokenIntrospectionResponse(
     val other: Map<String, Any?> = mutableMapOf(),
 )
 
+/**
+ * AuthClient is a client that interacts with Texas.
+ */
 class AuthClient(
     private val config: Config.Auth,
     private val provider: IdentityProvider,
@@ -150,66 +156,97 @@ class AuthClient(
     }
 }
 
-class AuthPluginConfiguration(
-    var client: AuthClient? = null,
-    var ingress: String? = null,
-    var logger: Logger = LoggerFactory.getLogger("io.nais.common.ktor.NaisAuth"),
-)
+fun AuthenticationConfig.texas(
+    name: String? = null,
+    configure: TexasAuthenticationProvider.Config.() -> Unit,
+) {
+    register(TexasAuthenticationProvider.Config(name).apply(configure).build())
+}
 
-val NaisAuth =
-    createRouteScopedPlugin(
-        name = "NaisAuth",
-        createConfiguration = ::AuthPluginConfiguration,
-    ) {
-        val logger = pluginConfig.logger
-        val client = pluginConfig.client ?: throw IllegalArgumentException("NaisAuth plugin: client must be set")
-        val ingress = pluginConfig.ingress ?: ""
-
-        val challenge: suspend (ApplicationCall) -> Unit = { call ->
-            val target = call.loginUrl(ingress)
-            logger.info("unauthenticated: redirecting to '$target'")
-            call.respondRedirect(target)
-        }
+/**
+ * TexasAuthenticationProvider is an [io.ktor.server.auth.AuthenticationProvider] that validates tokens by using Texas's introspection endpoint.
+ */
+class TexasAuthenticationProvider(
+    config: Config,
+) : AuthenticationProvider(config) {
+    class Config internal constructor(
+        name: String?,
+    ) : AuthenticationProvider.Config(name) {
+        lateinit var client: AuthClient
+        var logger: Logger = LoggerFactory.getLogger("io.nais.common.TexasAuthenticationProvider")
+        var ingress: String = ""
+
+        internal fun build() = TexasAuthenticationProvider(this)
+    }
 
-        pluginConfig.apply {
-            onCall { call ->
-                val token = call.bearerToken()
-                if (token == null) {
-                    logger.warn("unauthenticated: no Bearer token found in Authorization header")
-                    challenge(call)
-                    return@onCall
-                }
+    private val client = config.client
+    private val logger = config.logger
+    private val ingress = config.ingress
 
-                val introspectResponse =
-                    try {
-                        client.introspect(token)
-                    } catch (e: Exception) {
-                        logger.error("unauthenticated: introspect request failed: ${e.message}")
-                        challenge(call)
-                        return@onCall
-                    }
-
-                if (introspectResponse.active) {
-                    logger.info("authenticated - claims='${introspectResponse.other}'")
-                    return@onCall
-                }
+    override suspend fun onAuthenticate(context: AuthenticationContext) {
+        val applicationCall = context.call
+        val token = applicationCall.bearerToken()
 
-                logger.warn("unauthenticated: ${introspectResponse.error}")
-                challenge(call)
-                return@onCall
+        if (token == null) {
+            logger.warn("unauthenticated: no Bearer token found in Authorization header")
+            context.loginChallenge(AuthenticationFailedCause.NoCredentials)
+            return
+        }
+
+        val introspectResponse =
+            try {
+                client.introspect(token)
+            } catch (e: Exception) {
+                // TODO(user): You should handle the specific exceptions that can be thrown by the HTTP client, e.g. retry on network errors and so on
+                logger.error("unauthenticated: introspect request failed: ${e.message}")
+                context.loginChallenge(AuthenticationFailedCause.Error(e.message ?: "introspect request failed"))
+                return
             }
+
+        if (!introspectResponse.active) {
+            logger.warn("unauthenticated: ${introspectResponse.error}")
+            context.loginChallenge(AuthenticationFailedCause.InvalidCredentials)
+            return
         }
 
-        logger.info("NaisAuth plugin loaded.")
+        logger.info("authenticated - claims='${introspectResponse.other}'")
+        context.principal(
+            TexasPrincipal(
+                claims = introspectResponse.other,
+                token = token,
+            ),
+        )
     }
 
-// loginUrl constructs a URL string that points to the login endpoint (Wonderwall) for redirecting a request.
-// It also indicates that the user should be redirected back to the original request path after authentication
-private fun ApplicationCall.loginUrl(defaultHost: String): String {
-    val host =
-        defaultHost.ifEmpty(defaultValue = {
-            "${this.request.local.scheme}://${this.request.host()}"
-        })
+    private fun AuthenticationContext.loginChallenge(cause: AuthenticationFailedCause) {
+        challenge("Texas", cause) { authenticationProcedureChallenge, call ->
+            val target = call.loginUrl()
+            logger.info("unauthenticated: redirecting to '$target'")
+            call.respondRedirect(target)
+            authenticationProcedureChallenge.complete()
+        }
+    }
 
-    return "$host/oauth2/login?redirect=${this.request.uri}"
+    /**
+     * loginUrl constructs a URL string that points to the login endpoint (Wonderwall) for redirecting a request.
+     * It also indicates that the user should be redirected back to the original request path after authentication
+     */
+    private fun ApplicationCall.loginUrl(): String {
+        val host =
+            ingress.ifEmpty(defaultValue = {
+                "${this.request.local.scheme}://${this.request.host()}"
+            })
+
+        return "$host/oauth2/login?redirect=${this.request.uri}"
+    }
 }
+
+/**
+ * TexasPrincipal represents the authenticated principal.
+ * The `claims` field is a map of arbitrary claims from the [TokenIntrospectionResponse].
+ * TODO(user): You should explicitly define expected claims as fields on the data class itself instead of using a generic map.
+ */
+data class TexasPrincipal(
+    val claims: Map<String, Any?>,
+    val token: String,
+)