Ktor 服务器中的基本认证

所需依赖项: io.ktor:ktor-server-auth

代码示例: auth-basic, auth-basic-hash-table

对原生服务器的支持

Ktor 支持 Kotlin/Native，允许您在没有额外运行时或虚拟机的情况下运行服务器。

: ✅

基本认证方案是 HTTP 框架 的一部分，用于访问控制和认证。在此方案中，用户凭据以使用 Base64 编码的用户名/密码对形式传输。

Ktor 允许您使用基本认证来登录用户和保护特定 路由。您可以在 Ktor 服务器中的认证和授权 部分获取有关 Ktor 认证的通用信息。

鉴于基本认证以明文形式传输用户名和密码，您需要使用 HTTPS/TLS 来保护敏感信息。

添加依赖项

要启用 basic 认证，您需要在构建脚本中包含 ktor-server-auth artifact：

Gradle (Kotlin)Gradle (Groovy)Maven

基本认证流程

基本认证流程如下所示：

1. 客户端向服务器应用程序中的特定 路由 发出不带 Authorization 请求头的请求。
2. 服务器以 401 (Unauthorized) 响应状态响应客户端，并使用 WWW-Authenticate 响应头提供信息，表明该路由受到 basic 认证方案的保护。典型的 WWW-Authenticate 请求头如下所示：

WWW-Authenticate: Basic realm="Access to the '/' path", charset="UTF-8"

在 Ktor 中，您可以在 配置 basic 认证提供者时，使用相应属性指定 realm 和 charset。

3. 通常，客户端会显示一个登录对话框，用户可以在其中输入凭据。然后，客户端发出一个包含使用 Base64 编码的用户名和密码对的 Authorization 请求头的请求，例如：

Authorization: Basic amV0YnJhaW5zOmZvb2Jhcg

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

安装基本认证

要安装 basic 认证提供者，请在 install 代码块中调用 basic 函数：

import io.ktor.server.application.*
import io.ktor.server.auth.*
// ...
install(Authentication) {
    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 ->
            if (credentials.name == "jetbrains" && credentials.password == "foobar") {
                UserIdPrincipal(credentials.name)
            } else {
                null
            }
        }
    }
}

validate 函数检测 UserPasswordCredential，并在认证成功的情况下返回 UserIdPrincipal，如果认证失败则返回 null。

您还可以使用 UserHashedTableAuth 来验证存储在保存用户名和密码哈希的内存表中的用户。

步骤 2：保护特定资源

配置 basic 提供者后，您可以使用 authenticate 函数保护应用程序中的特定资源。在认证成功的情况下，您可以使用 call.principal 函数在路由处理程序中检索已认证的 UserIdPrincipal，并获取已认证用户的名称。

routing {
    authenticate("auth-basic") {
        get("/") {
            call.respondText("Hello, ${call.principal<UserIdPrincipal>()?.name}!")
        }
    }
}

使用 UserHashedTableAuth 进行验证

Ktor 允许您使用 UserHashedTableAuth 来 验证 存储在保存用户名和密码哈希的内存表中的用户。如果您的数据源被泄露，这可以防止用户密码被泄露。

要使用 UserHashedTableAuth 验证用户，请遵循以下步骤：

1. 使用 getDigestFunction 函数创建具有指定算法和盐提供者的摘要函数：

val digestFunction = getDigestFunction("SHA-256") { "ktor${it.length}" }

2. 初始化 UserHashedTableAuth 的新实例并指定以下属性：
   • 使用 table 属性提供用户名和哈希密码表。
   • 将摘要函数分配给 digester 属性。

val hashedUserTable = UserHashedTableAuth(
    table = mapOf(
        "jetbrains" to digestFunction("foobar"),
        "admin" to digestFunction("password")
    ),
    digester = digestFunction
)

3. 在 validate 函数内部，调用 UserHashedTableAuth.authenticate 函数来认证用户，如果凭据有效则返回 UserIdPrincipal 的实例：

install(Authentication) {
    basic("auth-basic-hashed") {
        realm = "Access to the '/' path"
        validate { credentials ->
            hashedUserTable.authenticate(credentials)
        }
    }
}