トークンの取得

On-Behalf-Of（OBO）トークン交換では、中間層サービスが受信したユーザー トークンを、ダウンストリーム サービス向けにスコープされた新しいトークンに交換できます。

POST /oauth/token

On-Behalf-Of (OBO) トークン交換 (RFC 8693) では、中間層サービスがユーザーにスコープされたトークンを、ダウンストリーム サービスを呼び出すための新しいトークンに交換できます。

新しいトークンは、元のユーザーのアイデンティティと権限を維持したまま、ダウンストリーム サービス専用にスコープされます。これにより、そのサービスはエンドユーザーに基づいて認可の判断を行えます。デリゲーション チェーンは act (actor) クレームで追跡され、各レベルは呼び出しチェーン内のサービスを表します。詳細については、On-Behalf-Of トークン交換のドキュメント を参照してください。

​

注意事項

• リソースサーバーに関連付けられたカスタム API クライアントのみが、OBO トークン交換を使用できます。カスタム API クライアントには、次の要件があります。

  • app_type を resource_server に設定します。
  • resource_server_identifier を有効なリソースサーバー (つまり https://my-api.example.com) に設定します。Auth0 は、認可呼び出しでリソースサーバー識別子を オーディエンス パラメーターとして使用します。

• アプリケーションに発行されるスコープは、要求したスコープと異なる場合があります。この場合、レスポンス JSON に scope パラメーターが含まれます。スコープは、ユーザーのロールベースアクセス制御 (RBAC) ポリシーに基づきます。

• OBO トークン交換では、post-login Action トリガーが実行されます。このとき、event.transaction.protocol は oauth2-token-exchange に設定され、event.transaction.actor で完全なデリゲーションチェーンが追跡されます。

• デリゲーションチェーンは、5 つのネストレベルまでに制限されています。サブジェクトトークンにすでに 5 つの act ネストレベルがある場合、OBO トークン交換は失敗します。

• API 呼び出しごとに新しいトークンを要求するのではなく、アクセストークンの有効期間中はそれをキャッシュしてください。アクセストークンは有効期限が切れるまで再利用できます。トークン交換を繰り返すと、リソースを無駄に消費し、レイテンシーが増加し、レート制限に達する可能性があります。

​

パラメーター

DPoP · string

リクエスト用の DPoP プルーフです。これは省略可能で、アプリケーションで 所有証明の提示 を使用している場合にのみ必要です。

auth0-forwarded-for · string

エンドユーザーの IP を文字列値で指定します。サーバー側のシナリオで 不審な IP スロットリング 保護を有効にする場合は、これを設定します。

​

リクエストボディ

grant_type · string · 必須

使用するフローを示します。On-Behalf-Of トークン交換 では、urn:ietf:params:oauth:grant-type:token-exchange を使用します。

subject_token_type · string · 必須

サブジェクトトークンの種類です。On-Behalf-Of トークン交換 では、urn:ietf:params:oauth:token-type:access_token を使用します。

subject_token · string · 必須

中間層サービスが現在保持している、ユーザーまたは上流サービスから受け取った Auth0 アクセストークンです。

requested_token_type · string · 必須

返却を要求するトークンの種類を示します。On-Behalf-Of トークン交換 では、urn:ietf:params:oauth:token-type:access_token を使用します。

client_id · string · 必須

カスタム API クライアントのクライアントIDです。カスタム API クライアントは、リソースサーバー (同じ識別子) に関連付けられている必要があります。他のグラントタイプと同様に、HTTP Basic Auth を使用して Authorization ヘッダーでクライアントIDを渡すこともできます。

client_secret · string · 必須

カスタム API クライアントのクライアントシークレットです。他のグラントタイプと同様に、HTTP Basic Auth を使用して Authorization ヘッダーでクライアントシークレットを渡すこともできます。代替方法については、Auth0 Authentication API リファレンスドキュメントを参照してください。OBO トークン交換では、token_endpoint_auth_method を none に設定できない点に注意してください。

audience · string · 必須

アクセス先のダウンストリーム API の一意の識別子です。これは、新しいトークンを受け取って検証する下流サービスの識別子です。

scope · string

(省略可) 下流呼び出しに対して要求する特定の権限のスペース区切りリストです。指定しない場合、対象のオーディエンスに対してユーザーに付与されているすべてのスコープが、RBAC ポリシーに基づいて含まれます。

​

レスポンス

ステータス	説明
200	リクエストは成功しました。同じユーザーのアイデンティティを維持したまま、ダウンストリーム API 用のアクセストークンを返します。
400	不正なリクエストです。デリゲーションチェーンの深さが許可されている最大の 4 階層を超えた場合や、必須パラメーターが不足している場合に発生することがあります。
401	未認証です。サブジェクトトークンが無効または期限切れであるか、クライアントクレデンシャルが正しくありません。
403	アクセスが拒否されました。クライアントにトークン交換を実行する権限がないか、ユーザーが対象のオーディエンスに対して要求されたスコープを持っていません。

200 Response

{
  "access_token": "eyJ...",
  "expires_in": 86400,
  "token_type": "Bearer",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
}

{
  "error": "invalid_request",
  "error_description": "Delegation chain (`act` claim) depth exceeds the maximum allowed limit of 5"
}

​

レスポンスフィールド

access_token · string

ダウンストリーム API 向けにスコープ設定された、新しい Auth0 アクセストークンです。この JSON Web Token (JWT) には、サブジェクトトークンと同じ sub (ユーザーのアイデンティティ) が含まれ、aud には要求されたダウンストリーム API のオーディエンスが設定されます。act クレームはデリゲーションチェーンを追跡します。

issued_token_type · string

返されるトークンの形式を示します。これは、リクエストの requested_token_type と一致します。

値: urn:ietf:params:oauth:token-type:access_token

token_type · string

Authorization ヘッダーで使用する認証スキームを指定します。OBO の場合、DPoP を使用していなければ Bearer、使用している場合は DPoP になります。

expires_in · number

トークンの有効期間 (秒) です。

scope · string

(省略可) 付与されたスコープが要求されたスコープと異なる場合にのみ含まれます。実際に付与されたスコープをスペース区切りで示したリストです。