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 构件:
implementation("io.ktor:ktor-server-auth-api-key:$ktor_version")
implementation("io.ktor:ktor-server-auth:$ktor_version")implementation "io.ktor:ktor-server-auth-api-key:$ktor_version"
implementation "io.ktor:ktor-server-auth:$ktor_version"<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 身份验证流程如下:
- 客户端向服务器应用程序中的特定路由发出请求,并在请求头中附带 API Key(通常为
X-API-Key)。 - 服务器使用自定义验证逻辑来验证该 API Key。
- 如果密钥有效,服务器将返回所请求的内容。如果密钥无效或缺失,服务器将返回
401 Unauthorized状态响应。
安装 API Key 身份验证
要安装 apiKey 身份验证提供程序,请在 install(Authentication) 块中调用 apiKey 函数:
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。
以下是一个最小示例:
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) 步骤:该方案是一个传递给需要它的路由的值。
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 指定自定义请求头:
apiKey("api-key-header") {
headerName = "X-Secret-Key"
validate { key ->
// ...
}
}val apiKeyAuth = apiKey<AppPrincipal>("api-key-header") {
headerName = "X-Secret-Key"
validate { key ->
// ...
}
}第 2 步:验证 API Key
验证逻辑取决于应用程序的要求。以下是常见的实现方法:
静态密钥比较
对于简单情况,可以直接与预定义的密钥进行比较:
apiKey {
validate { keyFromHeader ->
val expectedApiKey =
environment.config.property("api.key").getString()
keyFromHeader
.takeIf { it == expectedApiKey }
?.let { AppPrincipal(it) }
}
}请将敏感的 API Key 存储在配置文件或环境变量中,切勿写在源代码中。
数据库查询
如果有多个 API Key,可以针对数据库进行验证:
apiKey {
validate { keyFromHeader ->
// 在数据库中查找该密钥
val user = database.findUserByApiKey(keyFromHeader)
user?.let { UserIdPrincipal(it.username) }
}
}多重验证条件
你可以实现复杂的验证逻辑:
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 函数自定义在身份验证失败时发送的响应:
apiKey {
validate { key ->
// 验证逻辑
}
challenge { defaultScheme, realm ->
call.respond(
HttpStatusCode.Unauthorized,
"Invalid or missing API key"
)
}
}第 4 步:保护特定资源
配置好 apiKey 提供程序后,你可以使用 authenticate 函数保护应用程序中的特定资源。在身份验证成功的情况下,可以在路由处理程序中使用 call.principal 函数检索已通过身份验证的主体。
routing {
authenticate {
get("/") {
val principal = call.principal<AppPrincipal>()!!
val key = principal.key
call.respondText("Hello! Your key: $key")
}
}
}将该方案传递给 authenticateWith()。在代码块内,call.principal 即为你指定的主体类型且绝不会为 null,因此不需要使用 !!:
routing {
authenticateWith(apiKeyAuth) {
get("/") {
val key = call.principal.key
call.respondText("Hello! Your key: $key")
}
}
}API Key 身份验证示例
以下是 API Key 身份验证的完整最小示例:
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 身份验证时,请考虑以下最佳做法:
- 使用 HTTPS:始终通过 HTTPS 传输 API Key,以防止被拦截。
- 安全存储:切勿在源代码中硬编码 API Key。请使用环境变量或安全的配置管理方式。
- 密钥轮换:实现定期轮换 API Key 的机制。
- 速率限制:将 API Key 身份验证与速率限制相结合,以防止滥用。
- 日志记录:记录身份验证失败事件以进行安全监控,但切勿记录实际的 API Key。
- 密钥格式:对 API Key 使用加密安全的随机字符串(例如 UUID 或 Base64 编码的随机字节)。
- 多个密钥:考虑为每个用户针对不同的应用程序或用途支持多个 API Key。
- 过期时间:设置密钥过期机制以增强安全性。
