类型安全身份验证
所需依赖项:io.ktor:ktor-server-auth
Ktor 提供了类型安全身份验证方案 API,可将身份验证方案绑定到主体类型。您只需创建一次方案,将其传递给路由,即可读取主体,无需类型转换或 null 检查。
此 API 是 install(Authentication) 方式的替代方案。两种 API 均可在同一个应用程序中使用,并且您可以将使用其中一种 API 的路由嵌套在使用另一种 API 的路由内。
添加依赖项
要使用类型化身份验证,请在构建脚本中添加 ktor-server-auth 构件:
如果使用 jwt 方案,请添加 ktor-server-auth-jwt 构件:
如果使用 apiKey 方案,请添加 ktor-server-auth-api-key 构件:
implementation(ktorLibs.server.auth.apiKey)implementation ktorLibs.server.auth.apiKey<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-auth-api-key-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>启用此 API
此 API 标有 @ExperimentalKtorApi,因此您必须显式选择启用:
@OptIn(ExperimentalKtorApi::class)
fun Application.module() {
// ...
}路由构建器使用 Kotlin 上下文形参 (context parameters)。Kotlin 2.4.0 默认启用上下文形参。在 Kotlin 2.2.x 或 2.3.x 中,请在构建脚本中启用它们:
kotlin {
compilerOptions {
freeCompilerArgs.add("-Xcontext-parameters")
}
}定义主体
主体 (Principal) 表示您的应用程序与已通过身份验证的调用方关联的身份或其他信息。主体类型必须为非 null。
data class User(
val id: String,
val email: String
)创建方案
每种身份验证方法都提供一个工厂函数,该函数接受主体类型、名称和配置代码块。validate {} 代码块返回您的主体类型,或者在凭据被拒绝时返回 null:
val jwtAuth = jwt<User>("my-jwt") {
realm = "my-app"
verifier(jwkProvider, issuer)
validate { credential ->
val payload = credential.payload
User(
id = payload.subject,
email = payload.getClaim("email").asString()
)
}
}该工厂函数会返回一个值。请将其保存并传递给需要它的路由。
| 工厂函数 | 构件 | 说明 |
|---|---|---|
basic<P>() | ktor-server-auth | 参阅 Ktor Server 中的 Basic 身份验证 |
digest<P>() | ktor-server-auth | 仅限 JVM。参阅 Ktor Server 中的 Digest 身份验证 |
bearer<P>() | ktor-server-auth | 参阅 Ktor Server 中的 Bearer 身份验证 |
form<P>() | ktor-server-auth | 参阅 Ktor Server 中的基于表单的身份验证 |
session<S, P>() | ktor-server-auth | 参阅类型安全 Session 身份验证 |
apiKey<P>() | ktor-server-auth-api-key | 参阅 API Key 身份验证 |
jwt<P>() | ktor-server-auth-jwt | 仅限 JVM。参阅 JSON Web Token |
oauth2(), oauth2Session<P, S>() | ktor-server-auth | 参阅 OAuth 2.0 流程 |
方案名称必须唯一。如果创建了两个同名的不同方案,则当路由尝试使用第二个方案时将会失败。
保护路由
要保护路由,请将方案传递给 authenticateWith() 函数。在代码块内,call.principal 具有方案所定义的主体类型,并且保证为非 null:
routing {
authenticateWith(jwtAuth) {
get("/profile") {
val user: User = call.principal
call.respondText(user.email)
}
}
}使身份验证变为可选
当某个路由需要同时为已登录和匿名调用方提供服务时,请使用 authenticateWithOptional() 函数。在代码块内,使用 call.principalOrNull 访问主体:
routing {
authenticateWithOptional(jwtAuth) {
get("/me") {
val user = call.principalOrNull
call.respondText(user?.email ?: "anonymous")
}
}
}不带凭据的请求会成功处理,且 call.principalOrNull 为 null。包含无效凭据的请求仍会失败。
接受多种方案
使用 authenticateWithAnyOf() 函数可以在同一路由上接受多种方案。Ktor 会按照您列出方案的顺序依次尝试,第一个成功的方案将提供主体。
所有方案生成的主体必须符合一个通用类型,您可以在调用时声明该类型:
interface AppUser {
val email: String
}
data class JwtUser(
override val email: String,
val id: String
) : AppUser
data class ApiUser(override val email: String) : AppUser
val jwtScheme = jwt<JwtUser>("my-jwt") { /* ... */ }
val apiKeyScheme = apiKey<ApiUser>("my-api-key") { /* ... */ }
routing {
// AppUser is
authenticateWithAnyOf<AppUser>(jwtScheme, apiKeyScheme) {
get("/profile") {
call.respondText(call.principal.email)
}
}
}在 authenticateWithAnyOf() 内部,仅 call.principal 可用。属于单个方案的额外内容(例如会话方案中的 call.session)不可用。
允许匿名调用方
使用 orAnonymous() 函数可以构建一个为没有凭据的调用方提供服务的方案。不带凭据的请求将获取您在代码块中返回的主体。包含无效凭据的请求仍会失败。
最终得到的方案,其主体类型是两者的公共超类型:
interface Identity
data class AuthenticatedUser(val id: String) : Identity
data class GuestUser(val label: String = "guest") : Identity
val feedAuth = jwt<AuthenticatedUser>("my-jwt") {
verifier(jwkProvider, issuer)
validate { credential ->
AuthenticatedUser(credential.payload.subject)
}
}.orAnonymous { GuestUser() }
routing {
authenticateWith(feedAuth) {
get("/feed") {
when (val user = call.principal) {
is AuthenticatedUser ->
call.respondText(user.id)
is GuestUser ->
call.respondText(user.label)
}
}
}
}转换主体
使用 mapPrincipal() 函数可以将主体转换为另一种类型,例如通过从数据库加载用户记录:
data class AppUser(val id: String, val email: String)
val appAuth = jwtAuth.mapPrincipal { jwtUser ->
userDirectory.find(jwtUser.id)?.let { row ->
AppUser(id = row.id, email = row.email)
}
}此转换仅在方案生成主体后才会运行。如果转换返回 null,请求将被拒绝并返回 401 Unauthorized。
检查角色
角色检查是可选启用的。定义一个实现 AuthenticationRole 的角色类型,然后使用 withRoles() 构建一个具有角色感知能力的方案:
enum class Role : AuthenticationRole {
User, Admin, Moderator
}
val roleAuth = jwtAuth.withRoles { user ->
roleService.resolveRoles(user.id)
}withRoles {} 代码块在身份验证成功后针对每个请求运行。可用它从数据库、缓存或主体本身加载角色。
使用 roles 形参声明路由所需的角色:
routing {
authenticateWith(roleAuth, roles = setOf(Role.Admin)) {
get("/admin") {
val userRoles: Set<Role> = call.principal.roles
call.respondText(userRoles.joinToString { it.name })
}
}
}通过身份验证但缺少所需角色的调用方将收到 403 Forbidden。调用方必须具备集合中的所有角色,而不仅是其中之一。
传递 roles = null 可以在不要求任何角色的情况下解析角色。当处理程序需要自行决定时,这非常有用:
authenticateWith(roleAuth, roles = null) {
get("/dashboard") {
if (Role.Admin in call.principal.roles) {
call.respondText("admin view")
} else {
call.respondText("user view")
}
}
}roles 属性仅在具有角色感知能力的路由中存在。在受普通方案保护的路由中,它将无法通过编译。
处理失败情况
可能会出现两种错误情况,它们会分别处理:
onUnauthorized在身份验证失败时运行。默认响应为401 Unauthorized。onForbidden在身份验证成功但调用方缺少所需角色时运行。默认响应为403 Forbidden。
在方案上设置处理程序以覆盖使用该方案的所有路由:
val jwtAuth = jwt<User>("my-jwt") {
verifier(jwkProvider, issuer)
validate { credential -> /* ... */ }
onUnauthorized = { cause ->
val message = cause.toString()
call.respond(HttpStatusCode.Unauthorized, message)
}
}
val roleAuth = jwtAuth.withRoles(
onForbidden = {
val forbidden = HttpStatusCode.Forbidden
call.respondText("Not allowed", status = forbidden)
}
) { user ->
roleService.resolveRoles(user.id)
}或者在单个路由上设置处理程序,这将覆盖方案级别的处理程序:
authenticateWith(
roleAuth,
roles = setOf(Role.Admin),
onUnauthorized = { call.respondRedirect("/login") },
onForbidden = {
val forbidden = HttpStatusCode.Forbidden
call.respondText("Admins only", status = forbidden)
},
) {
get("/admin") {
call.respondText(call.principal.email)
}
}Ktor 会按以下顺序查找未授权处理程序:
- 传递给
authenticateWith()的处理程序。 - 方案上配置的
onUnauthorized处理程序。 - 提供程序的默认质询。
如果它们均未响应,请求将失败并返回 401 Unauthorized。
对于 authenticateWithAnyOf(),处理程序会接收一个方案名称对应失败原因的映射,以便您可以报告每个方案失败的原因:
authenticateWithAnyOf<AppUser>(
jwtScheme,
apiKeyScheme,
onUnauthorized = { failures ->
val schemes = failures.keys.joinToString()
call.respond(HttpStatusCode.Unauthorized, schemes)
}
) {
get("/profile") { /* ... */ }
}与传统 API 结合使用
两种身份验证 API 均可在同一个应用程序中使用。您可以将类型安全路由嵌套在受命名提供程序 API 保护的路由中,也可以将基于提供程序的路由嵌套在类型安全路由中:
routing {
authenticate("auth-session") {
authenticateWith(basicAuth) {
get("/admin") {
val basicUser = call.principal
val sessionUser =
checkNotNull(call.principal<SessionUser>())
if (basicUser.name == sessionUser.name) {
call.respondText("You are ${basicUser.name}!")
} else {
call.respondText("Who are you?")
}
}
}
}
authenticate(basicAuth.name) {
get("/hello") {
val user = checkNotNull(call.principal<BasicUser>())
call.respondText("Hello ${user.name}!")
}
}
}嵌套的身份验证层会按顺序应用。
限制
- 该 API 处于实验阶段。它可能会在次要版本中发生更改。
- 该 API 使用了 Kotlin 上下文形参,需要 Kotlin 2.4.0 或
-Xcontext-parameters编译器选项。 authenticateWithAnyOf()函数仅提供call.principal。在其中无法使用方案特有的属性(如call.session)。- LDAP 提供程序没有对应的类型安全实现。请改为在类型化的
validate {}代码块内调用ldapAuthenticate()。
