On-Behalf-Of Token Exchange

• Client Credentials Flow: アプリケーションは自身の代理として動作し、自身として認証されます。リクエストがユーザーによって開始された場合でも、そのコンテキストは失われます。ダウンストリームサービスが認識できるのは、呼び出し元アプリケーションのIDだけです。
• On-Behalf-Of (OBO) Token Exchange: アプリケーションはユーザーにスコープが付与されたトークンを受け取り、それを新しいトークンに交換してダウンストリームサービスを呼び出せます。これにより、元のエンドユーザーのIDとコンテキストが呼び出しチェーン全体で保持されます。

• 元のユーザーのIDと権限を維持する
• Service B 用に特化したスコープが設定されている
• Service B がエンドユーザーに基づいて認可の判断を行えるようにする

• event.transaction.protocol は oauth2-token-exchange に設定されます。
• event.transaction.actor は完全な委譲チェーンを追跡します。

​

ユースケース

• ユーザーに代わってファーストパーティ API を呼び出す必要がある MCP サーバー
• ユーザーに代わってダウンストリームサービスを呼び出す必要があるマイクロサービス

​

仕組み

​

例: MCPサーバーがファーストパーティAPIを呼び出す

​

ステップ 1: ユーザー認証

{
  "sub": "auth0|user123",
  "aud": "https://mcp-server.example.com",
  "azp": "spa_client_id" // またはトークンの仕様によっては "client_id"
}

​

ステップ 2: OBO 交換

{
  "sub": "auth0|user123",
  "aud": "https://first-party-api.example.com",
  "azp": "mcp_server_client_id", // またはトークンの仕様によっては "client_id"
  "act": {
    "sub": "mcp_server_client_id",
    "act": {
      "sub": "spa_client_id"
    }
  }
}

​

act クレーム

• 最も外側の act.sub: mcp_server_client_id (直前に token exchange を行った MCP サーバー)
• ネストされた act.sub: spa_client_id (元のクライアントアプリケーション)

{
  "sub": "auth0|user123",
  "aud": "https://calendar-api.acme.com",
  "azp": "first_party_api_client_id",
  "act": {
    "sub": "first_party_api_client_id",
    "act": {
      "sub": "mcp_server_client_id",
      "act": {
        "sub": "spa_client_id"
      }
    }
  }
}

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

​

User > MCPサーバー > API フロー

1. ユーザー認証: ユーザーはクライアントアプリケーションで認証を行います。Auth0 Authorization Server は、MCP サーバー向けのscopeを持つ Token A を発行します。
2. 最初のリクエスト: クライアントアプリケーションは MCP Server を呼び出し、Authorization: Bearer ヘッダーで Token A を渡します。
3. 検証とトークン交換: MCP サーバーは Token A を受け取り、検証したうえで、Auth0 Authorization Server の /oauth/token エンドポイントに渡します。OBO token exchange を使用して、MCP サーバーは subject_token として Token A を提示し、ファーストパーティ API 用の新しい token をリクエストします。
4. トークン発行: Auth0 Authorization Server は Token B を発行します。Token B は Token A と同じ sub (ユーザー ID) を持ちますが、aud (audience) はファーストパーティ API になります。
5. ダウンストリーム呼び出し: MCP Server は Token B を使用してファーストパーティ API を呼び出します。API は Token B を検証し、そのリクエストが正当に元のユーザーに「代わって」行われていることを確認します。

​

ユーザー > API1 > API2 > API3

1. ユーザー認証: ユーザーはクライアントアプリケーションで正常に認証されます。Auth0 Authorization Server は、API1 向けのスコープを持つ Token A を発行します。
2. 最初のリクエスト: クライアントアプリケーションは API1 を呼び出し、Authorization: Bearer ヘッダーで Token A を渡します。
3. API1 から API2 への委譲: API1 は Token A を受け取って検証した後、Auth0 Authorization Server の /oauth/token エンドポイントに渡します。OBO token exchange を使用して、API1 は Token A を subject_token として提示し、API2 向けの新しいトークンを要求します。
4. トークンの発行: Auth0 Authorization Server は API1 に新しいアクセストークンである Token B を付与します。Token B は Token A と同じ sub (ユーザー ID) を持ちますが、aud (オーディエンス) は API2 になります。
5. ダウンストリーム呼び出し: API1 は Token B を使用して API2 にリクエストを送信します。
6. API2 から API3 への委譲: API2 は Token B を受け取って検証した後、Auth0 Authorization Server の /oauth/token エンドポイントに渡します。OBO token exchange を使用して、API2 は Token B を subject_token として提示し、API3 向けの新しいトークンを要求します。
7. トークンの発行: Auth0 Authorization Server は API2 に新しいアクセストークンである Token C を付与します。Token C は Token A および Token B と同じ sub (ユーザー ID) を持ちますが、aud (オーディエンス) は API3 になります。
8. ダウンストリーム呼び出し: API2 は Token C を使用して API3 にリクエストを送信します。API3 は Token C を検証し、そのリクエストが元のユーザーに代わって正当に行われていることを確認します。

​

前提条件

