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

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

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

• 前提条件を満たす
• アプリケーションでカスタムトークン交換を有効にする
• カスタムトークン交換プロファイルを設定し、管理する

​

前提条件

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

• ファーストパーティ クライアントである
• OIDC 準拠である

アプリケーションを設定するには、Auth0 Dashboard で アプリケーション > 詳細設定 > OAuth に移動してください。

​

アプリケーションでカスタムトークン交換を有効にする

カスタムトークン交換を有効にするには、新しいアプリケーションを作成するか、Auth0 Dashboard または Management API を使用して既存のアプリケーションを更新します。カスタムトークン交換で使用するために、複数のアプリケーションを作成できます。

新しいアプリケーションを作成する場合:

1. デフォルトでは、カスタムトークン交換は無効になっています。カスタムトークン交換を有効にするには、Management API を使用して Create a Client に POST リクエストを送信するか、Update a Client に PATCH リクエストを送信します。token_exchange 配下の allow_any_profile_of_type 属性を ["custom_authentication"] に設定します:

{
  "token_exchange": {
    "allow_any_profile_of_type": ["custom_authentication"]
  }
}

2. アプリケーションで、カスタムトークン交換に使用する接続を有効にします。
3. ご使用のアプリケーションがファーストパーティとして設定され、Auth0 Dashboard > アプリケーション > 詳細設定 > OAuth で OIDC 準拠として構成されていることを確認します。

import mode が ON のカスタム DB は、setUserById() 操作でのみサポート対象です。

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

​

カスタムトークン交換プロファイルを設定する

各カスタムトークン交換プロファイルでは、subject_token_type と Action が1対1でマッピングされ、Action には特定のユースケースに対応するコードロジックが含まれます。

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

カスタムトークン交換プロファイルを作成するには、次の手順を行います。

1. プロファイル用のActionを作成する
2. カスタムトークン交換プロファイルを作成する
3. カスタムトークン交換プロファイルを管理する

​

プロファイル用のActionを作成する

Custom Token Exchange の Event オブジェクトと API オブジェクトを使用して、次の処理を行う Action を作成します。

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

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

Custom Token Exchange の Action の例については、Example Use Cases and Code Samples を参照してください。

Action を作成したら、Auth0 Dashboard で追加してデプロイします。

1. Actions > Library に移動します。
2. Create Action > Build from Scratch を選択します。
3. Create Action ダイアログで名前を入力し、ドロップダウンから カスタムトークン交換 トリガーを選択します。

4. Create を選択します。
5. Action を Deploy します。

Action をデプロイしたら、Auth0 によって割り当てられた Action ID をコピーします。Action にはまだカスタムロジックを追加する必要があります。まず、カスタムトークン交換プロファイル を作成するために Action ID を取得します。

6. Auth0 Dashboard で Action ID を取得するには、ブラウザーウィンドウの URL を確認します。次の画像に示すように、Action ID は URL の最後の部分です。

Management API から Action ID を取得することもできます。まず、API を利用するための Management API トークンを取得します。次に、/actions エンドポイントに対して次の GET リクエストを実行します。

curl --location 'https://{yourDomain}/api/v2/actions/actions?actionName={yourActionName}' \
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \

レスポンス本文の actions[0].id. に Action ID が含まれているはずです。カスタムトークン交換プロファイル を作成するには、Action ID が必要です。

​

カスタムトークン交換プロファイルを作成

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

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"
}'

パラメータ	説明
subject_token_type	https:// または urn で始まる、一意のプロファイルトークンタイプ URI 次の名前空間は予約されているため、使用できません。 http://auth0.com https://auth0.com http://okta.com https://okta.com urn:ietf urn:auth0 urn:okta
action_id	カスタムトークンプロファイル に関連付けられた Action の Action ID。
type	custom_authentication に設定する必要があります。

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

{
  "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"
}

​

カスタムトークン交換プロファイルを管理する

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

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

curl --location 'https://{yourDomain}/api/v2/token-exchange-profiles' \
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \

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

Action を作成すると、Action ID は変更できません。

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"
}'

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

curl --location --request DELETE 'https://{yourDomain}/api/v2/token-exchange-profiles/{yourProfileId}' \
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
--data ''