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

> カスタムトークンプロファイルにActionを関連付けて、カスタムトークン交換を設定する方法を説明します。

# カスタムトークン交換を設定する

アプリケーションのカスタムトークン交換を設定するには、次の操作が必要です。

* [前提条件を満たす](#prerequisites)
* [アプリケーションでカスタムトークン交換を有効にする](#enable-custom-token-exchange-for-your-application)
* カスタムトークン交換プロファイルを[設定](#configure-custom-token-exchange-profile)し、[管理](#manage-custom-token-exchange-profile)する

<h2 id="prerequisites">
  前提条件
</h2>

カスタムトークン交換を設定する前に、アプリケーションが以下の前提条件を満たしていることを確認してください。

* [ファーストパーティ クライアント](/docs/ja-jp/get-started/applications/first-party-and-third-party-applications)である
* [OIDC 準拠](/docs/ja-jp/get-started/applications/application-settings#oauth)である

<h2 id="enable-custom-token-exchange-for-your-application">
  アプリケーションでカスタムトークン交換を有効にする
</h2>

カスタムトークン交換は複数のアプリケーションで有効にできます。デフォルトでは無効になっています。有効にするには、次の手順を実行します。

<Tabs>
  <Tab title="Auth0 Dashboard">
    1. **アプリケーション > アプリケーション** に移動し、対象のアプリケーションを選択します。
    2. **設定** タブを選択します。
    3. **カスタムトークン交換** を見つけてオンにします。
    4. **保存** を選択します。
  </Tab>

  <Tab title="Management API">
    Management API を使用して、[Create a Client](https://auth0.com/docs/api/management/v2/clients/post-clients) に `POST` リクエスト、または [Update a Client](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id) に `PATCH` リクエストを送信し、`token_exchange` の `allow_any_profile_of_type` 属性を `["custom_authentication"]` に設定します。

    ```json lines theme={null}
    {
      "token_exchange": {
        "allow_any_profile_of_type": ["custom_authentication"]
      }
    }
    ```
  </Tab>
</Tabs>

アプリケーションでカスタムトークン交換を有効にしたら、そのアプリケーションでカスタムトークン交換に使用する接続も有効にします。

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  インポートモードが `ON` のカスタム DB は、`setUserById()` 操作でのみサポートされます。
</Callout>

後で `/oauth/token` エンドポイントを呼び出す際に使用するため、アプリケーションの `client_id` と `client_secret` を控えておきます。

<h2 id="configure-custom-token-exchange-profile">
  カスタムトークン交換プロファイルを設定する
</h2>

各カスタムトークン交換プロファイルは、`subject_token_type` と、特定のユースケースのコードロジックを含む Action との間に 1 対 1 のマッピングを定義します。

特定の `subject_token_type` 値を含む `/oauth/token` エンドポイントへのカスタムトークン交換リクエストは、対応するカスタムトークンプロファイルにマッピングされ、処理のために関連付けられた Action にルーティングされます。

Custom Token Exchange の Event オブジェクトと API オブジェクトを使用して、プロファイルに関連付けられた Action を作成します。Action では、次の処理を行う必要があります。

* `subject_token_type` に基づいて `subject_token` をデコードし、検証します。これにより、トランザクションにおけるユーザー情報を取得できます。
* トランザクションに適用する必要がある認可ポリシーを適用します。

トランザクションを続行できることを確認したら、ユーザーを設定します。すると Auth0 は、このユーザーに対してユーザー認証の一環として、アクセストークン、ID トークン、リフレッシュトークンを発行します。

Custom Token Exchange の Action の例については、[Example Use Cases and Code Samples](/docs/ja-jp/authenticate/custom-token-exchange/cte-example-use-cases) を参照してください。

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  `subject_token_type` は、`https://` または `urn` で始まる一意の URI である必要があります。次の名前空間は予約されているため使用できません: `http://auth0.com`, `https://auth0.com`, `http://okta.com`, `https://okta.com`, `urn:ietf`, `urn:auth0`, `urn:okta`。
</Callout>

<Tabs>
  <Tab title="Auth0 Dashboard">
    1. **Authentication > カスタムトークン交換**に移動し、**Create Profile**を選択します。
    2. **Create Profile**ダイアログで、以下を行います。
       * プロファイルの**Name**を入力します。
       * 一意の**Subject Token Type**を入力します。
       * このプロファイルに関連付けるActionの設定方法を選択します。
         * **Start from scratch**: 新しいActionの**Name**を入力します。プロファイルを作成すると、Auth0によりカスタムトークン交換トリガーに紐付けられた空のActionが作成されます。
         * **Create from Template**: [Action Template](/docs/ja-jp/customize/actions/actions-templates)を選択します。Auth0により、テンプレートのコードがあらかじめ入力された新しいActionが作成されます。
         * **Use existing**: カスタムトークン交換トリガーにすでに紐付けられている既存のActionを選択します。
    3. **Create**を選択します。Auth0によりプロファイルが作成され、新しいActionまたはテンプレートからActionを作成することを選択した場合は、そのActionも作成されます。その後、プロファイルの**Details**ページが表示されます。
    4. **Details**ページで、以下を行います。
       * 必要に応じて、プロファイルの**Name**または**Subject Token Type**を編集します。
       * 必要に応じて、関連付けられたActionの**Name**を編集します。
       * インラインコードエディターで、関連付けられたActionのコードを編集します。下書きを保存するには**Save**を、Actionの新しいバージョンをデプロイするには**Deploy**を選択します。

    <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
      プロファイルの作成後は、関連付けるActionを変更できません。
    </Callout>
  </Tab>

  <Tab title="Management API">
    Management API を使用してカスタムトークン交換プロファイルを作成するには、まず Action を作成し、次にその Action の ID を参照するプロファイルを作成します。

    <h3 id="create-the-action">
      Action を作成する
    </h3>

    Action のコードを記述し、Management API を使用して[作成](https://auth0.com/docs/api/management/v2/actions/post-action)してから[デプロイ](https://auth0.com/docs/api/management/v2/actions/post-deploy-action)します。

    <Callout icon="file-lines" color="#0EA5E9" iconType="regular">Auth0 CLI を使用する場合は、これらのコマンドを実行する前に、まだであれば [CLI セッションの設定と認証](/docs/ja-jp/deploy-monitor/auth0-cli)を行ってください。</Callout>

    1. 次の `POST` リクエストを `/actions/actions` エンドポイントに送信し、`custom-token-exchange` トリガーに紐付けられた Action を作成します。

    <Tabs>
      <Tab title="Auth0 CLI">
        ```bash theme={null}
        auth0 api post "actions/actions" \
          --data '{
              "name": "<YOUR_ACTION_NAME>",
              "supported_triggers": [
                { "id": "custom-token-exchange", "version": "v1" }
              ],
              "code": "exports.onExecuteCustomTokenExchange = async (event, api) => {\n  // ここにカスタムロジックを記述\n};"
          }'
        ```
      </Tab>

      <Tab title="cURL">
        ```bash lines theme={null}
        curl --location 'https://{yourDomain}/api/v2/actions/actions' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
        --data '{
            "name": "<YOUR_ACTION_NAME>",
            "supported_triggers": [
                { "id": "custom-token-exchange", "version": "v1" }
            ],
            "code": "exports.onExecuteCustomTokenExchange = async (event, api) => {\n  // ここにカスタムロジックを記述\n};"
        }'
        ```
      </Tab>
    </Tabs>

    レスポンス本文の `id` プロパティに Action ID が含まれています。これは、Action のデプロイとカスタムトークン交換プロファイルの作成の両方に必要です。

    2. 次の`POST`リクエストを`/actions/actions/{id}/deploy`エンドポイントに送信して、Actionをデプロイします。

    <Tabs>
      <Tab title="Auth0 CLI">
        ```bash theme={null}
        auth0 api post "actions/actions/{yourActionId}/deploy"
        ```
      </Tab>

      <Tab title="cURL">
        ```bash lines theme={null}
        curl --location --request POST 'https://{yourDomain}/api/v2/actions/actions/{yourActionId}/deploy' \
        --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
        ```
      </Tab>
    </Tabs>

    <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
      Actionをカスタムトークン交換プロファイルにバインドするには、事前にデプロイする必要があります。
    </Callout>

    カスタムトークン交換アクションの例から学ぶには、[ユースケースとコードサンプル](/docs/ja-jp/authenticate/custom-token-exchange/cte-example-use-cases)をお読みください。

    <h3 id="create-the-custom-token-exchange-profile">
      カスタムトークン交換プロファイルを作成する
    </h3>

    カスタムトークン交換プロファイルを作成するには、Management API を使用して、以下のパラメータを指定した `POST` リクエストを `/token-exchange-profiles` エンドポイントに送信します:

    <Tabs>
      <Tab title="Auth0 CLI">
        ```bash theme={null}
        auth0 api post "token-exchange-profiles" \
          --data '{
              "name": "<YOUR_PROFILE_NAME>",
              "subject_token_type": "<YOUR_UNIQUE_PROFILE_TOKEN_TYPE_URI>",
              "action_id": "<YOUR_ACTION_ID>",
              "type": "custom_authentication"
          }'
        ```
      </Tab>

      <Tab title="cURL">
        ```bash lines theme={null}
        curl --location 'https://{yourDomain}/api/v2/token-exchange-profiles' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
        --data '{
            "name": "<YOUR_PROFILE_NAME>",
            "subject_token_type": "<YOUR_UNIQUE_PROFILE_TOKEN_TYPE_URI>",
            "action_id": "<YOUR_ACTION_ID>",
            "type": "custom_authentication"
        }'
        ```
      </Tab>
    </Tabs>

    | パラメータ                | 説明                                                                                                                                                                                                                                                                           |
    | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `subject_token_type` | `https://` または `urn` で始まる一意のプロファイルトークンタイプ URI<br /><br />以下の名前空間は予約されており、使用できません。<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> |
    | `action_id`          | Custom Token Profile に関連付けられている Action の Action ID。                                                                                                                                                                                                                          |
    | `type`               | `custom_authentication` に設定します。                                                                                                                                                                                                                                              |

    カスタム トークン交換プロファイルが正常に作成されると、次のようなレスポンスが返されます。

    ```json lines theme={null}
    {
      "id":"tep_9xqewuejpa2RTltf",
      "name":"<YOUR_PROFILE_NAME>",
      "type":"custom_authentication",
      "subject_token_type":"<YOUR_UNIQUE_PROFILE_TOKEN_TYPE_URI>",
      "action_id":"<YOUR_ACTION_ID>",
      "created_at":"2025-01-30T13:19:00.616Z",
      "updated_at":"2025-01-30T13:19:00.616Z"
    }
    ```
  </Tab>
</Tabs>

<h3 id="manage-custom-token-exchange-profile">
  カスタムトークン交換プロファイルを管理する
</h3>

<Tabs>
  <Tab title="Auth0 Dashboard">
    1. **Authentication > Custom Token Exchange** に移動すると、各プロファイルの **Name**、**Subject Token Type**、**Action ID** を含むカスタムトークン交換プロファイルの一覧が表示されます。
    2. プロファイルを選択して **Details** ページを開くと、**Name**、**Subject Token Type**、および関連付けられた Action の **Name** とコードを編集できます (上記の「[カスタムトークン交換プロファイルを設定する](#configure-custom-token-exchange-profile)」を参照) 。
    3. プロファイルを削除するには、一覧でプロファイルの横にあるオプションメニュー (3点アイコン) を選択し、**Delete** を選択します。

    <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
      カスタムトークン交換プロファイルに関連付けられた Action を単独で削除することはできません。先にプロファイルを削除し、その Action が不要になった場合は削除してください。
    </Callout>
  </Tab>

  <Tab title="Management API">
    カスタムトークン交換プロファイルを管理するには、Management API を使用して `/token-exchange-profiles` エンドポイントにリクエストを送信します。

    すべてのカスタムトークン交換プロファイルを取得するには、`/token-exchange-profiles` エンドポイントに対して次の `GET` リクエストを送信します。複数のプロファイルがある場合、`/token-exchange-profiles` エンドポイントは checkpoint ページネーションをサポートします。

    <Tabs>
      <Tab title="Auth0 CLI">
        ```bash theme={null}
        auth0 api get "token-exchange-profiles"
        ```
      </Tab>

      <Tab title="cURL">
        ```bash lines theme={null}
        curl --location 'https://{yourDomain}/api/v2/token-exchange-profiles' \
        --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
        ```
      </Tab>
    </Tabs>

    既存のプロファイルの名前または `subject_token_type` を更新するには、`/token-exchange-profiles` エンドポイントに対して次の `PATCH` リクエストを送信します。

    <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
      Action を作成した後は、Action ID を変更できません。
    </Callout>

    <Tabs>
      <Tab title="Auth0 CLI">
        ```bash theme={null}
        auth0 api patch "token-exchange-profiles/{yourProfileId}" \
          --data '{
              "name": "external-idp-migration",
              "subject_token_type": "urn:partner0:external-idp-migration"
          }'
        ```
      </Tab>

      <Tab title="cURL">
        ```bash lines theme={null}
        curl --location --request PATCH 'https://{yourDomain}/api/v2/token-exchange-profiles/{yourProfileId}' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
        --data '{
            "name": "external-idp-migration",
            "subject_token_type": "urn:partner0:external-idp-migration"
        }'
        ```
      </Tab>
    </Tabs>

    カスタムトークン交換プロファイルを削除するには、`/token-exchange-profiles` エンドポイントに対して次の `DELETE` リクエストを送信します。

    <Tabs>
      <Tab title="Auth0 CLI">
        ```bash theme={null}
        auth0 api delete "token-exchange-profiles/{yourProfileId}" \
          --data ''
        ```
      </Tab>

      <Tab title="cURL">
        ```bash lines theme={null}
        curl --location --request DELETE 'https://{yourDomain}/api/v2/token-exchange-profiles/{yourProfileId}' \
        --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
        --data ''
        ```
      </Tab>
    </Tabs>

    <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
      カスタムトークン交換プロファイルに関連付けられた Action を単独で削除することはできません。先にプロファイルを削除し、その Action が不要になった場合は削除してください。
    </Callout>
  </Tab>
</Tabs>