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

# トークンの取得

> On-Behalf-Of（OBO）トークン交換では、中間層サービスが受信したユーザー トークンを、ダウンストリーム サービス向けにスコープされた新しいトークンに交換できます。

`POST /oauth/token`

On-Behalf-Of (OBO) トークン交換 ([RFC 8693](https://datatracker.ietf.org/doc/html/rfc8693)) では、中間層サービスがユーザーにスコープされたトークンを、ダウンストリーム サービスを呼び出すための新しいトークンに交換できます。

新しいトークンは、元のユーザーのアイデンティティと権限を維持したまま、ダウンストリーム サービス専用にスコープされます。これにより、そのサービスはエンドユーザーに基づいて認可の判断を行えます。デリゲーション チェーンは `act` (actor) クレームで追跡され、各レベルは呼び出しチェーン内のサービスを表します。詳細については、[On-Behalf-Of トークン交換のドキュメント](https://auth0.com/docs/secure/call-apis-on-users-behalf/on-behalf-of-token-exchange) を参照してください。

<div id="remarks">
  ## 注意事項
</div>

* リソースサーバーに関連付けられたカスタム API クライアントのみが、OBO トークン交換を使用できます。カスタム API クライアントには、次の要件があります。
  * `app_type` を `resource_server` に設定します。
  * `resource_server_identifier` を有効なリソースサーバー (つまり `https://my-api.example.com`) に設定します。Auth0 は、認可呼び出しでリソースサーバー識別子を オーディエンス パラメーターとして使用します。

* アプリケーションに発行されるスコープは、要求したスコープと異なる場合があります。この場合、レスポンス JSON に `scope` パラメーターが含まれます。スコープは、ユーザーの[ロールベースアクセス制御 (RBAC) ポリシー](/ja/docs/manage-users/access-control/rbac)に基づきます。

* OBO トークン交換では、[`post-login` Action トリガー](/ja/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger)が実行されます。このとき、`event.transaction.protocol` は `oauth2-token-exchange` に設定され、`event.transaction.actor` で完全なデリゲーションチェーンが追跡されます。

* デリゲーションチェーンは、5 つのネストレベルまでに制限されています。サブジェクトトークンにすでに 5 つの `act` ネストレベルがある場合、OBO トークン交換は失敗します。

* API 呼び出しごとに新しいトークンを要求するのではなく、アクセストークンの有効期間中はそれをキャッシュしてください。アクセストークンは有効期限が切れるまで再利用できます。トークン交換を繰り返すと、リソースを無駄に消費し、レイテンシーが増加し、レート制限に達する可能性があります。

<div id="parameters">
  ## パラメーター
</div>

<ParamField header="DPoP" type="string">
  リクエスト用の DPoP プルーフです。これは省略可能で、アプリケーションで [所有証明の提示](/ja/docs/secure/sender-constraining/demonstrating-proof-of-possession-dpop) を使用している場合にのみ必要です。
</ParamField>

<ParamField header="auth0-forwarded-for" type="string">
  エンドユーザーの IP を文字列値で指定します。サーバー側のシナリオで [不審な IP スロットリング](/ja/docs/secure/attack-protection/suspicious-ip-throttling) 保護を有効にする場合は、これを設定します。
</ParamField>

<div id="request-body">
  ## リクエストボディ
</div>

<ParamField body="grant_type" type="string" required>
  使用するフローを示します。On-Behalf-Of トークン交換 では、`urn:ietf:params:oauth:grant-type:token-exchange` を使用します。
</ParamField>

<ParamField body="subject_token_type" type="string" required>
  サブジェクトトークンの種類です。On-Behalf-Of トークン交換 では、`urn:ietf:params:oauth:token-type:access_token` を使用します。
</ParamField>

<ParamField body="subject_token" type="string" required>
  中間層サービスが現在保持している、ユーザーまたは上流サービスから受け取った Auth0 アクセストークンです。
</ParamField>

<ParamField body="requested_token_type" type="string" required>
  返却を要求するトークンの種類を示します。On-Behalf-Of トークン交換 では、`urn:ietf:params:oauth:token-type:access_token` を使用します。
</ParamField>

<ParamField body="client_id" type="string" required>
  カスタム API クライアントのクライアントIDです。カスタム API クライアントは、リソースサーバー (同じ識別子) に関連付けられている必要があります。他のグラントタイプと同様に、HTTP Basic Auth を使用して Authorization ヘッダーでクライアントIDを渡すこともできます。
</ParamField>

<ParamField body="client_secret" type="string" required>
  カスタム API クライアントのクライアントシークレットです。他のグラントタイプと同様に、`HTTP` Basic Auth を使用して Authorization ヘッダーでクライアントシークレットを渡すこともできます。代替方法については、[Auth0 Authentication API リファレンスドキュメント](https://auth0.com/docs/api/authentication#authentication-methods)を参照してください。OBO トークン交換では、`token_endpoint_auth_method` を `none` に設定できない点に注意してください。
</ParamField>

<ParamField body="audience" type="string" required>
  アクセス先のダウンストリーム API の一意の識別子です。これは、新しいトークンを受け取って検証する下流サービスの識別子です。
</ParamField>

<ParamField body="scope" type="string">
  (省略可) 下流呼び出しに対して要求する特定の権限のスペース区切りリストです。指定しない場合、対象のオーディエンスに対してユーザーに付与されているすべてのスコープが、RBAC ポリシーに基づいて含まれます。
</ParamField>

<div id="response">
  ## レスポンス
</div>

| ステータス | 説明                                                                              |
| ----- | ------------------------------------------------------------------------------- |
| 200   | リクエストは成功しました。同じユーザーのアイデンティティを維持したまま、ダウンストリーム API 用のアクセストークンを返します。               |
| 400   | 不正なリクエストです。デリゲーションチェーンの深さが許可されている最大の 4 階層を超えた場合や、必須パラメーターが不足している場合に発生することがあります。 |
| 401   | 未認証です。サブジェクトトークンが無効または期限切れであるか、クライアントクレデンシャルが正しくありません。                          |
| 403   | アクセスが拒否されました。クライアントにトークン交換を実行する権限がないか、ユーザーが対象のオーディエンスに対して要求されたスコープを持っていません。     |

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "access_token": "eyJ...",
    "expires_in": 86400,
    "token_type": "Bearer",
    "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
  }
  ```

  ```json 400 Response (Delegation chain limit exceeded) theme={null}
  {
    "error": "invalid_request",
    "error_description": "Delegation chain (`act` claim) depth exceeds the maximum allowed limit of 5"
  }
  ```
</ResponseExample>

<div id="response-fields">
  ## レスポンスフィールド
</div>

<ResponseField name="access_token" type="string">
  ダウンストリーム API 向けにスコープ設定された、新しい Auth0 アクセストークンです。この [JSON Web Token (JWT)](/ja/docs/secure/tokens/json-web-tokens#json-web-tokens) には、サブジェクトトークンと同じ `sub` (ユーザーのアイデンティティ) が含まれ、`aud` には要求されたダウンストリーム API のオーディエンスが設定されます。`act` クレームはデリゲーションチェーンを追跡します。
</ResponseField>

<ResponseField name="issued_token_type" type="string">
  返されるトークンの形式を示します。これは、リクエストの `requested_token_type` と一致します。

  値: `urn:ietf:params:oauth:token-type:access_token`
</ResponseField>

<ResponseField name="token_type" type="string">
  Authorization ヘッダーで使用する認証スキームを指定します。OBO の場合、DPoP を使用していなければ `Bearer`、使用している場合は `DPoP` になります。
</ResponseField>

<ResponseField name="expires_in" type="number">
  トークンの有効期間 (秒) です。
</ResponseField>

<ResponseField name="scope" type="string">
  (省略可) 付与されたスコープが要求されたスコープと異なる場合にのみ含まれます。実際に付与されたスコープをスペース区切りで示したリストです。
</ResponseField>