Skip to content

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 构件:

kotlin
implementation(ktorLibs.server.auth)
上述代码段使用 Ktor 版本目录来指定 Ktor 依赖项。
groovy
implementation ktorLibs.server.auth
上述代码段使用 Ktor 版本目录来指定 Ktor 依赖项。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-server-auth-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

表单身份验证流程 ​

表单身份验证流程大致如下:

  1. 未经身份验证的客户端向服务器应用程序中的特定路由发起请求。

  2. 服务器返回一个至少包含基于 HTML 的 Web 表单的 HTML 页面,提示用户输入用户名和密码。

    Ktor 允许你使用 Kotlin DSL 构建表单,或者也可以在各种 JVM 模板引擎(如 FreeMarker、Velocity 等)之间进行选择。

  3. 当用户提交用户名和密码后,客户端向服务器发起包含 Web 表单数据(其中包括用户名和密码)的请求。

    kotlin
    POST http://localhost:8080/login
    Content-Type: application/x-www-form-urlencoded
    
    username=jetbrains&password=foobar

    在 Ktor 中,你需要指定形参名称,用于获取用户名和密码。

  4. 服务器验证客户端发送的凭据并响应所请求的内容。

安装表单身份验证 ​

要安装 form 身份验证提供程序,请在 install 块内调用 form 函数:

kotlin
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。
kotlin
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) 步骤:该方案是一个值,你可以直接传递给需要它的路由。

kotlin
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,并获取已验证用户的名称。

kotlin
routing {
    authenticate("auth-form") {
        post("/login") {
            val user = call.principal<UserIdPrincipal>()
            call.respondText("Hello, ${user?.name}!")
        }
    }
}

定义发送表单数据的 post 路由,并将其包装在 authenticateWith() 中。在该代码块内部, call.principal 即为你的 Principal 类型且绝不为 null:

kotlin
routing {
    authenticateWith(formAuth) {
        post("/login") {
            call.respondText("Hello, ${call.principal.name}!")
        }
    }
}

你可以使用 Session 身份验证来存储已登录用户的 ID。 例如,当用户首次使用 Web 表单登录时,你可以将用户名保存到 Cookie 会话中,并在后续请求中使用 session 提供程序授权该用户。