Token Vault を使用したアクセストークン交換

アプリケーションが Token Vault にアクセスし、外部 API を呼び出すためのアクセストークンと Auth0 アクセストークンを交換する方法を学びます。

Token Vault はアクセストークン交換をサポートしており、クライアントアプリケーションは Auth0 アクセストークン (サブジェクトトークン) を外部プロバイダーのアクセストークン (要求トークン) と交換できます。

Single-Page Application (SPA) がバックエンド API を呼び出す際、Authorization ヘッダーに渡されるのは Auth0 アクセストークンのみです。バックエンド API は SPA に発行されたリフレッシュトークンを受け取らないため、外部 API を呼び出すために Token Vault にアクセスする リフレッシュトークン交換 は使用できません。

代わりに、バックエンド API は SPA から受け取った Auth0 アクセストークンを外部プロバイダーのアクセストークンと交換できます。これがアクセストークン交換です。このプロセスにより、機密性の高い外部の資格情報をバックエンド側で安全に保護できます。

Auth0 のアクセストークン交換では、バックエンド API はクライアントとリソースサーバーの両方の役割を果たします。

• クライアント: 自身の資格情報を使用して、Auth0 Authorization Server とのアクセストークン交換を安全に実行します。Auth0 では、バックエンド API と同じ識別子を持つカスタム API クライアントを作成します。バックエンド API は、カスタム API クライアントの資格情報を渡して、Auth0 Authorization Server とのアクセストークン交換を安全に実行します。
• リソースサーバー: SPA にバックエンド API を提供し、Auth0 アクセストークンを検証します。

バックエンド API は SPA と Auth0 Authorization Server の仲介役として機能することで、未承認のクライアントが Auth0 トークンを盗み、ユーザーに代わってそれを使って外部プロバイダーにアクセスすることを防ぎます。

​

利用例

アクセストークン交換の一般的な利用例には、次のようなものがあります。

• バックエンド API: ユーザーが SPA を操作し、その後、バックエンド API が Auth0 Authorization Server に対して、Auth0 アクセストークンを外部プロバイダーのアクセストークンに交換するためのリクエストを送信します。
• マイクロサービス アーキテクチャ: 外部 API にアクセスするためにアクセストークンの交換が必要な、MCP サーバーやその他の OAuth 2.0 リソースサーバーなどのバックエンドサービス。

​

仕組み

次のシーケンス図は、Auth0 のアクセストークン交換を使って外部 API を呼び出すまでの一連の流れをエンドツーエンドで示しています。

実際のユースケースで見ていきましょう。ユーザーが SPA を使って Google Calendar に会議を予定したい場合を考えます。

​

前提条件

開始する前に、Token Vault でアクセストークン交換を設定する必要があります。

​

ステップ 1: 接続してアクセスを認可する

ミーティングを設定するには、SPA が Auth0 を介して Google に接続し、Google Calendar API にアクセスするためのユーザーの許可を得る必要があります。 ユーザーは、My Account API を使用する Connected Accounts flow を通じて、Google 経由でアプリケーションにログインします。アプリケーションで Organizations を使用している場合は、先に対象の organization にサインインしてから続行します。

My Account API が Connected Accounts のリクエストを検証して完了すると、要求されたカレンダーのスコープとともに、Google のアクセストークンとリフレッシュトークンが Token Vault に保存されます。

​

ステップ 2: SPA が Auth0 アクセストークンを使用してバックエンド API を呼び出す

SPA がバックエンド API を呼び出す際は、Authorization ヘッダーに Auth0 アクセストークンを設定してバックエンド API に渡します。バックエンド API は、次の点を確認して Auth0 アクセストークンを検証します。

• 署名: Auth0 の公開キーを使用してトークンの署名を検証します。これにより、そのアクセストークンが Auth0 によって発行されたことを確認できます。
• 発行者: トークンのペイロード内の iss クレームを確認し、そのトークンがあなたの Auth0 テナントによって発行されたことを確かめます。
• Audience: aud クレームを確認し、それがバックエンド API 自体の一意の識別子と一致することを確かめます。これにより、そのトークンがこのリソースサーバー向けに発行されたものであることを確認できます。
• 有効期限: exp クレームを検証し、そのトークンがまだ有効であり、期限切れになっていないことを確認します。
• スコープ: scope クレームを確認し、ユーザーにどの permissions が付与されているかを判断します。

