Custom Token Exchange フローを使用して API を呼び出す

Custom Token Exchange フローを使用して API を呼び出す方法を説明します。

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

Custom Token Exchange で使用するサブジェクトトークンとアクタートークンは、Action コードで解釈できる限り、任意のトークン形式またはトークンタイプを使用できます。受信して受け入れるトークンについては、必ず堅牢な検証を実装してください。これを怠ると、なりすましやリプレイ攻撃などのさまざまな攻撃ベクトルに対して脆弱になり、悪意のある第三者が他人のユーザー ID で認証されたり、権限なくそのユーザーの代理として振る舞えたりするおそれがあります。

各 subject_token_type は Custom Token Exchange Profile にマッピングされ、そのトランザクションを制御するために実行される Action に関連付けられます。

パラメーター	説明
grant_type	Custom Token Exchange の場合は、urn:ietf:params:oauth:grant-type:token-exchange を使用します。
subject_token_type	サブジェクトトークンのタイプです。Custom Token Exchange では、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 に使用するアプリケーションのクライアント ID です。他のグラントタイプと同様に、HTTP Basic Auth を使用して Authorization ヘッダーでクライアント ID を渡すこともできます。
client_secret	Token Exchange に使用するアプリケーションのクライアントシークレットです。他のグラントタイプと同様に、HTTP Basic Auth を使用して Authorization ヘッダーでクライアントシークレットを渡すこともできます。 そのほかの方法については、Auth0 Authentication API リファレンスを参照してください。 なお、Custom Token Exchange はパブリックアプリケーションでも使用できます。その場合は、アタックプロテクション を必ず確認してください。
audience	Auth0 で定義された API 識別子です。指定しない場合は、テナント設定 で設定されたデフォルトのテナントオーディエンスが使用されます。
scope	(省略可能) OAuth 2.0 のスコープパラメーターです。
organization	(省略可能) リクエストに関連付ける組織識別子です。テナントで Use Organization Names in Authentication API が許可されている場合は、代わりに組織名を指定することもできます。リクエストがどのように処理されるかについて詳しくは、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 と同じ名前空間の制約に従ってください。

トランザクションにアクターが設定されている場合、要求されたスコープにかかわらずリフレッシュトークンは発行されません。レスポンスからは offline_access スコープが除外されます。これは意図された設計です。デリゲーションされたトークンがその場の交換を超えて有効にならないようにすることで、後続の各アクセスリクエストが 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_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>'