JSON Web Tokens
必要な依存関係: io.ktor:ktor-server-auth, io.ktor:ktor-server-auth-jwt
コード例: auth-jwt-hs256, auth-jwt-rs256
Native サーバーKtorはKotlin/Nativeをサポートしており、追加のランタイムや仮想マシンなしでサーバーを実行できます。のサポート: ✖️
JSON Web Token (JWT) は、当事者間で情報を JSON オブジェクトとして安全に送信する方法を定義したオープン標準です。この情報は、共有シークレット(HS256 アルゴリズムなど)または公開鍵/秘密鍵のペア(RS256 など)を使用して署名されているため、検証および信頼することができます。
Ktor は、Bearer スキームを使用して Authorization ヘッダーで渡された JWT を処理し、以下の操作を実行できます。
- JSON Web Token の署名を検証する
- JWT ペイロードに対して追加の検証を実行する
Ktor における認証と認可の一般的な情報については、Ktor Server での認証と認可セクションを参照してください。
トークンが 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 {
// Configure jwt authentication
}
}オプションで、指定したルートを認証するために使用できるプロバイダー名を指定できます。
JWT の構成
このセクションでは、Ktor サーバーアプリケーションで JSON Web Token を使用する方法について説明します。トークンの検証方法が少し異なるため、トークンの署名に関する2つのアプローチを示します。
- 指定された共有シークレットで
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>()
// Check username and password
// ...
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>()
// Check username and password
// ...
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 設定でトークンを生成し、受信したユーザー名を含むカスタムクレームを追加して、指定されたアルゴリズムでトークンに署名します。HS256の場合、トークンの署名に共有シークレットが使用されます。RS256の場合、公開鍵/秘密鍵のペアが使用されます。
call.respondは、トークンを JSON オブジェクトとしてクライアントに送信します。
ステップ 3: レルムの構成
realm プロパティを使用すると、保護されたルートへのアクセス時に WWW-Authenticate ヘッダーで渡されるレルムを設定できます。
val myRealm = jwtConfig.property("jwt.realm").getString()
install(Authentication) {
jwt("auth-jwt") {
realm = myRealm
}
}ステップ 4: トークン検証機能の構成
verifier 関数を使用すると、トークンの形式とその署名を検証できます。
HS256の場合、トークンを検証するために JWTVerifier インスタンスを渡す必要があります。RS256の場合、トークンの検証に使用される公開鍵にアクセスするための JWKS エンドポイントを指定する JwkProvider を渡す必要があります。この例では発行者が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がスローされます。JWT ペイロードを含み JWTCredential オブジェクトを表すcredentialパラメータをチェックします。以下の例では、カスタムのusernameクレームの値がチェックされています。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 は試験的なものです。いつでも廃止または変更される可能性があります。 オプトインが必要です。詳細については、 型安全な認証のドキュメントを参照してください。
jwt() 関数は、任意のプリンシパル型のスキームを作成します。install(Authentication) のステップはありません。スキームは、それを必要とするルートに渡す値です。
validate の内部で必要なクレームを読み取り、独自の型を返します。これにより、ルートハンドラーは 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)
}
}失敗ハンドラーは challenge ではなく onUnauthorized です。完全な API については、型安全な認証を参照してください。
ステップ 6: 特定のリソースの保護
jwt プロバイダーを構成した後、authenticate 関数を使用してアプリケーション内の特定のリソースを保護できます。認証に成功した場合、ルートハンドラー内で call.principal 関数を使用して認証済みの JWTPrincipal を取得し、JWT ペイロードを取得できます。以下の例では、カスタムの username クレームの値とトークンの有効期限が取得されています。
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 で読み取られているため、ハンドラーは独自の型を操作でき、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."
)
}
}
}