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

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

Token Vault はアクセストークン交換をサポートしており、これによりクライアントアプリケーションは Auth0 のアクセストークン (subject token) を外部プロバイダーのアクセストークン (requested token) に交換できます。

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

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

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

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

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

​

ユースケース

アクセストークン交換の一般的なユースケースには、次のものがあります。

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

​

仕組み

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

実際の例で見ていきましょう。ユーザーは SPA を使用して Google カレンダーに会議を登録したいと考えています。

​

前提条件

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

​

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

会議をスケジュールするには、SPA は Auth0 経由で Google に接続し、そのうえで Google Calendar API へのアクセスについてユーザーの許可を得る必要があります。 ユーザーは、My Account API を使用する Connected Accounts flow を通じて、Google 経由でアプリケーションにログインします。アプリケーションで Organizations を使用している場合は、続行する前に、ユーザーは対象の組織にサインインします。

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

​

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

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

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

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

​

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

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

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

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

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

• バックエンド API (カスタム API クライアント) のクライアント認証情報を Auth0 認可サーバーに渡して、自身を認証します。
• 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 認可サーバーが検証する 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 認可サーバーがアクセストークンを検証する

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

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

Auth0 認可サーバーは、ユーザーの検証が完了すると、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を呼び出し、会議をスケジュールします。