Skip to content

API Key 身份验证 ​

必需的依赖项: io.ktor:ktor-server-auth, io.ktor:ktor-server-auth-api-key

原生服务器Ktor 支持 Kotlin/Native,并允许您在无需额外运行时或虚拟机的情况下运行服务器。支持: ✅

API Key 身份验证是一种简单的身份验证方法,客户端在请求中(通常在请求头中)传递一个密钥。该密钥既用作标识符,也充当身份验证机制。

Ktor 允许你使用 API Key 身份验证来保护路由并验证客户端请求。

你可以在 Ktor Server 中的身份验证与授权部分获取有关 Ktor 身份验证的常规信息。

API Key 应保持保密并进行安全传输。建议使用 HTTPS/TLS 保护传输中的 API Key。

添加依赖项 ​

要启用 API Key 身份验证,请在构建脚本中添加 ktor-server-auth 和 ktor-server-auth-api-key 构件:

kotlin
implementation("io.ktor:ktor-server-auth-api-key:$ktor_version")
implementation("io.ktor:ktor-server-auth:$ktor_version")
Groovy
implementation "io.ktor:ktor-server-auth-api-key:$ktor_version"
implementation "io.ktor:ktor-server-auth:$ktor_version"
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-server-auth-api-key-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-server-auth</artifactId>
    <version>${ktor_version}</version>
</dependency>

API Key 身份验证流程 ​

API Key 身份验证流程如下:

  1. 客户端向服务器应用程序中的特定路由发出请求,并在请求头中附带 API Key(通常为 X-API-Key)。
  2. 服务器使用自定义验证逻辑来验证该 API Key。
  3. 如果密钥有效,服务器将返回所请求的内容。如果密钥无效或缺失,服务器将返回 401 Unauthorized 状态响应。

安装 API Key 身份验证 ​

要安装 apiKey 身份验证提供程序,请在 install(Authentication) 块中调用 apiKey 函数:

kotlin
import io.ktor.server.application.*
import io.ktor.server.auth.*
// ...
install(Authentication) {
    apiKey {
        // 配置 API Key 身份验证
    }
}

你也可以选择指定一个提供程序名称,用于对指定路由进行身份验证。

配置 API Key 身份验证 ​

在本节中,我们将介绍 apiKey 身份验证提供程序的具体配置。

要了解如何在 Ktor 中配置不同的身份验证提供程序,请参阅配置身份验证。

第 1 步:配置 API Key 提供程序 ​

apiKey 身份验证提供程序通过 ApiKeyAuthenticationProvider.Config 类公开其设置。在以下示例中,指定了如下设置:

  • validate 函数接收从请求中提取的 API Key,在身份验证成功时返回 Principal,若身份验证失败则返回 null。

以下是一个最小示例:

kotlin
data class AppPrincipal(val key: String) : Principal

install(Authentication) {
    apiKey {
        validate { keyFromHeader ->
            val expectedApiKey = "this-is-expected-key"
            keyFromHeader
                .takeIf { it == expectedApiKey }
                ?.let { AppPrincipal(it) }
        }
    }
}

类型安全的身份验证方案 API 目前为实验性功能。它可能随时被弃用或更改。 需要显式选择加入(Opt-in)。有关更多详细信息,请参阅 类型安全身份验证文档。

apiKey() 函数为你选择的主体(Principal)类型创建一个方案。这里没有 install(Authentication) 步骤:该方案是一个传递给需要它的路由的值。

kotlin
data class AppPrincipal(val key: String)

val apiKeyAuth = apiKey<AppPrincipal>("api-key") {
    validate { keyFromHeader ->
        val expectedApiKey = "this-is-expected-key"
        keyFromHeader
            .takeIf { it == expectedApiKey }
            ?.let { AppPrincipal(it) }
    }
}

与传统提供程序不同,该方案必须指定名称。有关完整的 API,请参阅类型安全身份验证。

自定义密钥位置 ​

默认情况下,apiKey 提供程序会在 X-API-Key 请求头中查找 API Key。

你可以使用 headerName 指定自定义请求头:

kotlin
apiKey("api-key-header") {
    headerName = "X-Secret-Key"
    validate { key ->
        // ...
    }
}
kotlin
val apiKeyAuth = apiKey<AppPrincipal>("api-key-header") {
    headerName = "X-Secret-Key"
    validate { key ->
        // ...
    }
}

