0
# Ktor Client Auth
1

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

4
## Package Information
5

6
- **Package Name**: io.ktor:ktor-client-auth-js
7
- **Package Type**: maven
8
- **Language**: Kotlin (targeting JavaScript)
9
- **Installation**: Add dependency to your `build.gradle.kts`:
10

11
```kotlin
12
implementation("io.ktor:ktor-client-auth-js:3.2.0")
13
```
14

15
## Core Imports
16

17
```kotlin
18
import io.ktor.client.plugins.auth.*
19
import io.ktor.client.plugins.auth.providers.*
20
```
21

22
## Basic Usage
23

24
```kotlin
25
import io.ktor.client.*
26
import io.ktor.client.plugins.auth.*
27
import io.ktor.client.plugins.auth.providers.*
28

29
// Create HTTP client with Basic authentication
30
val client = HttpClient {
31
    Auth {
32
        basic {
33
            credentials {
34
                BasicAuthCredentials("username", "password")
35
            }
36
        }
37
    }
38
}
39

40
// Create HTTP client with Bearer token authentication
41
val clientWithBearer = HttpClient {
42
    Auth {
43
        bearer {
44
            loadTokens {
45
                BearerTokens("access_token", "refresh_token")
46
            }
47
            refreshTokens { params ->
48
                // Refresh logic here
49
                BearerTokens("new_access_token", "new_refresh_token")
50
            }
51
        }
52
    }
53
}
54
```
55

56
## Architecture
57

58
Ktor Client Auth is built around several key components:
59

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

66
## Capabilities
67

68
### Plugin Installation and Configuration
69

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

72
```kotlin { .api }
73
val Auth: ClientPlugin<AuthConfig>
74

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

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

82
val AuthCircuitBreaker: AttributeKey<Unit>
83
```
84

85
[Plugin Configuration](./plugin-configuration.md)
86

87
### Basic Authentication
88

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

91
```kotlin { .api }
92
fun AuthConfig.basic(block: BasicAuthConfig.() -> Unit)
93

94
class BasicAuthConfig {
95
    var realm: String?
96
    fun credentials(block: suspend () -> BasicAuthCredentials?)
97
    fun sendWithoutRequest(block: (HttpRequestBuilder) -> Boolean)
98
}
99

100
class BasicAuthCredentials(
101
    val username: String,
102
    val password: String
103
)
104

105
class BasicAuthProvider : AuthProvider
106
```
107

108
[Basic Authentication](./basic-authentication.md)
109

110
### Bearer Token Authentication
111

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

114
```kotlin { .api }
115
fun AuthConfig.bearer(block: BearerAuthConfig.() -> Unit)
116

117
class BearerAuthConfig {
118
    var realm: String?
119
    fun refreshTokens(block: suspend RefreshTokensParams.() -> BearerTokens?)
120
    fun loadTokens(block: suspend () -> BearerTokens?)
121
    fun sendWithoutRequest(block: (HttpRequestBuilder) -> Boolean)
122
}
123

124
class BearerTokens(
125
    val accessToken: String,
126
    val refreshToken: String?
127
)
128

129
class RefreshTokensParams(
130
    val client: HttpClient,
131
    val response: HttpResponse,
132
    val oldTokens: BearerTokens?
133
) {
134
    fun HttpRequestBuilder.markAsRefreshTokenRequest()
135
}
136

137
class BearerAuthProvider : AuthProvider
138
```
139

140
[Bearer Authentication](./bearer-authentication.md)
141

142
### Digest Authentication
143

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

146
```kotlin { .api }
147
fun AuthConfig.digest(block: DigestAuthConfig.() -> Unit)
148

149
class DigestAuthConfig {
150
    var algorithmName: String
151
    var realm: String?
152
    fun credentials(block: suspend () -> DigestAuthCredentials?)
153
}
154

155
class DigestAuthCredentials(
156
    val username: String,
157
    val password: String
158
)
159

160
class DigestAuthProvider : AuthProvider
161
```
162

163
[Digest Authentication](./digest-authentication.md)
164

165
## Core Types
166

167
```kotlin { .api }
168
interface AuthProvider {
169
    fun sendWithoutRequest(request: HttpRequestBuilder): Boolean
170
    fun isApplicable(auth: HttpAuthHeader): Boolean
171
    suspend fun addRequestHeaders(request: HttpRequestBuilder, authHeader: HttpAuthHeader? = null)
172
    suspend fun refreshToken(response: HttpResponse): Boolean
173
}
174

175
val HttpClient.authProviders: List<AuthProvider>
176

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