Ktor Server 中的 Bearer 身份验证
必需依赖项:io.ktor:ktor-server-auth
代码示例: auth-bearer
原生服务器Ktor 支持 Kotlin/Native,并允许您在无需额外运行时或虚拟机的情况下运行服务器。支持:✅
Bearer 身份验证方案是用于访问控制和身份验证的 HTTP 框架的一部分。该方案涉及被称为 bearer 令牌的安全令牌。Bearer 身份验证方案可用作 OAuth 或 JWT 的一部分,但您也可以提供自定义逻辑来授权 bearer 令牌。
您可以在 Ktor Server 中的身份验证与授权章节中获取有关 Ktor 身份验证的总体信息。
Bearer 身份验证应仅在 HTTPS/TLS 上使用。
添加依赖项
要启用 bearer 身份验证,您需要在构建脚本中引入 ktor-server-auth 构件:
Bearer 身份验证流程
通常,Bearer 身份验证流程可能如下所示:
- 用户成功通过身份验证并授权访问后,服务器会向客户端返回一个访问令牌。
- 客户端可以使用
Bearer方案在Authorization请求头中传递令牌,向受保护资源发起请求。HTTPGET http://localhost:8080/ Authorization: Bearer abc123 - 服务器接收请求并验证令牌。
- 验证通过后,服务器将返回受保护资源的内容作为响应。
安装 bearer 身份验证
要安装 bearer 身份验证提供程序,请在 install 代码块中调用 bearer 函数:
import io.ktor.server.application.*
import io.ktor.server.auth.*
// ...
install(Authentication) {
bearer {
// Configure bearer authentication
}
}配置 bearer 身份验证
要初步了解如何在 Ktor 中配置不同的身份验证提供程序,请参阅配置身份验证。在本节中,我们将介绍 bearer 身份验证提供程序的具体配置。
第 1 步:配置 bearer 提供程序
bearer 身份验证提供程序通过 BearerAuthenticationProvider.Configuration 类公开其设置。在以下示例中,指定了以下设置:
realm属性设置要在WWW-Authenticate请求头中传递的 realm。authenticate函数用于检查客户端发送的令牌;如果身份验证成功,则返回UserIdPrincipal,若验证失败,则返回null。
install(Authentication) {
bearer("auth-bearer") {
realm = "Access to the '/' path"
authenticate { tokenCredential ->
if (tokenCredential.token == "abc123") {
UserIdPrincipal("jetbrains")
} else {
null
}
}
}
}类型安全的身份验证方案 API 为实验性功能。它可能随时被废弃或更改。 需要选择启用(Opt-in)。有关更多详细信息,请参阅 类型安全身份验证文档。
bearer() 函数会为您选择的主体(principal)类型创建一个方案。此方案无需 install(Authentication) 步骤:方案本身就是一个值,您可以将其传递给需要它的路由。
data class User(val name: String)
val bearerAuth = bearer<User>("auth-bearer") {
realm = "Access to the '/' path"
validate { tokenCredential ->
if (tokenCredential.token == "abc123") {
User("jetbrains")
} else {
null
}
}
}请注意名称上的变化:经典提供程序使用 authenticate,而类型安全方案与其他类型安全方案类似,使用的是 validate。它会返回您指定的主体类型;若身份验证失败,则返回 null。
您还可以设置 authHeader 以从 Authorization 请求头以外的位置读取令牌,并设置 authSchemes 以接受除 Bearer 以外的方案。有关完整 API,请参阅类型安全身份验证。
第 2 步:保护特定资源
配置好 bearer 提供程序后,您可以使用 authenticate 函数保护应用程序中的特定资源。在身份验证成功的情况下,可以在路由处理程序内使用 call.principal 函数检索已验证的 UserIdPrincipal,并获取已验证用户的名称。
routing {
authenticate("auth-bearer") {
get("/") {
val user = call.principal<UserIdPrincipal>()
call.respondText("Hello, ${user?.name}!")
}
}
}将方案传递给 authenticateWith()。在代码块内,call.principal 即为您的主体类型且绝不会为 null,因此不需要进行转换或 null 检查:
routing {
authenticateWith(bearerAuth) {
get("/") {
call.respondText("Hello, ${call.principal.name}!")
}
}
}