第 2 步:验证 API Key ​

验证逻辑取决于应用程序的要求。以下是常见的实现方法:

静态密钥比较 ​

对于简单情况,可以直接与预定义的密钥进行比较:

kotlin
apiKey {
    validate { keyFromHeader ->
        val expectedApiKey = 
            environment.config.property("api.key").getString()
        keyFromHeader
            .takeIf { it == expectedApiKey }
            ?.let { AppPrincipal(it) }
    }
}

请将敏感的 API Key 存储在配置文件或环境变量中,切勿写在源代码中。

数据库查询 ​

如果有多个 API Key,可以针对数据库进行验证:

kotlin
apiKey {
    validate { keyFromHeader ->
        // 在数据库中查找该密钥
        val user = database.findUserByApiKey(keyFromHeader)
        user?.let { UserIdPrincipal(it.username) }
    }
}

多重验证条件 ​

你可以实现复杂的验证逻辑:

kotlin
apiKey {
    validate { keyFromHeader ->
        val apiKey = database.findApiKey(keyFromHeader)

        // 检查密钥是否存在、是否有效且未过期
        if (apiKey != null &&
            apiKey.isActive &&
            apiKey.expiresAt > Clock.System.now()
        ) {
            UserIdPrincipal(apiKey.userId)
        } else {
            null
        }
    }
}

第 3 步:配置质询 ​

你可以使用 challenge 函数自定义在身份验证失败时发送的响应:

kotlin
apiKey {
    validate { key ->
        // 验证逻辑
    }
    challenge { defaultScheme, realm ->
        call.respond(
            HttpStatusCode.Unauthorized,
            "Invalid or missing API key"
        )
    }
}

第 4 步:保护特定资源 ​

配置好 apiKey 提供程序后,你可以使用 authenticate 函数保护应用程序中的特定资源。在身份验证成功的情况下,可以在路由处理程序中使用 call.principal 函数检索已通过身份验证的主体。

kotlin
routing {
    authenticate {
        get("/") {
            val principal = call.principal<AppPrincipal>()!!
            val key = principal.key
            call.respondText("Hello! Your key: $key")
        }
    }
}

将该方案传递给 authenticateWith()。在代码块内,call.principal 即为你指定的主体类型且绝不会为 null,因此不需要使用 !!:

kotlin
routing {
    authenticateWith(apiKeyAuth) {
        get("/") {
            val key = call.principal.key
            call.respondText("Hello! Your key: $key")
        }
    }
}

API Key 身份验证示例 ​

以下是 API Key 身份验证的完整最小示例:

kotlin
import io.ktor.server.application.*
import io.ktor.server.auth.*
import io.ktor.server.response.*
import io.ktor.server.routing.*

data class AppPrincipal(val key: String) : Principal

fun Application.module() {
    val expectedApiKey = "this-is-expected-key"

    install(Authentication) {
        apiKey {
            validate { keyFromHeader ->
                keyFromHeader
                    .takeIf { it == expectedApiKey }
                    ?.let { AppPrincipal(it) }
            }
        }
    }

    routing {
        authenticate {
            get("/") {
                val principal = call.principal<AppPrincipal>()!!
                call.respondText("Key: ${principal.key}")
            }
        }
    }
}

最佳做法 ​

在实现 API Key 身份验证时,请考虑以下最佳做法:

  1. 使用 HTTPS:始终通过 HTTPS 传输 API Key,以防止被拦截。
  2. 安全存储:切勿在源代码中硬编码 API Key。请使用环境变量或安全的配置管理方式。
  3. 密钥轮换:实现定期轮换 API Key 的机制。
  4. 速率限制:将 API Key 身份验证与速率限制相结合,以防止滥用。
  5. 日志记录:记录身份验证失败事件以进行安全监控,但切勿记录实际的 API Key。
  6. 密钥格式:对 API Key 使用加密安全的随机字符串(例如 UUID 或 Base64 编码的随机字节)。
  7. 多个密钥:考虑为每个用户针对不同的应用程序或用途支持多个 API Key。
  8. 过期时间:设置密钥过期机制以增强安全性。