ID トークンのヘッダーへの独自クレーム追加

はじめに

本記事では、ID トークンの JWS ヘッダーに独自のクレームを追加する方法を説明します。

本機能は Authlete 2.2 以降でのみ利用可能になります。

独自クレームの指定方法

認可サーバーは以下の Authlete API に対するリクエストにおいて、idtHeaderParams パラメーターを用いて、ID トークンのヘッダーに追加したい独自のクレーム群を JSON 形式にて指定します。

• /auth/authorization/issue
• /backchannel/authentication/complete
• /device/complete

Authlete は受け取った独自クレームを ID トークンのヘッダーに追加し、認可サーバーに返却します。

動作例

本セクションでは、認可コードフローにおける、独自クレームを含む ID トークンの生成手順を例示します。

独自クレームの準備

ここでは、以下の独自クレームを ID トークンのヘッダーに含めるものとします。

idtHeaderParams パラメーターに指定する JSON 形式の値は以下のようになります。

{
    "typ": "JWT",
    "extra_key": "extra_value"
}

認証リクエストの処理

クライアント（OIDC リライングパーティ）は認可サーバー（OIDC アイデンティティプロバイダー）に対し、scope=openid / response_type=code を含む認証リクエストをユーザーエージェント経由で送信します。

認可サーバーはその認証リクエストを Authlete の /auth/authorization API に転送し、次に Authlete API へリクエストを行う際に必要な値 (ticket) を取得します。（詳細は割愛します）

認可サーバーは、必要に応じてユーザー認証と同意確認を行い、Authlete の /auth/authorization/issue API を呼び出します。このときに、さきほど用意した独自クレームを idtHeaderParams パラメーターとして指定します。

以下は curl による実行例です。（読みやすさのために折り返しています）

• リクエスト

curl -s -X POST .../auth/authorization/issue
 -u $apiKey:$apiSecret
 -H 'Content-type: application/json'
 -d '{"subject":"...",
      "ticket": "...",
      "idtHeaderParams":
        "{\"typ\":\"JWT\",
          \"extra_key\":\"extra_value\"}"
     }'

• レスポンス

{
    "type": "authorizationIssueResponse",
    "resultCode": "A040001",
    "resultMessage": "[A040001] The authorization request was processed successfully.",
    "accessTokenDuration": 0,
    "accessTokenExpiresAt": 0,
    "action": "LOCATION",
    "authorizationCode": "eOEh...3eSc",
    "responseContent": "https://...?code=eOEh...3eSc"
}

このレスポンスを受け取った認可サーバーは、クライアントに対してユーザーエージェント（Web ブラウザ）経由で認可コード (eOEh…3eSc) を返却することになります。

トークンリクエストの処理

認可コードを受け取ったクライアントは、認可サーバーに対して、認可コードを含むトークンリクエストを送信します。そして認可サーバーはそのトークンリクエストを Authlete の /auth/token API に転送し、トークンレスポンスを取得します。

以下は curl による実行例です。（読みやすさのために折り返しています）

• リクエスト

curl -s -X POST .../auth/token \
     -u $apiKey:$apiSecret \
     -H 'Content-type: application/json' \
     -d '{"clientId":"...",
          "clientSecret":"...",
          "parameters":
            "redirect_uri=https://...
            &grant_type=authorization_code
            &code=eOEh...3eSc"}'

• レスポンス

{
  "type": "tokenResponse",
  "resultCode": "A050001",
  "resultMessage":
    "[A050001] The token request (grant_type=authorization_code) was
     processed successfully.",
  "accessToken": "9Myh...sYMs",
  "action": "OK",
  "grantType": "AUTHORIZATION_CODE",
  "idToken":
    "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImV4dHJ
     hX2tleSI6ImV4dHJhX3ZhbHVlIn0.
     eyJzdWIiOiJ0ZXN0dXNlcjAxIiwiYXVkIjpbIjI4MzA
     0NTE3OTYwODU5NDAiXSwiaXNzIjoiaHR0cHM6Ly9hcy
     5leGFtcGxlLmNvbSIsImV4cCI6MTU5OTcyNjA0MCwia WF0IjoxNTk5NjM5NjQwfQ.
     -jo-A-SXjP4JlBSc24vKkO6FVf3MQJ6eN-XzPAraiZ4",
  "refreshToken": "SlEl...cWoY",
  "responseContent":
    "{\"access_token\":\"9Myh...sYMs\",
      \"refresh_token\":\"lEl...cWoY\",
      \"scope\":\"openid\",
      \"id_token\":
        \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImV4dHJ
          hX2tleSI6ImV4dHJhX3ZhbHVlIn0.
          eyJzdWIiOiJ0ZXN0dXNlcjAxIiwiYXVkIjpbIjI4MzA
          0NTE3OTYwODU5NDAiXSwiaXNzIjoiaHR0cHM6Ly9hcy
          5leGFtcGxlLmNvbSIsImV4cCI6MTU5OTcyNjA0MCwia
          WF0IjoxNTk5NjM5NjQwfQ.
          -jo-A-SXjP4JlBSc24vKkO6FVf3MQJ6eN-XzPAraiZ4\",
      \"token_type\":\"Bearer\",
      \"expires_in\":86400}",
  "scopes": [
    "openid"
  ],
  ...

このレスポンスに含まれる ID トークン (eyJh…aiZ4) の JWS ヘッダーには独自クレームが追加されています。以下はヘッダー部をデコードした結果です。

{
    "alg": "HS256",
    "typ": "JWT",
    "extra_key": "extra_value"

}

以上のように、独自定義したクレームを ID トークンのヘッダーに追加できました。