CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-io-ktor--ktor-server-auth-jvm

Authentication and authorization plugin for Ktor server applications

Pending
Overview
Eval results
Files

Ktor Server Authentication

Comprehensive authentication and authorization capabilities for Ktor server applications. This module provides support for multiple authentication mechanisms including Basic, Bearer, Form-based, Session-based, Digest, OAuth 1.0a, and OAuth 2.0 authentication through a flexible provider-based architecture.

Package Information

  • Package Name: ktor-server-auth-jvm
  • Package Type: maven
  • Language: Kotlin
  • Installation:
    implementation("io.ktor:ktor-server-auth-jvm:3.2.0")

Core Imports

import io.ktor.server.auth.*
import io.ktor.server.application.*
import io.ktor.server.routing.*

Basic Usage

import io.ktor.server.application.*
import io.ktor.server.auth.*
import io.ktor.server.routing.*
import io.ktor.server.response.*

fun Application.configureAuthentication() {
    install(Authentication) {
        basic("auth-basic") {
            realm = "Access to the '/' path"
            validate { credentials ->
                if (credentials.name == "admin" && credentials.password == "password") {
                    UserIdPrincipal(credentials.name)
                } else null
            }
        }
    }
    
    routing {
        authenticate("auth-basic") {
            get("/protected") {
                val principal = call.principal<UserIdPrincipal>()
                call.respond("Hello ${principal?.name}!")
            }
        }
    }
}

Architecture

The Ktor authentication module follows a provider-based architecture:

  • Authentication Plugin: Core plugin that manages multiple authentication providers
  • Authentication Providers: Specific implementations for different auth mechanisms (Basic, Bearer, OAuth, etc.)
  • Authentication Context: Manages authentication state and results during request processing
  • Principals: Represent authenticated users/identities
  • Credentials: Represent authentication data (username/password, tokens, etc.)
  • Challenge System: Handles authentication failures and response generation

Core Components

Authentication Plugin

Main plugin for handling authentication and authorization.

object Authentication : BaseApplicationPlugin<Application, AuthenticationConfig, Authentication>

fun Application.authentication(block: AuthenticationConfig.() -> Unit)

class AuthenticationConfig {
    fun provider(name: String?, configure: DynamicProviderConfig.() -> Unit)
    fun register(provider: AuthenticationProvider)
}

class DynamicProviderConfig(name: String?) {
    fun authenticate(block: (context: AuthenticationContext) -> Unit)
}

Authentication Context

val ApplicationCall.authentication: AuthenticationContext

inline fun <reified P : Any> ApplicationCall.principal(): P?
inline fun <reified P : Any> ApplicationCall.principal(provider: String?): P?

class AuthenticationContext {
    fun principal(principal: Any)
    fun principal(provider: String?, principal: Any)
    fun <T> principal(provider: String? = null): T?
    fun challenge(key: Any, cause: AuthenticationFailedCause, function: ChallengeFunction)
    fun error(key: Any, cause: AuthenticationFailedCause)
    val allErrors: List<AuthenticationFailedCause>
    val allFailures: List<AuthenticationFailedCause>
}

Route Protection

fun Route.authenticate(
    vararg configurations: String? = arrayOf(null),
    optional: Boolean = false,
    build: Route.() -> Unit
): Route

fun Route.authenticate(
    vararg configurations: String? = arrayOf(null),
    strategy: AuthenticationStrategy,
    build: Route.() -> Unit
): Route

enum class AuthenticationStrategy {
    Optional, FirstSuccessful, Required
}

class AuthenticationRouteSelector(val names: List<String?>)

object AuthenticationChecked

Capabilities

Basic Authentication

HTTP Basic authentication with username and password validation.

fun AuthenticationConfig.basic(
    name: String? = null,
    configure: BasicAuthenticationProvider.Config.() -> Unit
)

Basic Authentication

Bearer Token Authentication

Bearer token authentication for API access tokens and JWT tokens.

fun AuthenticationConfig.bearer(
    name: String? = null,
    configure: BearerAuthenticationProvider.Config.() -> Unit
)

Bearer Authentication

Form and Session Authentication

Form-based and session-based authentication for web applications.

fun AuthenticationConfig.form(
    name: String? = null,
    configure: FormAuthenticationProvider.Config.() -> Unit
)

fun <T : Any> AuthenticationConfig.session(
    name: String? = null,
    configure: SessionAuthenticationProvider.Config<T>.() -> Unit
)

Form and Session Authentication

OAuth Authentication

OAuth 1.0a and OAuth 2.0 support for third-party authentication providers.

fun AuthenticationConfig.oauth(
    name: String? = null,
    configure: OAuthAuthenticationProvider.Config.() -> Unit
)

OAuth Authentication

JVM-Specific Features

Digest authentication and comprehensive OAuth 1.0a support available only on JVM platform.

fun AuthenticationConfig.digest(
    name: String? = null,
    configure: DigestAuthenticationProvider.Config.() -> Unit
)

JVM-Specific Features

Common Types

Credentials

data class UserPasswordCredential(val name: String, val password: String)
data class BearerTokenCredential(val token: String)

Principals

data class UserIdPrincipal(val name: String)

Utility Classes

class UserHashedTableAuth(
    table: Map<String, ByteArray>,
    digester: (String) -> String
) {
    fun authenticate(credential: UserPasswordCredential): UserIdPrincipal?
}

Header Utilities

fun ApplicationRequest.parseAuthorizationHeader(): HttpAuthHeader?

Authentication Results

sealed class AuthenticationFailedCause {
    data object NoCredentials : AuthenticationFailedCause()
    data object InvalidCredentials : AuthenticationFailedCause()
    open class Error(val message: String) : AuthenticationFailedCause()
}

typealias ChallengeFunction = suspend PipelineContext<*, ApplicationCall>.(String, String) -> Unit
typealias AuthenticationFunction<C> = suspend ApplicationCall.(C) -> Any?
typealias ApplicationCallPredicate = (ApplicationCall) -> Boolean

Response Types

class UnauthorizedResponse(
    challenge: HttpAuthHeader = HttpAuthHeader.basicAuthChallenge("Ktor Server")
) : HttpStatusCodeContent

class ForbiddenResponse(message: String = "Forbidden") : HttpStatusCodeContent

Platform Availability

  • Common: Basic, Bearer, Form, Session authentication, OAuth 2.0
  • JVM Only: Digest authentication, OAuth 1.0a
  • JS/WASM/Native: Limited OAuth support through platform-specific implementations

Install with Tessl CLI

npx tessl i tessl/maven-io-ktor--ktor-server-auth-jvm
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.ktor/ktor-server-auth-jvm@3.2.x
Badge
tessl/maven-io-ktor--ktor-server-auth-jvm badge