Ktor Server 中的表单身份验证
所需依赖项:io.ktor:ktor-server-auth
代码示例: auth-form-html-dsl、 auth-form-session
原生服务器Ktor 支持 Kotlin/Native,并允许您在无需额外运行时或虚拟机的情况下运行服务器。支持:✅
表单身份验证使用 Web 表单收集凭据信息并对用户进行身份验证。 要在 Ktor 中创建 Web 表单,可以使用 HTML DSL,或者在 JVM 模板引擎(如 FreeMarker、Velocity 等)中进行选择。
鉴于在使用表单身份验证时用户名和密码以明文形式传输,你需要使用 HTTPS/TLS 来保护敏感信息。
添加依赖项
要启用 form 身份验证,需要在构建脚本中包含 ktor-server-auth 构件:
表单身份验证流程
表单身份验证流程大致如下:
未经身份验证的客户端向服务器应用程序中的特定路由发起请求。
服务器返回一个至少包含基于 HTML 的 Web 表单的 HTML 页面,提示用户输入用户名和密码。
Ktor 允许你使用 Kotlin DSL 构建表单,或者也可以在各种 JVM 模板引擎(如 FreeMarker、Velocity 等)之间进行选择。
当用户提交用户名和密码后,客户端向服务器发起包含 Web 表单数据(其中包括用户名和密码)的请求。
kotlinPOST http://localhost:8080/login Content-Type: application/x-www-form-urlencoded username=jetbrains&password=foobar在 Ktor 中,你需要指定形参名称,用于获取用户名和密码。
服务器验证客户端发送的凭据并响应所请求的内容。
安装表单身份验证
要安装 form 身份验证提供程序,请在 install 块内调用 form 函数:
import io.ktor.server.application.*
import io.ktor.server.auth.*
// ...
install(Authentication) {
form {
// 配置表单身份验证
}
}你可以选择指定提供程序名称,该名称可用于对指定路由进行身份验证。
配置表单身份验证
第 1 步:配置表单提供程序
form 身份验证提供程序通过 FormAuthenticationProvider.Config 类公开其设置。在以下示例中,指定了以下设置:
userParamName和passwordParamName属性指定用于获取用户名和密码的形参名称。validate函数验证用户名和密码。validate函数检查UserPasswordCredential,并在身份验证成功时返回UserIdPrincipal,若身份验证失败则返回null。challenge函数指定在身份验证失败时执行的操作。例如,你可以重定向回登录页面或发送 UnauthorizedResponse。
install(Authentication) {
form("auth-form") {
userParamName = "username"
passwordParamName = "password"
validate { credentials ->
val isValid = credentials.name == "jetbrains" &&
credentials.password == "foobar"
if (isValid) {
UserIdPrincipal(credentials.name)
} else {
null
}
}
challenge {
val message = "Credentials are not valid"
val status = HttpStatusCode.Unauthorized
call.respond(status, message)
}
}
}类型安全身份验证方案 API 是一项实验性功能。它可能会随时被移除或更改。 需要显式选择启用 (Opt-in)。有关更多详情,请参阅 类型安全身份验证文档。
form() 函数为你选择的 Principal 类型创建方案。无需 install(Authentication) 步骤:该方案是一个值,你可以直接传递给需要它的路由。
data class User(val name: String)
val formAuth = form<User>("auth-form") {
usernameField = "username"
passwordField = "password"
validate { credentials ->
val isValid = credentials.name == "jetbrains" &&
credentials.password == "foobar"
if (isValid) User(credentials.name) else null
}
onUnauthorized = {
val message = "Credentials are not valid"
call.respond(HttpStatusCode.Unauthorized, message)
}
}有两个名称与经典提供程序不同。表单字段为 usernameField 和 passwordField,而非 userParamName 和 passwordParamName。失败处理程序为 onUnauthorized 而非 challenge。有关完整 API,请参阅类型安全身份验证。
与 basic 身份验证相同,你也可以使用 UserHashedTableAuth 来验证保存在内存表中(存储用户名与密码哈希)的用户。
第 2 步:保护特定资源
配置 form 提供程序后,你需要定义接收数据的 post 路由。 然后,将此路由添加到 authenticate 函数内部。 在身份验证成功的情况下,可以在路由处理程序内使用 call.principal 函数检索已验证的 UserIdPrincipal,并获取已验证用户的名称。
routing {
authenticate("auth-form") {
post("/login") {
val user = call.principal<UserIdPrincipal>()
call.respondText("Hello, ${user?.name}!")
}
}
}定义发送表单数据的 post 路由,并将其包装在 authenticateWith() 中。在该代码块内部, call.principal 即为你的 Principal 类型且绝不为 null:
routing {
authenticateWith(formAuth) {
post("/login") {
call.respondText("Hello, ${call.principal.name}!")
}
}
}你可以使用 Session 身份验证来存储已登录用户的 ID。 例如,当用户首次使用 Web 表单登录时,你可以将用户名保存到 Cookie 会话中,并在后续请求中使用 session 提供程序授权该用户。
