Ktor Server 中的 Basic 身份验证
所需依赖项:io.ktor:ktor-server-auth
代码示例:auth-basic、auth-basic-hash-table
Native 服务器Ktor 支持 Kotlin/Native,并允许您在无需额外运行时或虚拟机的情况下运行服务器。支持:✅
Basic 身份验证方案是用于访问控制和身份验证的 HTTP 框架 的一部分。在该方案中,用户凭据以经过 Base64 编码的用户名/密码对形式进行传输。
Ktor 允许您使用 Basic 身份验证来登录用户并保护特定的路由。您可以在 Ktor Server 中的身份验证与授权部分中获取有关 Ktor 身份验证的常规信息。
鉴于 Basic 身份验证以明文形式传递用户名和密码,您需要使用 HTTPS/TLS 来保护敏感信息。
添加依赖项
要启用 basic 身份验证,您需要在构建脚本中包含 ktor-server-auth 工件:
Basic 身份验证流程
Basic 身份验证流程如下所示:
客户端向服务器应用程序中的特定路由发起不带
Authorization标头的请求。服务器向客户端返回
401(Unauthorized,未授权)响应状态,并使用WWW-Authenticate响应标头指示使用 Basic 身份验证方案来保护该路由。典型的WWW-Authenticate标头如下所示:WWW-Authenticate: Basic realm="Access to the '/' path", charset="UTF-8"在 Ktor 中,您可以在配置
basic身份验证提供程序时,使用对应的属性指定 realm 和 charset。通常,客户端会显示一个登录对话框供用户输入凭据。然后,客户端发起带有
Authorization标头的请求,该标头包含使用 Base64 编码的用户名和密码对,例如:Authorization: Basic amV0YnJhaW5zOmZvb2Jhcg服务器验证客户端发送的凭据并返回请求的内容。
安装 Basic 身份验证
要安装 basic 身份验证提供程序,请在 install 块内调用 basic 函数:
import io.ktor.server.application.*
import io.ktor.server.auth.*
// ...
install(Authentication) {
basic {
// 配置 Basic 身份验证
}
}配置 Basic 身份验证
要大体了解如何在 Ktor 中配置不同的身份验证提供程序,请参阅配置身份验证。在本节中,我们将介绍 basic 身份验证提供程序的具体配置。
第 1 步:配置 Basic 提供程序
basic 身份验证提供程序通过 BasicAuthenticationProvider.Configuration 类公开其设置。在以下示例中,指定了以下设置:
realm属性设置要在WWW-Authenticate标头中传递的 realm。validate函数用于验证用户名和密码。
install(Authentication) {
basic("auth-basic") {
realm = "Access to the '/' path"
validate { credentials ->
val isValid = credentials.name == "jetbrains" &&
credentials.password == "foobar"
if (isValid) {
UserIdPrincipal(credentials.name)
} else {
null
}
}
}
}validate 函数会检查 UserPasswordCredential,并在身份验证成功时返回 UserIdPrincipal,如果身份验证失败则返回 null。
您也可以使用 UserHashedTableAuth 来验证保存在存储了用户名和密码哈希的内存表中的用户。
类型安全身份验证方案 API 是一项实验性功能。它可能随时被放弃或更改。 需要显式启用。有关更多详细信息,请参阅 类型安全身份验证文档。
basic() 函数为您选择的主体类型创建方案。这里没有 install(Authentication) 步骤:该方案是一个直接传递给需要它的路由的值。
data class User(val name: String)
val basicAuth = basic<User>("auth-basic") {
realm = "Access to the '/' path"
validate { credentials ->
val isValid = credentials.name == "jetbrains" &&
credentials.password == "foobar"
if (isValid) User(credentials.name) else null
}
}validate 函数会检查 UserPasswordCredential 并返回您的主体类型,如果身份验证失败则返回 null。有关完整 API,请参阅类型安全身份验证。
第 2 步:保护特定资源
配置 basic 提供程序后,您可以使用 authenticate 函数保护应用程序中的特定资源。在身份验证成功的情况下,您可以在路由处理程序内使用 call.principal 函数检索已验证的 UserIdPrincipal,并获取已验证用户的名称。
routing {
authenticate("auth-basic") {
get("/") {
val user = call.principal<UserIdPrincipal>()
call.respondText("Hello, ${user?.name}!")
}
}
}将该方案传递给 authenticateWith()。在块内部,call.principal 为您的主体类型且绝不会为 null,因此不需要进行类型转换或 null 检查:
routing {
authenticateWith(basicAuth) {
get("/") {
call.respondText("Hello, ${call.principal.name}!")
}
}
}使用 UserHashedTableAuth 进行验证
Ktor 允许您使用 UserHashedTableAuth 来验证保存在存储了用户名和密码哈希的内存表中的用户。这样即使您的数据源泄露,也不会危及用户密码。
要使用 UserHashedTableAuth 验证用户,请遵循以下步骤:
使用 getDigestFunction 函数创建具有指定算法和盐值提供程序的摘要函数:
kotlinval digestFunction = getDigestFunction("SHA-256") { "ktor${it.length}" }初始化
UserHashedTableAuth的新实例并指定以下属性:- 使用
table属性提供用户名和哈希密码表。 - 将摘要函数分配给
digester属性。
kotlinval hashedUserTable = UserHashedTableAuth( table = mapOf( "jetbrains" to digestFunction("foobar"), "admin" to digestFunction("password") ), digester = digestFunction )- 使用
在
validate函数中,调用 UserHashedTableAuth.authenticate 函数对用户进行身份验证,如果凭据有效则返回UserIdPrincipal实例:kotlininstall(Authentication) { basic("auth-basic-hashed") { realm = "Access to the '/' path" validate { credentials -> hashedUserTable.authenticate(credentials) } } }