• app_type を resource_server に設定します。
• resource_server_identifier を有効なリソースサーバー (例: https://my-api.example.com) に設定します。Auth0 は、認可リクエストでリソースサーバー identifier を audience パラメーターとして使用します。

​

カスタム API クライアントを作成

• Auth0 Dashboard
• Management API

Auth0 Dashboard でカスタム API クライアントを作成するには、次の手順に従います。

1. Applications > APIs に移動し、バックエンド API を選択します。

2. Add Application を選択し、アプリケーション名を入力します。
3. Add を選択します。

アプリケーションが正常に作成されたら、Configure Application を選択して確認し、Application Properties までスクロールします。Application Type は カスタム API クライアント です。

リソースサーバーと同じ識別子を持つカスタム API クライアントを作成するには、次のリクエストボディを指定して /api/v2/clients エンドポイントに POST リクエストを送信します。

• Auth0 CLI
• cURL

Auth0 CLI を使用していますか？まだの場合は、このコマンドを実行する前に CLI セッションをセットアップして認証してください。

auth0 api post "clients" \
  --data '{
    "name": "Custom API Client",
    "app_type": "resource_server",
    "resource_server_identifier": "https://my-api.example.com"
  }'

curl --request POST 'https://{yourDomain}/api/v2/clients' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN' \
  --data '{
    "name": "Custom API Client",
    "app_type": "resource_server",
    "resource_server_identifier": "https://my-api.example.com"
  }'

パラメーター	説明
name	カスタム API クライアントの名前。
app_type	カスタム API クライアントのアプリケーションタイプ。resource_server に設定します。
resource_server_identifier	カスタム API クライアントの一意の識別子。リソースサーバーの audience (つまり https://my-api.example.com) に設定します。

​

クライアントグラントを作成

auth0 api post "client-grants" \
  --data '{
    "client_id": "YOUR_CLIENT_ID",
    "audience": "https://my-api.example.com",
    "scope": [
      "read:item"
    ],
    "subject_type": "user"
  }'

curl --location 'https://{yourDomain}/api/v2/client-grants' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN' \
  --data '{
    "client_id": "YOUR_CLIENT_ID",
    "audience": "https://my-api.example.com",
    "scope": [
      "read:item"
    ],
    "subject_type": "user"
  }'

​

OBO token exchange を設定する

• Auth0 Dashboard
• Management API

1. アプリケーション > アプリケーション に移動し、カスタム API クライアントを選択します。
2. Token Exchange で、On-Behalf-Of Token Exchange をオンにします。
3. Save を選択します。

次のリクエストボディを指定して、/api/v2/clients/{clientId} エンドポイントに PATCH リクエストを送信します。

• Auth0 CLI
• cURL

auth0 api patch "clients/{clientId}" \
  --data '{
    "token_exchange": {
      "allow_any_profile_of_type": ["on_behalf_of_token_exchange"]
    }
  }'

curl --location --request PATCH 'https://{yourDomain}/api/v2/clients/{clientId}' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN' \
  --data '{
    "token_exchange": {
      "allow_any_profile_of_type": ["on_behalf_of_token_exchange"]
    }
  }'

​

OBO token exchange を実行する

import { ApiClient } from '@auth0/auth0-api-js';

const apiClient = new ApiClient({
  domain: 'YOUR_AUTH0_DOMAIN',
  audience: 'YOUR_MCP_SERVER_AUDIENCE',
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
});

const result = await apiClient.getTokenOnBehalfOf(accessToken, {
  audience: 'YOUR_DOWNSTREAM_API_AUDIENCE',
  scope: 'read:private',  // 省略可能
});

from auth0_api_python import ApiClient, ApiClientOptions

api_client = ApiClient(
    ApiClientOptions(
        domain='YOUR_AUTH0_DOMAIN',
        audience='YOUR_MCP_SERVER_AUDIENCE',
        client_id='YOUR_CLIENT_ID',
        client_secret='YOUR_CLIENT_SECRET',
    )
)

result = await api_client.get_token_on_behalf_of(
    access_token=access_token,
    audience='YOUR_DOWNSTREAM_API_AUDIENCE',
    scope='read:private'  # 省略可能
)

curl --location 'https://YOUR_DOMAIN.us.auth0.com/oauth/token' \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "subject_token": "AUTH0_SUBJECT_TOKEN",
    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
    "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
    "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
    "audience": "https://my-api.example.com"
  }'

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

​

トークンバインディング

• DPoP: 受信した DPoP proof の jwk の JWK SHA-256 thumbprint を計算し (RFC 7638 に従う) 、サブジェクトトークンの cnf.jkt クレーム と一致することを検証します。Auth0 はトークン交換中にこのチェックを実行しません。
• mTLS: クライアント証明書の DER エンコーディングの SHA-256 thumbprint を base64url エンコードし、サブジェクトトークンの cnf.x5t#S256 クレーム と一致することを検証します。

​

Organizations のサポート

• org_id がテナント内に存在すること
• ユーザー (sub で識別される) がその organization のメンバーであること

• 元のトークンと同じ org_id クレームを含む
• 同じ organization 固有の RBAC ポリシーを適用する
• post-login Actions トリガーで、event.organization プロパティを通じて organization のコンテキストを利用できるようにする