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

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 アーティファクトを含める必要があります。

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 {
        // 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'"
}

シークレット情報を設定ファイルにプレーンテキストで保存しないでください。このようなパラメータを指定するには、環境変数の使用を検討してください。

コード内でこれらの設定にアクセスするには、次のように記述します。

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>()
    // 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))
}
kotlin
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))
}
  1. post("/login") は、POST リクエストを受信するための認証ルートを定義します。
  2. call.receive<User>() は、JSON オブジェクトとして送信されたユーザークレデンシャルを受信し、User クラスオブジェクトに変換します。
  3. JWT.create() は、指定された JWT 設定でトークンを生成し、受信したユーザー名を含むカスタムクレームを追加して、指定されたアルゴリズムでトークンに署名します。
    • HS256 の場合、トークンの署名に共有シークレットが使用されます。
    • RS256 の場合、公開鍵/秘密鍵のペアが使用されます。
  4. call.respond は、トークンを JSON オブジェクトとしてクライアントに送信します。

ステップ 3: レルムの構成 ​

realm プロパティを使用すると、保護されたルートへのアクセス時に WWW-Authenticate ヘッダーで渡されるレルムを設定できます。

kotlin
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 になります。
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 がスローされます。JWT ペイロードを含み JWTCredential オブジェクトを表す credential パラメータをチェックします。以下の例では、カスタムの username クレームの値がチェックされています。

    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 は試験的なものです。いつでも廃止または変更される可能性があります。 オプトインが必要です。詳細については、 型安全な認証のドキュメントを参照してください。

jwt() 関数は、任意のプリンシパル型のスキームを作成します。install(Authentication) のステップはありません。スキームは、それを必要とするルートに渡す値です。

validate の内部で必要なクレームを読み取り、独自の型を返します。これにより、ルートハンドラーは 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)
    }
}

失敗ハンドラーは challenge ではなく onUnauthorized です。完全な API については、型安全な認証を参照してください。

ステップ 6: 特定のリソースの保護 ​

jwt プロバイダーを構成した後、authenticate 関数を使用してアプリケーション内の特定のリソースを保護できます。認証に成功した場合、ルートハンドラー内で call.principal 関数を使用して認証済みの JWTPrincipal を取得し、JWT ペイロードを取得できます。以下の例では、カスタムの username クレームの値とトークンの有効期限が取得されています。

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 で読み取られているため、ハンドラーは独自の型を操作でき、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."
            )
        }
    }
}