0
# Ktor Server Authentication
1

2
Comprehensive authentication and authorization capabilities for Ktor server applications. This module provides support for multiple authentication mechanisms including Basic, Bearer, Form-based, Session-based, Digest, OAuth 1.0a, and OAuth 2.0 authentication through a flexible provider-based architecture.
3

4
## Package Information
5

6
- **Package Name**: ktor-server-auth-jvm
7
- **Package Type**: maven
8
- **Language**: Kotlin
9
- **Installation**: 
10
  ```kotlin
11
  implementation("io.ktor:ktor-server-auth-jvm:3.2.0")
12
  ```
13

14
## Core Imports
15

16
```kotlin
17
import io.ktor.server.auth.*
18
import io.ktor.server.application.*
19
import io.ktor.server.routing.*
20
```
21

22
## Basic Usage
23

24
```kotlin
25
import io.ktor.server.application.*
26
import io.ktor.server.auth.*
27
import io.ktor.server.routing.*
28
import io.ktor.server.response.*
29

30
fun Application.configureAuthentication() {
31
    install(Authentication) {
32
        basic("auth-basic") {
33
            realm = "Access to the '/' path"
34
            validate { credentials ->
35
                if (credentials.name == "admin" && credentials.password == "password") {
36
                    UserIdPrincipal(credentials.name)
37
                } else null
38
            }
39
        }
40
    }
41
    
42
    routing {
43
        authenticate("auth-basic") {
44
            get("/protected") {
45
                val principal = call.principal<UserIdPrincipal>()
46
                call.respond("Hello ${principal?.name}!")
47
            }
48
        }
49
    }
50
}
51
```
52

53
## Architecture
54

55
The Ktor authentication module follows a provider-based architecture:
56

57
- **Authentication Plugin**: Core plugin that manages multiple authentication providers
58
- **Authentication Providers**: Specific implementations for different auth mechanisms (Basic, Bearer, OAuth, etc.)
59
- **Authentication Context**: Manages authentication state and results during request processing
60
- **Principals**: Represent authenticated users/identities
61
- **Credentials**: Represent authentication data (username/password, tokens, etc.)
62
- **Challenge System**: Handles authentication failures and response generation
63

64
## Core Components
65

66
### Authentication Plugin
67

68
Main plugin for handling authentication and authorization.
69

70
```kotlin { .api }
71
object Authentication : BaseApplicationPlugin<Application, AuthenticationConfig, Authentication>
72

73
fun Application.authentication(block: AuthenticationConfig.() -> Unit)
74

75
class AuthenticationConfig {
76
    fun provider(name: String?, configure: DynamicProviderConfig.() -> Unit)
77
    fun register(provider: AuthenticationProvider)
78
}
79

80
class DynamicProviderConfig(name: String?) {
81
    fun authenticate(block: (context: AuthenticationContext) -> Unit)
82
}
83
```
84

85
### Authentication Context
86

87
```kotlin { .api }
88
val ApplicationCall.authentication: AuthenticationContext
89

90
inline fun <reified P : Any> ApplicationCall.principal(): P?
91
inline fun <reified P : Any> ApplicationCall.principal(provider: String?): P?
92

93
class AuthenticationContext {
94
    fun principal(principal: Any)
95
    fun principal(provider: String?, principal: Any)
96
    fun <T> principal(provider: String? = null): T?
97
    fun challenge(key: Any, cause: AuthenticationFailedCause, function: ChallengeFunction)
98
    fun error(key: Any, cause: AuthenticationFailedCause)
99
    val allErrors: List<AuthenticationFailedCause>
100
    val allFailures: List<AuthenticationFailedCause>
101
}
102
```
103

104
### Route Protection
105

106
```kotlin { .api }
107
fun Route.authenticate(
108
    vararg configurations: String? = arrayOf(null),
109
    optional: Boolean = false,
110
    build: Route.() -> Unit
111
): Route
112

113
fun Route.authenticate(
114
    vararg configurations: String? = arrayOf(null),
115
    strategy: AuthenticationStrategy,
116
    build: Route.() -> Unit
117
): Route
118

119
enum class AuthenticationStrategy {
120
    Optional, FirstSuccessful, Required
121
}
122

123
class AuthenticationRouteSelector(val names: List<String?>)
124

125
object AuthenticationChecked
126
```
127

