0
# Authentication
1

2
HTTP authentication header parsing and generation supporting Basic, Bearer, Digest, and custom authentication schemes with parameter handling and encoding options.
3

4
## Capabilities
5

6
### HttpAuthHeader Base Class
7

8
Abstract base class for HTTP authentication headers with rendering support.
9

10
```kotlin { .api }
11
/**
12
 * Base class for HTTP authentication headers
13
 */
14
abstract class HttpAuthHeader {
15
    /**
16
     * Authentication scheme name (e.g., "Basic", "Bearer")
17
     */
18
    val authScheme: String
19
    
20
    /**
21
     * Render header value with default encoding
22
     */
23
    abstract fun render(): String
24
    
25
    /**
26
     * Render header value with specified encoding
27
     * @param encoding header value encoding strategy
28
     */
29
    abstract fun render(encoding: HeaderValueEncoding): String
30
    
31
    companion object {
32
        /**
33
         * Create Basic authentication challenge
34
         * @param realm authentication realm
35
         * @param charset character set for encoding
36
         */
37
        fun basicAuthChallenge(
38
            realm: String,
39
            charset: Charset = Charsets.UTF_8
40
        ): Parameterized
41
        
42
        /**
43
         * Create Bearer authentication challenge
44
         * @param realm optional realm
45
         * @param scope optional scope
46
         */
47
        fun bearerAuthChallenge(
48
            realm: String? = null,
49
            scope: String? = null
50
        ): HttpAuthHeader
51
        
52
        /**
53
         * Create Digest authentication challenge
54
         * @param realm authentication realm
55
         * @param nonce server nonce value
56
         * @param domain list of protected URIs
57
         * @param opaque opaque value
58
         * @param stale whether credentials are stale
59
         * @param algorithm digest algorithm
60
         */
61
        fun digestAuthChallenge(
62
            realm: String,
63
            nonce: String,
64
            domain: List<String> = emptyList(),
65
            opaque: String? = null,
66
            stale: Boolean? = null,
67
            algorithm: String? = null
68
        ): Parameterized
69
    }
70
}
71
```
72

73
### Single Authentication Header
74

75
Simple authentication header with single blob value.
76

77
```kotlin { .api }
78
/**
79
 * Simple authentication header with blob value
80
 */
81
class HttpAuthHeader.Single(
82
    authScheme: String,
83
    val blob: String
84
) : HttpAuthHeader {
85
    
86
    override fun render(): String
87
    override fun render(encoding: HeaderValueEncoding): String
88
}
89
```
90

91
### Parameterized Authentication Header
92

93
Authentication header with parameters for complex schemes like Digest.
94

95
```kotlin { .api }
96
/**
97
 * Authentication header with parameters
98
 */
99
class HttpAuthHeader.Parameterized(
100
    authScheme: String,
101
    val parameters: List<HeaderValueParam>,
102
    val encoding: HeaderValueEncoding = HeaderValueEncoding.QUOTED_WHEN_REQUIRED
103
) : HttpAuthHeader {
104
    
105
    /**
106
     * Constructor from parameter map
107
     */
108
    constructor(
109
        authScheme: String,
110
        parameters: Map<String, String>,
111
        encoding: HeaderValueEncoding = HeaderValueEncoding.QUOTED_WHEN_REQUIRED
112
    )
113
    
114
    /**
115
     * Get parameter value by name
116
     * @param name parameter name
117
     * @return parameter value or null
118
     */
119
    fun parameter(name: String): String?
120
    
121
    /**
122
     * Add parameter to header
123
     * @param name parameter name
124
     * @param value parameter value
125
     * @return new Parameterized header with added parameter
126
     */
127
    fun withParameter(name: String, value: String): Parameterized
128
    
129
    /**
130
     * Replace parameter in header
131
     * @param name parameter name
132
     * @param value new parameter value
133
     * @return new Parameterized header with replaced parameter
134
     */
135
    fun withReplacedParameter(name: String, value: String): Parameterized
136
    
137
    override fun render(): String
138
    override fun render(encoding: HeaderValueEncoding): String
139
}
140
```
141

142
### Authentication Schemes
143

144
Constants for standard authentication schemes.
145

146
```kotlin { .api }
147
/**
148
 * Standard authentication scheme names
149
 */
150
object AuthScheme {
151
    const val Basic: String = "Basic"
152
    const val Bearer: String = "Bearer"
153
    const val Digest: String = "Digest"
154
    const val OAuth: String = "OAuth"
155
    const val Negotiate: String = "Negotiate"
156
}
157
```
158

159
### Authentication Parameters
160

161
Constants for standard authentication parameters.
162

163
```kotlin { .api }
164
/**
165
 * Standard authentication header parameters
166
 */
167
object HttpAuthHeader.Parameters {
168
    const val Realm: String = "realm"
169
    const val Charset: String = "charset"
170
    
171
    // OAuth parameters
172
    const val OAuthCallback: String = "oauth_callback"
173
    const val OAuthCallbackConfirmed: String = "oauth_callback_confirmed"
174
    const val OAuthConsumerKey: String = "oauth_consumer_key"
175
    const val OAuthNonce: String = "oauth_nonce"
176
    const val OAuthSignature: String = "oauth_signature"
177
    const val OAuthSignatureMethod: String = "oauth_signature_method"
178
    const val OAuthTimestamp: String = "oauth_timestamp"
179
    const val OAuthToken: String = "oauth_token"
180
    const val OAuthTokenSecret: String = "oauth_token_secret"
181
    const val OAuthVerifier: String = "oauth_verifier"
182
    const val OAuthVersion: String = "oauth_version"
183
}
184
```
185

