POST /oauth/token
On-Behalf-Of (OBO) トークン交換 (RFC 8693) を使用すると、中間層サービスは、ユーザーにスコープが設定されたトークンを、下流サービスを呼び出すための新しいトークンに交換できます。
新しいトークンは、元のユーザーの識別情報と権限を維持したまま、下流サービス向けに特化したスコープが設定されます。これにより、そのサービスはエンドユーザーに基づいて認可を判断できます。委任チェーンは act (actor) クレームで追跡され、各レベルは呼び出しチェーン内のサービスを表します。詳しくは、On-Behalf-Of Token Exchange documentationを参照してください。
注意事項
-
リソースサーバーに関連付けられた Custom API クライアントのみが、OBO トークン交換を使用できます。Custom API クライアントには、次の要件があります。
app_typeをresource_serverに設定します。resource_server_identifierを有効なリソースサーバー (例:https://my-api.example.com) に設定します。Auth0 は認可リクエストで、リソースサーバー識別子を audience パラメーターとして使用します。
-
アプリケーションに発行されるスコープは、リクエストしたスコープと異なる場合があります。その場合、レスポンス JSON には
scopeパラメーターが含まれます。スコープは、ユーザーの RBAC ポリシー に基づいて決まります。 -
OBO トークン交換を行うと、
post-loginAction trigger がトリガーされます。このとき、event.transaction.protocolにはoauth2-token-exchangeが設定され、event.transaction.actorには完全な委任チェーンが記録されます。 -
委任チェーンは 5 段階までネストできます。交換時に現在のクライアントがさらに 1 段階として追加されるため、サブジェクトトークンがすでに 4 段階の
actネストレベルを持っている場合、OBO トークン交換は失敗します。 - API 呼び出しのたびに新しいトークンをリクエストするのではなく、アクセストークンの有効期間中はそのアクセストークンをキャッシュしてください。アクセストークンは有効期限が切れるまで再利用できます。トークン交換を繰り返すと、リソースを無駄に消費し、レイテンシーが増加し、レート制限に達する可能性があります。
パラメーター
リクエスト用の DPoP プルーフです。これは任意項目で、アプリケーションで Demonstrating Proof-of-Possession を使用している場合にのみ必要です。
エンドユーザーの IP アドレスを文字列で指定します。サーバーサイドのシナリオで Suspicious IP Throttling 保護を有効にしたい場合は、これを設定してください。
リクエストボディ
使用するフローを示します。On-Behalf-Of Token Exchange の場合は、
urn:ietf:params:oauth:grant-type:token-exchange を使用します。サブジェクトトークン の種類です。On-Behalf-Of Token Exchange の場合は、
urn:ietf:params:oauth:token-type:access_token を使用します。返却を希望するトークンの種類を示します。On-Behalf-Of Token Exchange の場合は、
urn:ietf:params:oauth:token-type:access_token を使用します。Custom API クライアントの Client ID です。Custom API クライアントは、リソースサーバー (同じ identifier) に関連付けられている必要があります。他の grant type と同様に、HTTP Basic Auth を使用して Authorization ヘッダーで Client ID を渡すこともできます。
Custom API クライアントの Client Secret です。他の grant type と同様に、
HTTP Basic Auth を使用して Authorization ヘッダーで Client Secret を渡すこともできます。代替手段については、Auth0 Authentication API リファレンスドキュメント を参照してください。OBO トークン交換 では、token_endpoint_auth_method を none に設定できない点に注意してください。(任意) 下流呼び出しに対して要求する特定の権限を、スペース区切りのリストで指定します。指定しない場合は、対象 audience に対してユーザーに付与されているすべてのスコープが、RBAC ポリシーに基づいて含まれます。
レスポンス
act クレームでは、エージェントが最も外側のactorとして配置され、サブジェクトトークンの既存の委任チェーンがネストされた内側の act として保持されます。
レスポンスフィールド
下流 API 向けにスコープ指定された、新しい Auth0 のアクセストークンです。この JSON Web Token (JWT) には、サブジェクトトークン と同じ
sub (ユーザー ID) が含まれ、aud にはリクエストされた下流 API の audience が設定されます。act クレーム は委任チェーンを追跡します。エージェントにリンクされたクライアントが交換を実行し、下流 API でエージェントのサブジェクトクレームが有効になっている場合、エージェントは act クレームの最も外側のactorとなり、サブジェクトトークンからの以前の委任チェーンはネストされた内側の act として保持されます。詳細については、act クレームを参照してください。返されるトークンの形式を示します。これはリクエスト内の
requested_token_type と一致します。値: urn:ietf:params:oauth:token-type:access_token