or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

basic-authentication.mdbearer-authentication.mddigest-authentication.mdindex.mdplugin-configuration.md
tile.json

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

Ktor client authentication and authorization plugin for JavaScript platforms supporting Basic, Digest, and Bearer token authentication with automatic token refresh

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

To install, run

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

index.mddocs/

Ktor Client Auth

Ktor Client Auth is a comprehensive authentication and authorization plugin for Ktor HTTP clients targeting JavaScript platforms. It provides a modular, provider-based authentication system supporting multiple authentication schemes including Basic, Digest, and Bearer token authentication with automatic token refresh, unauthorized response detection, and circuit breaker functionality to prevent infinite authentication loops.

Package Information

  • Package Name: io.ktor:ktor-client-auth-js
  • Package Type: maven
  • Language: Kotlin (targeting JavaScript)
  • Installation: Add dependency to your build.gradle.kts:
implementation("io.ktor:ktor-client-auth-js: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.plugins.auth.*
import io.ktor.client.plugins.auth.providers.*

// Create HTTP client with Basic authentication
val client = HttpClient {
    Auth {
        basic {
            credentials {
                BasicAuthCredentials("username", "password")
            }
        }
    }
}

// Create HTTP client with Bearer token authentication
val clientWithBearer = HttpClient {
    Auth {
        bearer {
            loadTokens {
                BearerTokens("access_token", "refresh_token")
            }
            refreshTokens { params ->
                // Refresh logic here
                BearerTokens("new_access_token", "new_refresh_token")
            }
        }
    }
}

Architecture

Ktor Client Auth is built around several key components:

  • Auth Plugin: Core plugin that orchestrates authentication providers and handles token refresh workflows
  • Authentication Providers: Modular providers implementing specific authentication schemes (Basic, Digest, Bearer)
  • Token Management: Automatic token refresh, caching, and circuit breaker functionality
  • Request Interception: Seamless integration with Ktor's client pipeline for automatic header injection
  • Response Detection: Configurable unauthorized response detection for triggering re-authentication

Capabilities

Plugin Installation and Configuration

Core authentication plugin installation and configuration with multiple provider support and customizable unauthorized response detection.

val Auth: ClientPlugin<AuthConfig>

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

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

val AuthCircuitBreaker: AttributeKey<Unit>

Plugin Configuration

Basic Authentication

HTTP Basic authentication provider supporting username/password credentials with optional realm specification and configurable sending behavior.

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

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

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

class BasicAuthProvider : AuthProvider

Basic Authentication

Bearer Token Authentication

Bearer token authentication provider with support for automatic token refresh, access/refresh token pairs, and circuit breaker functionality.

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

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

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

class RefreshTokensParams(
    val client: HttpClient,
    val response: HttpResponse,
    val oldTokens: BearerTokens?
) {
    fun HttpRequestBuilder.markAsRefreshTokenRequest()
}

class BearerAuthProvider : AuthProvider

Bearer Authentication

Digest Authentication

HTTP Digest authentication provider supporting MD5 and other hash algorithms with automatic nonce handling and client nonce generation.

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

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

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

class DigestAuthProvider : AuthProvider

Digest Authentication

Core 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 HttpClient.authProviders: List<AuthProvider>

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