186
### Header Value Encoding
187

188
Encoding strategies for authentication header values.
189

190
```kotlin { .api }
191
/**
192
 * Header value encoding strategies
193
 */
194
enum class HeaderValueEncoding {
195
    /**
196
     * Quote values only when required by RFC
197
     */
198
    QUOTED_WHEN_REQUIRED,
199
    
200
    /**
201
     * Always quote values
202
     */
203
    QUOTED_ALWAYS,
204
    
205
    /**
206
     * URI encode values
207
     */
208
    URI_ENCODE
209
}
210
```
211

212
### Authorization Header Parsing
213

214
Functions for parsing Authorization and WWW-Authenticate headers.
215

216
```kotlin { .api }
217
/**
218
 * Parse Authorization header value
219
 * @param headerValue header value string
220
 * @return HttpAuthHeader instance or null if invalid
221
 */
222
fun parseAuthorizationHeader(headerValue: String): HttpAuthHeader?
223

224
/**
225
 * Parse multiple authorization headers
226
 * @param headerValue header value string
227
 * @return List of HttpAuthHeader instances
228
 */
229
fun parseAuthorizationHeaders(headerValue: String): List<HttpAuthHeader>
230
```
231

232
**Usage Examples:**
233

234
```kotlin
235
import io.ktor.http.auth.*
236
import io.ktor.http.*
237
import java.util.*
238

239
// Create Basic authentication challenge
240
val basicChallenge = HttpAuthHeader.basicAuthChallenge(
241
    realm = "Secure Area",
242
    charset = Charsets.UTF_8
243
)
244
println(basicChallenge.render()) // Basic realm="Secure Area"
245

246
// Create Bearer authentication challenge
247
val bearerChallenge = HttpAuthHeader.bearerAuthChallenge(
248
    realm = "api",
249
    scope = "read write"
250
)
251
println(bearerChallenge.render()) // Bearer realm="api" scope="read write"
252

253
// Create Digest authentication challenge
254
val digestChallenge = HttpAuthHeader.digestAuthChallenge(
255
    realm = "Protected Area",
256
    nonce = UUID.randomUUID().toString(),
257
    domain = listOf("/api", "/secure"),
258
    opaque = "opaque-value",
259
    stale = false,
260
    algorithm = "MD5"
261
)
262

263
// Create custom parameterized header
264
val customAuth = HttpAuthHeader.Parameterized(
265
    authScheme = "Custom",
266
    parameters = mapOf(
267
        "token" to "abc123",
268
        "expires" to "3600"
269
    ),
270
    encoding = HeaderValueEncoding.QUOTED_ALWAYS
271
)
272

273
// Add parameters to existing header
274
val updatedAuth = digestChallenge.withParameter("qop", "auth")
275
val replacedAuth = updatedAuth.withReplacedParameter("nonce", "new-nonce")
276

277
// Access parameters
278
val realm = digestChallenge.parameter("realm") // "Protected Area"
279
val nonce = digestChallenge.parameter("nonce")
280

281
// Create simple auth header
282
val apiKeyAuth = HttpAuthHeader.Single(
283
    authScheme = "ApiKey",
284
    blob = "key-12345"
285
)
286

287
// Parse authorization headers
288
val authHeaderValue = "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
289
val parsedAuth = parseAuthorizationHeader(authHeaderValue)
290

291
when (parsedAuth) {
292
    is HttpAuthHeader.Single -> {
293
        println("Scheme: ${parsedAuth.authScheme}")
294
        println("Token: ${parsedAuth.blob}")
295
    }
296
    is HttpAuthHeader.Parameterized -> {
297
        println("Scheme: ${parsedAuth.authScheme}")
298
        parsedAuth.parameters.forEach { param ->
299
            println("${param.name}: ${param.value}")
300
        }
301
    }
302
}
303

304
// Parse multiple auth headers
305
val multiAuthValue = "Basic dXNlcjpwYXNz, Bearer token123"
306
val parsedHeaders = parseAuthorizationHeaders(multiAuthValue)
307

308
// Render with different encodings
309
val header = HttpAuthHeader.Parameterized(
310
    authScheme = "Test",
311
    parameters = mapOf("value" to "needs quoting")
312
)
313
println(header.render(HeaderValueEncoding.QUOTED_WHEN_REQUIRED))
314
println(header.render(HeaderValueEncoding.QUOTED_ALWAYS))
315
println(header.render(HeaderValueEncoding.URI_ENCODE))
316

317
// Use in HTTP headers
318
val headers = headers {
319
    append(HttpHeaders.Authorization, parsedAuth.render())
320
    append(HttpHeaders.WWWAuthenticate, basicChallenge.render())
321
}
322

323
// Common authentication patterns
324
fun createBasicAuth(username: String, password: String): HttpAuthHeader.Single {
325
    val credentials = "$username:$password"
326
    val encoded = Base64.getEncoder().encodeToString(credentials.toByteArray())
327
    return HttpAuthHeader.Single(AuthScheme.Basic, encoded)
328
}
329

330
fun createBearerAuth(token: String): HttpAuthHeader.Single {
331
    return HttpAuthHeader.Single(AuthScheme.Bearer, token)
332
}
333

334
// Usage
335
val basicAuth = createBasicAuth("user", "password")
336
val bearerAuth = createBearerAuth("jwt-token-here")
337
```
338

339
## Types
340

341
All types are defined above in their respective capability sections.