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

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

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

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

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

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 を使用できます。 次の名前空間は予約済みのため使用できません。 http://auth0.com https://auth0.com http://okta.com https://okta.com urn:ietf urn:auth0 urn:okta
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 を渡すこともできます。 そのほかの方法についても、Auth0 Authentication API reference docs で説明されています。 なお、カスタムトークン交換はパブリックなアプリケーションでも使用できます。その場合は必ず 攻撃対策 を確認してください。
audience	Auth0 で定義された API 識別子です。指定しない場合は、Tenant Settings で設定されているテナントのデフォルト audience が使用されます。
scope	(任意) OAuth2 の scope パラメータです。
organization	(任意) リクエストに関連付ける organization 識別子です。テナントで Use Organization Names in Authentication API が許可されている場合は、organization名を指定することもできます。リクエストがどのように処理されるかについて詳しくは、api.authentication.setOrganization() API method を参照してください。
actor_token	(任意) アクター、またはサブジェクトユーザーに代わって委譲を実行する主体を識別するトークンです。actor_token_type とあわせて指定する必要があります。
actor_token_type	(任意) アクタートークンのタイプです。actor_token とあわせて指定する必要があります。Auth0 ID トークンの場合は、サーバー側で自動的に検証されるよう urn:ietf:params:oauth:token-type:id_token を使用します。その他の値については、subject_token_type と同じ名前空間の制限に従ってください。

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

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

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

​

リクエスト例

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'

​

actor token を含むリクエスト例

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

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