> ## Documentation Index
> Fetch the complete documentation index at: https://developers.authlete.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> ID トークンの JWS ヘッダーに独自のクレームを追加する方法について説明します。

## はじめに

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

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

## 独自クレームの指定方法

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

* [/auth/authorization/issue](/api-reference/authorization-endpoint/issue-authorization-response)
* [/backchannel/authentication/complete](/api-reference/ciba/complete-backchannel-authentication)
* [/device/complete](/api-reference/device-flow/complete-device-authorization)

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

***

## 動作例

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

### 独自クレームの準備

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

| Key        | Value        |
| ---------- | ------------ |
| typ        | JWT          |
| extra\_key | extra\_value |

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

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

### 認証リクエストの処理

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

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

認可サーバーは、必要に応じてユーザー認証と同意確認を行い、Authlete の [/auth/authorization/issue](/api-reference/authorization-endpoint/issue-authorization-response)
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-reference/token-endpoint/process-token-request)
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 トークンのヘッダーに追加できました。