or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

auth-plugin.mdbasic-auth.mdbearer-auth.mddigest-auth.mdindex.md
tile.json

tessl/maven-io-ktor--ktor-client-auth

Ktor client authentication and authorization plugin that handles various authentication schemes including Basic, Bearer, and Digest authentication.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.ktor/ktor-client-auth@3.2.x

To install, run

npx @tessl/cli install tessl/maven-io-ktor--ktor-client-auth@3.2.0

index.mddocs/

Ktor Client Auth

Ktor Client Auth is a comprehensive authentication and authorization plugin for Ktor HTTP clients. It provides automatic handling of various authentication schemes including Basic, Bearer, and Digest authentication with intelligent token management, refresh capabilities, and circuit breaker functionality to prevent infinite authentication loops.

Package Information

  • Package Name: io.ktor:ktor-client-auth
  • Package Type: Maven
  • Language: Kotlin
  • Installation: implementation("io.ktor:ktor-client-auth:3.2.0")

Core Imports

import io.ktor.client.plugins.auth.*
import io.ktor.client.plugins.auth.providers.*

Basic Usage

import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.auth.*
import io.ktor.client.plugins.auth.providers.*
import io.ktor.client.request.*

// Create HTTP client with Bearer authentication
val client = HttpClient(CIO) {
    install(Auth) {
        bearer {
            loadTokens {
                // Load tokens from storage
                BearerTokens("access_token", "refresh_token")
            }
            refreshTokens { params ->
                // Refresh tokens when needed
                val newTokens = refreshTokenFromServer(params.oldTokens)
                newTokens
            }
        }
    }
}

// Make authenticated requests
val response = client.get("https://api.example.com/protected")

Architecture

Ktor Client Auth is built around several key components:

  • Auth Plugin: Core plugin that intercepts HTTP requests/responses and manages authentication flow
  • Authentication Providers: Pluggable authentication handlers for different schemes (Basic, Bearer, Digest)
  • Token Management: Thread-safe token caching and refresh system with automatic retry logic
  • Circuit Breaker: Prevention of infinite authentication loops using request attributes
  • Response Detection: Configurable detection of unauthorized responses to trigger re-authentication

Capabilities

Auth Plugin Configuration

Core authentication plugin setup and configuration for handling unauthorized responses and managing authentication providers.

val Auth: ClientPlugin<AuthConfig>

fun HttpClientConfig<*>.Auth(block: AuthConfig.() -> Unit)

class AuthConfig {
    val providers: MutableList<AuthProvider>
    fun reAuthorizeOnResponse(block: suspend (HttpResponse) -> Boolean)
}

Auth Plugin

Bearer Authentication

OAuth2/JWT token authentication with automatic token refresh and management. Supports access tokens with optional refresh tokens.

fun AuthConfig.bearer(block: BearerAuthConfig.() -> Unit)

class BearerTokens(
    val accessToken: String,
    val refreshToken: String?
)

class BearerAuthConfig {
    var realm: String?
    fun loadTokens(block: suspend () -> BearerTokens?)
    fun refreshTokens(block: suspend RefreshTokensParams.() -> BearerTokens?)
    fun sendWithoutRequest(block: (HttpRequestBuilder) -> Boolean)
}

Bearer Authentication

Basic Authentication

Username/password authentication using HTTP Basic authentication scheme with credential caching.

fun AuthConfig.basic(block: BasicAuthConfig.() -> Unit)

class BasicAuthCredentials(
    val username: String,
    val password: String
)

class BasicAuthConfig {
    var realm: String?
    fun credentials(block: suspend () -> BasicAuthCredentials?)
    fun sendWithoutRequest(block: (HttpRequestBuilder) -> Boolean)
}

Basic Authentication

Digest Authentication

Challenge-response authentication using HTTP Digest authentication scheme with nonce handling and hash computation.

fun AuthConfig.digest(block: DigestAuthConfig.() -> Unit)

class DigestAuthCredentials(
    val username: String,
    val password: String
)

class DigestAuthConfig {
    var algorithmName: String
    var realm: String?
    fun credentials(block: suspend () -> DigestAuthCredentials?)
}

Digest Authentication

Types

interface AuthProvider {
    fun sendWithoutRequest(request: HttpRequestBuilder): Boolean
    fun isApplicable(auth: HttpAuthHeader): Boolean
    suspend fun addRequestHeaders(request: HttpRequestBuilder, authHeader: HttpAuthHeader? = null)
    suspend fun refreshToken(response: HttpResponse): Boolean
}

val AuthCircuitBreaker: AttributeKey<Unit>

val HttpClient.authProviders: List<AuthProvider>

inline fun <reified T : AuthProvider> HttpClient.authProvider(): T?