128
## Capabilities
129

130
### Basic Authentication
131

132
HTTP Basic authentication with username and password validation.
133

134
```kotlin { .api }
135
fun AuthenticationConfig.basic(
136
    name: String? = null,
137
    configure: BasicAuthenticationProvider.Config.() -> Unit
138
)
139
```
140

141
[Basic Authentication](./basic-auth.md)
142

143
### Bearer Token Authentication
144

145
Bearer token authentication for API access tokens and JWT tokens.
146

147
```kotlin { .api }
148
fun AuthenticationConfig.bearer(
149
    name: String? = null,
150
    configure: BearerAuthenticationProvider.Config.() -> Unit
151
)
152
```
153

154
[Bearer Authentication](./bearer-auth.md)
155

156
### Form and Session Authentication
157

158
Form-based and session-based authentication for web applications.
159

160
```kotlin { .api }
161
fun AuthenticationConfig.form(
162
    name: String? = null,
163
    configure: FormAuthenticationProvider.Config.() -> Unit
164
)
165

166
fun <T : Any> AuthenticationConfig.session(
167
    name: String? = null,
168
    configure: SessionAuthenticationProvider.Config<T>.() -> Unit
169
)
170
```
171

172
[Form and Session Authentication](./form-session-auth.md)
173

174
### OAuth Authentication
175

176
OAuth 1.0a and OAuth 2.0 support for third-party authentication providers.
177

178
```kotlin { .api }
179
fun AuthenticationConfig.oauth(
180
    name: String? = null,
181
    configure: OAuthAuthenticationProvider.Config.() -> Unit
182
)
183
```
184

185
[OAuth Authentication](./oauth.md)
186

187
### JVM-Specific Features
188

189
Digest authentication and comprehensive OAuth 1.0a support available only on JVM platform.
190

191
```kotlin { .api }
192
fun AuthenticationConfig.digest(
193
    name: String? = null,
194
    configure: DigestAuthenticationProvider.Config.() -> Unit
195
)
196
```
197

198
[JVM-Specific Features](./jvm-features.md)
199

200
## Common Types
201

202
### Credentials
203

204
```kotlin { .api }
205
data class UserPasswordCredential(val name: String, val password: String)
206
data class BearerTokenCredential(val token: String)
207
```
208

209
### Principals
210

211
```kotlin { .api }
212
data class UserIdPrincipal(val name: String)
213
```
214

215
### Utility Classes
216

217
```kotlin { .api }
218
class UserHashedTableAuth(
219
    table: Map<String, ByteArray>,
220
    digester: (String) -> String
221
) {
222
    fun authenticate(credential: UserPasswordCredential): UserIdPrincipal?
223
}
224
```
225

226
### Header Utilities
227

228
```kotlin { .api }
229
fun ApplicationRequest.parseAuthorizationHeader(): HttpAuthHeader?
230
```
231

232
### Authentication Results
233

234
```kotlin { .api }
235
sealed class AuthenticationFailedCause {
236
    data object NoCredentials : AuthenticationFailedCause()
237
    data object InvalidCredentials : AuthenticationFailedCause()
238
    open class Error(val message: String) : AuthenticationFailedCause()
239
}
240

241
typealias ChallengeFunction = suspend PipelineContext<*, ApplicationCall>.(String, String) -> Unit
242
typealias AuthenticationFunction<C> = suspend ApplicationCall.(C) -> Any?
243
typealias ApplicationCallPredicate = (ApplicationCall) -> Boolean
244
```
245

246
### Response Types
247

248
```kotlin { .api }
249
class UnauthorizedResponse(
250
    challenge: HttpAuthHeader = HttpAuthHeader.basicAuthChallenge("Ktor Server")
251
) : HttpStatusCodeContent
252

253
class ForbiddenResponse(message: String = "Forbidden") : HttpStatusCodeContent
254
```
255

256
## Platform Availability
257

258
- **Common**: Basic, Bearer, Form, Session authentication, OAuth 2.0
259
- **JVM Only**: Digest authentication, OAuth 1.0a
260
- **JS/WASM/Native**: Limited OAuth support through platform-specific implementations