> ## 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.

> カスタムトークン交換を使用して、サブジェクトトークンを Auth0 のアクセストークン、ID トークン、リフレッシュトークンと交換するために API を呼び出す方法を学びます。

# カスタムトークン交換フローを使用して API を呼び出す

カスタムトークン交換を使用するには、次のパラメータを指定して `/oauth/token` エンドポイントに `POST` リクエストを送信します。

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  カスタムトークン交換で使用するサブジェクトトークンとアクタートークンは、Action コードで解釈できる限り、どのような形式・タイプのトークンでも使用できます。ただし、受け取って受け入れるトークンに対しては、必ず強固な検証を実装してください。これを怠ると、なりすましやリプレイ攻撃など、さまざまな攻撃経路に対して脆弱になり、悪意のある第三者が他人のユーザー ID を使って認証したり、権限なくその人になり代わって行動したりするおそれがあります。

  各 `subject_token_type` は 1 つのカスタムトークン交換プロファイルに対応しており、そのトランザクションを制御するために実行される Action に関連付けられます。
</Callout>

| Parameter            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `grant_type`         | カスタムトークン交換では、`urn:ietf:params:oauth:grant-type:token-exchange` を使用します。                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `subject_token_type` | サブジェクトトークンのタイプです。カスタムトークン交換では、`http://acme.com/legacy-token` や `urn:acme:legacy-token` のように、自身が所有する名前空間配下の任意の URI を使用できます。<br /><br />次の名前空間は予約済みのため使用できません。<ul><li>`http://auth0.com`</li><li>`https://auth0.com`</li><li>`http://okta.com`</li><li>`https://okta.com`</li><li>`urn:ietf`</li><li>`urn:auth0`</li><li>`urn:okta`</li></ul>                                                                                                                                                                    |
| `subject_token`      | サブジェクトトークンです。Action でこれを検証し、ユーザーを識別するために使用する必要があります。                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `client_id`          | Token Exchange に使用するアプリケーションの client ID です。他のグラントタイプと同様に、HTTP Basic Auth を使用して Authorization header で client ID を渡すこともできます。                                                                                                                                                                                                                                                                                                                                                                                    |
| `client_secret`      | Token Exchange に使用するアプリケーションの client secret です。他のグラントタイプと同様に、HTTP Basic Auth を使用して Authorization header で client secret を渡すこともできます。<br /><br />そのほかの方法についても、[Auth0 Authentication API reference docs](https://auth0.com/docs/api/authentication#authentication-methods) で説明されています。<br /><br />なお、カスタムトークン交換はパブリックなアプリケーションでも使用できます。その場合は必ず [攻撃対策](#attack-protection) を確認してください。                                                                                                                               |
| `audience`           | Auth0 で定義された API 識別子です。指定しない場合は、[Tenant Settings](/docs/ja-jp/get-started/tenant-settings) で設定されているテナントのデフォルト audience が使用されます。                                                                                                                                                                                                                                                                                                                                                                                |
| `scope`              | (任意) OAuth2 の scope パラメータです。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `organization`       | (任意) リクエストに関連付ける organization 識別子です。テナントで [Use Organization Names in Authentication API](/docs/ja-jp/manage-users/organizations/configure-organizations/use-org-name-authentication-api) が許可されている場合は、organization名を指定することもできます。リクエストがどのように処理されるかについて詳しくは、[api.authentication.setOrganization() API method](/docs/ja-jp/customize/actions/explore-triggers/signup-and-login-triggers/custom-token-exchange-trigger/custom-token-exchange-api-object#api-authentication-setorganization-organization) を参照してください。 |
| `actor_token`        | (任意) アクター、またはサブジェクトユーザーに代わって委譲を実行する主体を識別するトークンです。`actor_token_type` とあわせて指定する必要があります。                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `actor_token_type`   | (任意) アクタートークンのタイプです。`actor_token` とあわせて指定する必要があります。Auth0 ID トークンの場合は、サーバー側で自動的に検証されるよう `urn:ietf:params:oauth:token-type:id_token` を使用します。その他の値については、`subject_token_type` と同じ名前空間の制限に従ってください。                                                                                                                                                                                                                                                                                                                  |

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  トランザクションにアクターが設定されている場合、要求された scopes に関係なくリフレッシュトークンは発行されません。`offline_access` scope もレスポンスから除外されます。これは意図された動作です。委譲されたトークンがその場限りの交換を超えて有効にならないようにすることで、後続の各アクセスリクエストが CTE Action の認可ロジックを通り、委譲が再検証されるようにしています。

  CTE Action では、`subject_token` に対して行うのと同じ厳密さ (たとえば暗号学的署名の検証) で `actor_token` を安全に検証する必要があります。`actor_token_type` が `urn:ietf:params:oauth:token-type:id_token` の場合は、Auth0 がこの検証を自動的に実行します。
</Callout>

上記に記載されていないその他の拡張機能パラメーターは、対応するActionの`event.request.body`に含まれます。

<div id="sample-request">
  ## リクエスト例
</div>

```bash lines theme={null}
curl --location 'https://{yourDomain}/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
--data-urlencode 'audience=https://api.acme.com' \
--data-urlencode 'scopes=openid offline_access acme-scope1 acme-scope2' \
--data-urlencode 'subject_token_type=urn:acme:external-idp-migration' \
--data-urlencode 'subject_token=t8e7S2D9trQm73e .... iqBR3GjxDtbDVjpfQU' \
--data-urlencode 'client_id=<YOUR_CLIENT_ID>' \
--data-urlencode 'client_secret=<YOUR_CLIENT_SECRET>'
--data-urlencode 'organization=periscope-acme'
```

<div id="sample-request-with-actor-token">
  ## actor token を含むリクエスト例
</div>

委任された認可の交換を行う際は、`actor_token` と `actor_token_type` を含めます。

```bash lines theme={null}
curl --location 'https://{yourDomain}/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
--data-urlencode 'audience=https://api.acme.com' \
--data-urlencode 'scopes=openid acme-scope1 acme-scope2' \
--data-urlencode 'subject_token_type=urn:acme:legacy-token' \
--data-urlencode 'subject_token=t8e7S2D9trQm73e .... iqBR3GjxDtbDVjpfQU' \
--data-urlencode 'actor_token=eyJhbGciOiJSUzI1NiI .... kXdF9tZ3c' \
--data-urlencode 'actor_token_type=urn:ietf:params:oauth:token-type:id_token' \
--data-urlencode 'client_id=<YOUR_CLIENT_ID>' \
--data-urlencode 'client_secret=<YOUR_CLIENT_SECRET>'
```