JSON Web Tokens
必需依赖项:io.ktor:ktor-server-auth、io.ktor:ktor-server-auth-jwt
代码示例: auth-jwt-hs256、 auth-jwt-rs256
原生服务器Ktor 支持 Kotlin/Native,并允许您在无需额外运行时或虚拟机的情况下运行服务器。支持:✖️
JSON Web Token (JWT) 是一项开放标准,定义了一种以 JSON 对象形式在各方之间安全传输信息的方式。由于此类信息使用共享密钥(通过 HS256 算法)或公钥/私钥对(例如 RS256)进行了签名,因此可以被验证和信任。
Ktor 可以处理在 Authorization 标头中使用 Bearer 模式传递的 JWT,并允许您:
- 验证 JSON Web Token 的签名;
- 对 JWT 载荷执行额外的验证。
您可以在 Ktor Server 中的身份验证与授权章节中获取关于 Ktor 身份验证与授权的常规信息。
如果令牌来自 OpenID Connect 提供商,Oidc 插件会从签发者 URL 解析 JWKS 端点,并在密钥轮换时对其进行刷新,因此您无需手动配置 JwkProvider。它还会拒绝作为访问令牌提供的 ID 令牌。请参阅 OpenID Connect 资源服务器。
添加依赖项
要启用 JWT 身份验证,您需要在构建脚本中包含 ktor-server-auth 和 ktor-server-auth-jwt 构件:
implementation("io.ktor:ktor-server-auth:$ktor_version")
implementation("io.ktor:ktor-server-auth-jwt:$ktor_version")implementation "io.ktor:ktor-server-auth:$ktor_version"
implementation "io.ktor:ktor-server-auth-jwt:$ktor_version"<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-auth-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>
<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-auth-jwt-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>JWT 授权流程
Ktor 中的 JWT 授权流程大致如下:
- 客户端携带凭据向服务器应用程序中的特定身份验证路由发起
POST请求。下面的示例展示了一个通过 JSON 传递凭据的 HTTP 客户端POST请求:HTTPPOST http://localhost:8080/login Content-Type: application/json { "username": "jetbrains", "password": "foobar" } - 如果凭据有效,服务器将生成一个 JSON Web Token 并使用指定的算法对其进行签名。例如,这可以是使用特定共享密钥的
HS256,也可以是使用公钥/私钥对的RS256。 - 服务器将生成的 JWT 发送给客户端。
- 客户端现在可以使用
Bearer模式在Authorization标头中携带 JSON Web Token 向受保护的资源发起请求。HTTPGET http://localhost:8080/hello Authorization: Bearer {{auth_token}} - 服务器接收请求并执行以下验证:
- 验证完成后,服务器返回受保护资源的内容。
安装 JWT
要安装 jwt 身份验证提供程序,请在 install 代码块中调用 jwt 函数:
import io.ktor.server.application.*
import io.ktor.server.auth.*
import io.ktor.server.auth.jwt.*
//...
install(Authentication) {
jwt {
// 配置 jwt 身份验证
}
}您可以选择指定一个提供程序名称,该名称可用于对指定路由进行身份验证。
配置 JWT
在本节中,我们将了解如何在 Ktor 服务器应用程序中使用 JSON Web Token。我们将演示两种对令牌进行签名的方法,因为它们在验证令牌时的机制略有不同:
- 使用带有指定共享密钥的
HS256。 - 使用带有公钥/私钥对的
RS256。
您可以在此处找到完整的项目:auth-jwt-hs256、auth-jwt-rs256。
第 1 步:配置 JWT 设置
要配置 JWT 相关的设置,您可以在配置文件中创建一个自定义的 jwt 组。例如,application.conf 文件可能如下所示:
jwt {
secret = "secret"
issuer = "http://0.0.0.0:8080/"
audience = "http://0.0.0.0:8080/hello"
realm = "Access to 'hello'"
}jwt {
privateKey = "MIIBVQIBADANBgkqhkiG9w0BAQEFAASCAT8wggE7AgEAAkEAtfJaLrzXILUg1U3N1KV8yJr92GHn5OtYZR7qWk1Mc4cy4JGjklYup7weMjBD9f3bBVoIsiUVX6xNcYIr0Ie0AQIDAQABAkEAg+FBquToDeYcAWBe1EaLVyC45HG60zwfG1S4S3IB+y4INz1FHuZppDjBh09jptQNd+kSMlG1LkAc/3znKTPJ7QIhANpyB0OfTK44lpH4ScJmCxjZV52mIrQcmnS3QzkxWQCDAiEA1Tn7qyoh+0rOO/9vJHP8U/beo51SiQMw0880a1UaiisCIQDNwY46EbhGeiLJR1cidr+JHl86rRwPDsolmeEF5AdzRQIgK3KXL3d0WSoS//K6iOkBX3KMRzaFXNnDl0U/XyeGMuUCIHaXv+n+Brz5BDnRbWS+2vkgIe9bUNlkiArpjWvX+2we"
issuer = "http://0.0.0.0:8080/"
audience = "http://0.0.0.0:8080/hello"
realm = "Access to 'hello'"
}请注意,密钥信息不应以明文形式存储在配置文件中。建议使用环境变量来指定此类参数。
您可以通过以下方式在代码中访问这些设置:
val jwtConfig = environment.config
val secret = jwtConfig.property("jwt.secret").getString()
val issuer = jwtConfig.property("jwt.issuer").getString()
val audience = jwtConfig
.property("jwt.audience").getString()
val myRealm = jwtConfig.property("jwt.realm").getString()val jwtConfig = environment.config
val privateKeyString = jwtConfig
.property("jwt.privateKey").getString()
val issuer = jwtConfig.property("jwt.issuer").getString()
val audience = jwtConfig
.property("jwt.audience").getString()
val myRealm = jwtConfig.property("jwt.realm").getString()第 2 步:生成令牌
要生成 JSON Web Token,您可以使用 JWTCreator.Builder。以下代码段展示了如何针对 HS256 和 RS256 算法执行此操作:
post("/login") {
val user = call.receive<User>()
// 检查用户名和密码
// ...
val expiresAt = System.currentTimeMillis() + 60000
val token = JWT.create()
.withAudience(audience)
.withIssuer(issuer)
.withClaim("username", user.username)
.withExpiresAt(Date(expiresAt))
.sign(Algorithm.HMAC256(secret))
call.respond(hashMapOf("token" to token))
}post("/login") {
val user = call.receive<User>()
// 检查用户名和密码
// ...
val keyId = "6f8856ed-9189-488f-9011-0ff4b6c08edc"
val publicKey = jwkProvider.get(keyId).publicKey
val decoded = Base64.getDecoder()
.decode(privateKeyString)
val keySpecPKCS8 = PKCS8EncodedKeySpec(decoded)
val privateKey = KeyFactory.getInstance("RSA")
.generatePrivate(keySpecPKCS8)
val algorithm = Algorithm.RSA256(
publicKey as RSAPublicKey,
privateKey as RSAPrivateKey
)
val expiresAt = System.currentTimeMillis() + 60000
val token = JWT.create()
.withAudience(audience)
.withIssuer(issuer)
.withClaim("username", user.username)
.withExpiresAt(Date(expiresAt))
.sign(algorithm)
call.respond(hashMapOf("token" to token))
}post("/login")定义了一个用于接收POST请求的身份验证路由。call.receive<User>()接收作为 JSON 对象发送的用户凭据,并将其转换为User类对象。JWT.create()使用指定的 JWT 设置生成令牌,添加包含所接收用户名的自定义 claim,并使用指定的算法对令牌进行签名:- 对于
HS256,使用共享密钥对令牌进行签名。 - 对于
RS256,使用公钥/私钥对。
- 对于
call.respond将令牌作为 JSON 对象发送给客户端。
第 3 步:配置 realm
realm 属性允许您设置在访问受保护路由时在 WWW-Authenticate 标头中传递的领域 (realm)。
val myRealm = jwtConfig.property("jwt.realm").getString()
install(Authentication) {
jwt("auth-jwt") {
realm = myRealm
}
}第 4 步:配置令牌验证程序
verifier 函数允许您验证令牌格式及其签名:
- 对于
HS256,您需要传递一个 JWTVerifier 实例来验证令牌。 - 对于
RS256,您需要传递 JwkProvider,它指定用于访问验证令牌所需公钥的 JWKS 端点。在我们的示例中,签发者为http://0.0.0.0:8080,因此 JWKS 端点地址将为http://0.0.0.0:8080/.well-known/jwks.json。
val jwtConfig = environment.config
val secret = jwtConfig.property("jwt.secret").getString()
val issuer = jwtConfig.property("jwt.issuer").getString()
val audience = jwtConfig
.property("jwt.audience").getString()
val myRealm = jwtConfig.property("jwt.realm").getString()
install(Authentication) {
jwt("auth-jwt") {
realm = myRealm
verifier(JWT
.require(Algorithm.HMAC256(secret))
.withAudience(audience)
.withIssuer(issuer)
.build())
}
}val issuer = jwtConfig.property("jwt.issuer").getString()
val audience = jwtConfig
.property("jwt.audience").getString()
val myRealm = jwtConfig.property("jwt.realm").getString()
val jwkProvider = JwkProviderBuilder(issuer)
.cached(10, 24, TimeUnit.HOURS)
.rateLimited(10, 1, TimeUnit.MINUTES)
.build()
install(Authentication) {
jwt("auth-jwt") {
realm = myRealm
verifier(jwkProvider, issuer) {
acceptLeeway(3)
}
}
}第 5 步:验证 JWT 载荷
validate函数允许您对 JWT 载荷执行验证。此函数是必需的:如果您未对其进行配置,提供程序初始化时将抛出IllegalArgumentException。检查credential形参,它表示一个包含 JWT 载荷的 JWTCredential 对象。在下面的示例中,检查了自定义usernameclaim 的值。kotlininstall(Authentication) { jwt("auth-jwt") { validate { credential -> val payload = credential.payload val claim = payload.getClaim("username") if (claim.asString() != "") { JWTPrincipal(credential.payload) } else { null } } } }身份验证成功时,返回 JWTPrincipal。
challenge函数允许您配置在身份验证失败时发送的响应。kotlininstall(Authentication) { jwt("auth-jwt") { challenge { defaultScheme, realm -> val text = "Token is not valid or has expired" val status = HttpStatusCode.Unauthorized call.respond(status, text) } } }
类型安全身份验证方案 API 目前为实验性功能。它可能随时被废弃或变更。 使用需要选择启用(Opt-in)。有关更多详细信息,请参阅 类型安全身份验证文档。
jwt() 函数为您所选的主体类型创建一个方案。没有 install(Authentication) 步骤:该方案是一个值,您可以将其传递给需要它的路由。
在 validate 中读取所需的 claim 并返回您自己的类型。然后路由处理程序将直接处理该类型, 而不是 JWTPrincipal:
data class User(val username: String, val expiresAt: Long?)
val jwtAuth = jwt<User>("auth-jwt") {
realm = myRealm
verifier(
JWT.require(Algorithm.HMAC256(secret))
.withAudience(audience)
.withIssuer(issuer)
.build()
)
validate { credential ->
val payload = credential.payload
val username = payload.getClaim("username").asString()
if (username != "") {
User(username, credential.expiresAt?.time)
} else {
null
}
}
onUnauthorized = {
val message = "Token is not valid or has expired"
call.respond(HttpStatusCode.Unauthorized, message)
}
}失败处理程序为 onUnauthorized 而不是 challenge。有关完整 API,请参阅类型安全身份验证。
第 6 步:保护特定资源
配置好 jwt 提供程序后,您可以使用 authenticate 函数来保护应用程序中的特定资源。在身份验证成功的情况下,您可以在路由处理程序内部使用 call.principal 函数检索已验证的 JWTPrincipal,并获取 JWT 载荷。在下面的示例中,检索了自定义 username claim 的值以及令牌过期时间。
routing {
authenticate("auth-jwt") {
get("/hello") {
val principal = call.principal<JWTPrincipal>()
val payload = principal!!.payload
val username = payload.getClaim("username")
.asString()
val now = System.currentTimeMillis()
val expiresAt = principal.expiresAt?.time
?.minus(now)
call.respondText(
"Hello, $username! " +
"Token is expired at $expiresAt ms."
)
}
}
}将该方案传递给 authenticateWith()。由于已经在 validate 中读取了 claim,因此处理程序可以使用您自己的类型,且不需要进行 null 检查:
routing {
authenticateWith(jwtAuth) {
get("/hello") {
val user = call.principal
val now = System.currentTimeMillis()
val expiresIn = user.expiresAt?.minus(now)
call.respondText(
"Hello, ${user.username}! " +
"Token is expired at $expiresIn ms."
)
}
}
}