トークンを取得

On-Behalf-Of（OBO）トークン交換を使用すると、中間層サービスは受信したユーザートークンを、下流サービス向けにスコープが設定された新しいトークンに交換できます。

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-login Action trigger がトリガーされます。このとき、event.transaction.protocol には oauth2-token-exchange が設定され、event.transaction.actor には完全な委任チェーンが記録されます。

• 委任チェーンは 5 段階までネストできます。交換時に現在のクライアントがさらに 1 段階として追加されるため、サブジェクトトークンがすでに 4 段階の act ネストレベルを持っている場合、OBO トークン交換は失敗します。

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

​

パラメーター

DPoP · string

リクエスト用の DPoP プルーフです。これは任意項目で、アプリケーションで Demonstrating Proof-of-Possession を使用している場合にのみ必要です。

auth0-forwarded-for · string

エンドユーザーの IP アドレスを文字列で指定します。サーバーサイドのシナリオで Suspicious IP Throttling 保護を有効にしたい場合は、これを設定してください。

​

リクエストボディ

grant_type · string · 必須

使用するフローを示します。On-Behalf-Of Token Exchange の場合は、urn:ietf:params:oauth:grant-type:token-exchange を使用します。

subject_token_type · string · 必須

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

subject_token · string · 必須

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

requested_token_type · string · 必須

返却を希望するトークンの種類を示します。On-Behalf-Of Token Exchange の場合は、urn:ietf:params:oauth:token-type:access_token を使用します。

client_id · string · 必須

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

client_secret · string · 必須

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

audience · string · 必須

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

scope · string

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

​

レスポンス

ステータス	説明
200	正常なレスポンスです。ユーザー ID を維持したまま、下流 API 用のアクセストークンを返します。
400	不正なリクエストです。サブジェクトトークンにすでに 4 階層のネストされた act が含まれており、これがこの交換で拡張できる最大値である場合や、必須パラメーターが不足している場合に発生することがあります。
401	未認証です。サブジェクトトークンが無効か有効期限切れであるか、クライアント認証情報が誤っています。
403	アクセスが拒否されました。クライアントにトークン交換を実行する権限がないか、ユーザーにターゲットaudienceに対して要求されたスコープがありません。

200 レスポンス

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

エージェントにリンクされたクライアントが交換を実行すると、返されたアクセストークンのデコードされた act クレームでは、エージェントが最も外側のactorとして配置され、サブジェクトトークンの既存の委任チェーンがネストされた内側の act として保持されます。

{
  "act": {
    "sub": "agt_72jbvv7LfRKYp59gtRLtkn",
    "sub_profile": "ai_agent",
    "client_id": "K1AUPhZq8mRi0Q0pjhkfu1D7y6KjDQja",
    "iss": "https://tenant.auth0.com/",
    "act": {
      "sub": "mcp_server_client_id",
      "client_id": "mcp_server_client_id",
      "sub_profile": "service ai_agent",
      "iss": "https://tenant.auth0.com/"
    }
  }
}

​

レスポンスフィールド

access_token · string

下流 API 向けにスコープ指定された、新しい Auth0 のアクセストークンです。この JSON Web Token (JWT) には、サブジェクトトークン と同じ sub (ユーザー ID) が含まれ、aud にはリクエストされた下流 API の audience が設定されます。act クレーム は委任チェーンを追跡します。

エージェントにリンクされたクライアントが交換を実行し、下流 API でエージェントのサブジェクトクレームが有効になっている場合、エージェントは act クレームの最も外側のactorとなり、サブジェクトトークンからの以前の委任チェーンはネストされた内側の act として保持されます。詳細については、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

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