0
# Ktor Client Auth
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: io.ktor:ktor-client-auth
7
- **Package Type**: Maven
8
- **Language**: Kotlin
9
- **Installation**: `implementation("io.ktor:ktor-client-auth:3.2.0")`
10

11
## Core Imports
12

13
```kotlin
14
import io.ktor.client.plugins.auth.*
15
import io.ktor.client.plugins.auth.providers.*
16
```
17

18
## Basic Usage
19

20
```kotlin
21
import io.ktor.client.*
22
import io.ktor.client.engine.cio.*
23
import io.ktor.client.plugins.auth.*
24
import io.ktor.client.plugins.auth.providers.*
25
import io.ktor.client.request.*
26

27
// Create HTTP client with Bearer authentication
28
val client = HttpClient(CIO) {
29
    install(Auth) {
30
        bearer {
31
            loadTokens {
32
                // Load tokens from storage
33
                BearerTokens("access_token", "refresh_token")
34
            }
35
            refreshTokens { params ->
36
                // Refresh tokens when needed
37
                val newTokens = refreshTokenFromServer(params.oldTokens)
38
                newTokens
39
            }
40
        }
41
    }
42
}
43

44
// Make authenticated requests
45
val response = client.get("https://api.example.com/protected")
46
```
47

48
## Architecture
49

50
Ktor Client Auth is built around several key components:
51

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

58
## Capabilities
59

60
### Auth Plugin Configuration
61

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

64
```kotlin { .api }
65
val Auth: ClientPlugin<AuthConfig>
66

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

69
class AuthConfig {
70
    val providers: MutableList<AuthProvider>
71
    fun reAuthorizeOnResponse(block: suspend (HttpResponse) -> Boolean)
72
}
73
```
74

75
[Auth Plugin](./auth-plugin.md)
76

77
### Bearer Authentication
78

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

81
```kotlin { .api }
82
fun AuthConfig.bearer(block: BearerAuthConfig.() -> Unit)
83

84
class BearerTokens(
85
    val accessToken: String,
86
    val refreshToken: String?
87
)
88

89
class BearerAuthConfig {
90
    var realm: String?
91
    fun loadTokens(block: suspend () -> BearerTokens?)
92
    fun refreshTokens(block: suspend RefreshTokensParams.() -> BearerTokens?)
93
    fun sendWithoutRequest(block: (HttpRequestBuilder) -> Boolean)
94
}
95
```
96

97
[Bearer Authentication](./bearer-auth.md)
98

99
### Basic Authentication
100

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

103
```kotlin { .api }
104
fun AuthConfig.basic(block: BasicAuthConfig.() -> Unit)
105

106
class BasicAuthCredentials(
107
    val username: String,
108
    val password: String
109
)
110

111
class BasicAuthConfig {
112
    var realm: String?
113
    fun credentials(block: suspend () -> BasicAuthCredentials?)
114
    fun sendWithoutRequest(block: (HttpRequestBuilder) -> Boolean)
115
}
116
```
117

118
[Basic Authentication](./basic-auth.md)
119

120
### Digest Authentication
121

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

124
```kotlin { .api }
125
fun AuthConfig.digest(block: DigestAuthConfig.() -> Unit)
126

127
class DigestAuthCredentials(
128
    val username: String,
129
    val password: String
130
)
131

132
class DigestAuthConfig {
133
    var algorithmName: String
134
    var realm: String?
135
    fun credentials(block: suspend () -> DigestAuthCredentials?)
136
}
137
```
138

139
[Digest Authentication](./digest-auth.md)
140

141
## Types
142

143
```kotlin { .api }
144
interface AuthProvider {
145
    fun sendWithoutRequest(request: HttpRequestBuilder): Boolean
146
    fun isApplicable(auth: HttpAuthHeader): Boolean
147
    suspend fun addRequestHeaders(request: HttpRequestBuilder, authHeader: HttpAuthHeader? = null)
148
    suspend fun refreshToken(response: HttpResponse): Boolean
149
}
150

151
val AuthCircuitBreaker: AttributeKey<Unit>
152

153
val HttpClient.authProviders: List<AuthProvider>
154

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