Skip to content
Server Plugin

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

kotlin
implementation("io.ktor:ktor-server-auth:$ktor_version")
implementation("io.ktor:ktor-server-auth-jwt:$ktor_version")
groovy
implementation "io.ktor:ktor-server-auth:$ktor_version"
implementation "io.ktor:ktor-server-auth-jwt:$ktor_version"
xml
<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 授权流程大致如下:

  1. 客户端携带凭据向服务器应用程序中的特定身份验证路由发起 POST 请求。下面的示例展示了一个通过 JSON 传递凭据的 HTTP 客户端 POST 请求:
    HTTP
    POST http://localhost:8080/login
    Content-Type: application/json
    
    {
      "username": "jetbrains",
      "password": "foobar"
    }
  2. 如果凭据有效,服务器将生成一个 JSON Web Token 并使用指定的算法对其进行签名。例如,这可以是使用特定共享密钥的 HS256,也可以是使用公钥/私钥对的 RS256。
  3. 服务器将生成的 JWT 发送给客户端。
  4. 客户端现在可以使用 Bearer 模式在 Authorization 标头中携带 JSON Web Token 向受保护的资源发起请求。
    HTTP
    GET http://localhost:8080/hello
    Authorization: Bearer {{auth_token}}
  5. 服务器接收请求并执行以下验证:
    • 验证令牌的签名。请注意,验证方式取决于对令牌签名时所使用的算法。
    • 对 JWT 载荷执行额外验证。
  6. 验证完成后,服务器返回受保护资源的内容。

安装 JWT ​

要安装 jwt 身份验证提供程序,请在 install 代码块中调用 jwt 函数:

kotlin
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'"
}

请注意,密钥信息不应以明文形式存储在配置文件中。建议使用环境变量来指定此类参数。

您可以通过以下方式在代码中访问这些设置:

kotlin
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()
kotlin
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 算法执行此操作:

kotlin
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))
}
kotlin
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))
}
  1. post("/login") 定义了一个用于接收 POST 请求的身份验证路由。
  2. call.receive<User>() 接收作为 JSON 对象发送的用户凭据,并将其转换为 User 类对象。
  3. JWT.create() 使用指定的 JWT 设置生成令牌,添加包含所接收用户名的自定义 claim,并使用指定的算法对令牌进行签名:
    • 对于 HS256,使用共享密钥对令牌进行签名。
    • 对于 RS256,使用公钥/私钥对。
  4. call.respond 将令牌作为 JSON 对象发送给客户端。

第 3 步:配置 realm ​

realm 属性允许您设置在访问受保护路由时在 WWW-Authenticate 标头中传递的领域 (realm)。

kotlin
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。
kotlin
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())
    }
}
kotlin
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 载荷 ​

  1. validate 函数允许您对 JWT 载荷执行验证。此函数是必需的:如果您未对其进行配置,提供程序初始化时将抛出 IllegalArgumentException。检查 credential 形参,它表示一个包含 JWT 载荷的 JWTCredential 对象。在下面的示例中,检查了自定义 username claim 的值。

    kotlin
    install(Authentication) {
        jwt("auth-jwt") {
            validate { credential ->
                val payload = credential.payload
                val claim = payload.getClaim("username")
                if (claim.asString() != "") {
                    JWTPrincipal(credential.payload)
                } else {
                    null
                }
            }
        }
    }

    身份验证成功时,返回 JWTPrincipal。

  2. challenge 函数允许您配置在身份验证失败时发送的响应。

    kotlin
    install(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:

kotlin
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 的值以及令牌过期时间。

kotlin
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 检查:

kotlin
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."
            )
        }
    }
}