これらの確認がすべて正常に完了すると、バックエンド API は Auth0 アクセストークンを信頼し、トークン交換に進むことができます。

​

ステップ 3: バックエンド API がアクセストークン交換を実行する

アクセストークン交換を行うには、バックエンド API にリンクされたカスタム API クライアントを作成する必要があります。カスタム API クライアントはバックエンド API と同じ識別子を持ち、Token Vault のグラントタイプが有効になっています。

バックエンド API がアクセストークン交換を実行する際は、カスタム API クライアントの資格情報を Auth0 Authorization Server に渡して自身を認証し、Auth0 Dashboard に登録されたものと同一のエンティティであることを証明します。

アクセストークン交換を実行するには、バックエンド API は Auth0 SDKs を使用して /oauth/token エンドポイントに POST リクエストを送信します。

トークンリクエストでは、バックエンド API は次のことを行います。

• 自身を認証するために、バックエンド API (カスタム API クライアント) のクライアント資格情報を Auth0 Authorization Server に渡します。
• Auth0 アクセストークンを Google アクセストークンと交換します。

curl --request POST 'https://{yourDomain}/oauth/token' \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "<YOUR_CUSTOM_API_CLIENT_ID>",
    "client_secret": "<YOUR_CUSTOM_API_CLIENT_SECRET>",
    "subject_token": "<YOUR_AUTH0_ACCESS_TOKEN>",
    "grant_type": "urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token",
    "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
    "requested_token_type": "http://auth0.com/oauth/token-type/federated-connection-access-token",
    "connection": "google-oauth2"
  }'

Parameter	Description
grant_type	グラントタイプ。Token Vault では、urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token に設定します。
client_id	クライアントアプリケーション ID
client_secret	クライアントシークレット。注: 外部プロバイダーのアクセストークンの取得には、任意のクライアント認証方式を使用できます。
subject_token_type	サブジェクトトークンの種類。アクセストークン交換では、アクセストークンを表す urn:ietf:params:oauth:token-type:access_token に設定します。
subject_token	Auth0 Authorization Server が、ユーザーを識別するために検証する Auth0 アクセストークン。
requested_token_type	要求するトークンの種類。Token Vault では、外部プロバイダーのアクセストークン、または http://auth0.com/oauth/token-type/federated-connection-access-token に設定します。
connection	接続名。この場合は google-oauth2 です。
login_hint	(任意) login_hint は、ユーザーが同じ接続に複数のアカウント (仕事用の Google アカウントや個人用の Google アカウントなど) を持っている場合にのみ使用します。トークン交換時に login_hint に値を渡すと、ユーザーにリンクされている複数のアカウントのうち、どのアカウントに対するリクエストかを明示的に指定できます。

​

ステップ 4: Auth0 Authorization Server がアクセストークンを検証する

Auth0 Authorization Server は、Auth0 アクセストークンに関連付けられたユーザープロファイルを検証し、読み込みます。

• Auth0 は、トークン交換リクエストを行うクライアントが、アクセストークンの audience で識別されるバックエンド API にリンクされていることを確認します。
• Auth0 は、ユーザープロファイルの connected_accounts array に、認可リクエストで渡された接続名を持つユーザーアカウントが含まれているかどうかを確認します。
• 認可リクエストに login_hint が含まれている場合、Auth0 は接続名と login_hint の両方に一致する ID を探します。
• Auth0 がユーザーを見つけられない場合、エラーメッセージとともに 401 ステータスコードを返します。

Auth0 Authorization Server がユーザーを検証すると、Token Vault 内で Google アクセストークンを探します。まだ有効であれば、Auth0 は Google アクセストークンをそのスコープと有効期限とともに返します。

{
  "access_token": "<YOUR_GOOGLE_ACCESS_TOKEN>",
  "scope": "https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/calendar.addons.execute https://www.googleapis.com/auth/calendar.events https://www.googleapis.com/auth/calendar.events.readonly https://www.googleapis.com/auth/calendar.settings.readonly https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile openid",
  "expires_in": 1377,
  "issued_token_type": "http://auth0.com/oauth/token-type/federated-connection-access-token",
  "token_type": "Bearer"
}

Google のアクセストークンを使用して、バックエンド API はユーザーに代わって Google Calendar API を呼び出し、会議をスケジュールします。