Token Vault を使用したリフレッシュトークン交換

アプリケーションが Token Vault にアクセスし、Auth0 のリフレッシュトークンをアクセストークンに交換して外部 API を呼び出す方法を説明します。

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

リフレッシュトークンは、クライアントと認可サーバー間の安全なバックチャネルでのみ交換されるため、エンドユーザーに公開されることはありません。そのため、クライアントはユーザーに接続の再認可を求めることなく、ユーザーのセッションを維持できます。

​

ユースケース

リフレッシュトークン交換の一般的なユースケースには、次のようなものがあります。

• Web application: Web ベースの生産性向上アプリがユーザーの Google Calendar に接続し、会議のスケジュール設定などのタスクをユーザーに代わって実行します。これにより、ユーザーは再認証せずに利用を継続できます。
• Mobile application: モバイル写真ギャラリーアプリがユーザーの Google Photos アカウントに接続し、撮影した写真を自動的にアップロードします。バックグラウンドでアクセストークンを更新することで、ユーザーのログイン状態を維持します。

​

仕組み

次のシーケンス図は、Auth0 でリフレッシュトークン交換を使用して外部 API を呼び出すエンドツーエンドの流れを示しています。

では、実際のユースケースで見ていきましょう。ユーザーが Web アプリケーションを使って Google Calendar に会議を予定したいとします。

​

前提条件

開始する前に、Token Vault でのリフレッシュトークン交換を設定する必要があります。

​

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

会議をスケジュールするには、Web アプリケーションが Auth0 経由で Google に接続し、Google Calendar API へのアクセスについてユーザーの許可を得る必要があります。

ユーザーは、My Account API を使用する Connected Accounts flow を通じて、Google 経由でアプリケーションにログインします。アプリケーションで 組織 を使用している場合、ユーザーは続行する前に対象の組織にサインインします。My Account API は Connected Accounts リクエストを検証して完了した後、要求されたカレンダー用のスコープとともに、Google のアクセストークンとリフレッシュトークンを Token Vault に保存します。

​

ステップ 2: リフレッシュトークン交換を実行する

Token Vault はリフレッシュトークンローテーションをサポートしていませんが、セキュリティをさらに強化するために、DPoP を使用して Auth0 が発行したトークンをクライアントにバインドできます。Token Vault でリフレッシュトークン交換を正常に実行するには、Auth0 Dashboard でアプリケーションの Allow Refresh Token Rotation を無効にしてください。

アプリケーションは、有効な Auth0 のリフレッシュトークンを使用して、Connected Accounts フローで付与されたスコープを持つ Google アクセストークンを Token Vault に要求できます。この処理により、ユーザーに接続の再認可を求めることなく、新しいアクセストークンを取得できます。

リフレッシュトークン交換を実行するには、アプリケーションは Auth0 SDK を使用して、次のパラメーターを指定した POST リクエストを /oauth/token エンドポイントに送信します。

curl --request POST 'https://{yourDomain}/oauth/token' \
--header 'Content-Type: application/json' \
--data '{
  "client_id": "<YOUR_CLIENT_ID>",
  "client_secret": "<YOUR_CLIENT_SECRET>",
  "subject_token": "<YOUR_AUTH0_REFRESH_TOKEN>",
  "grant_type": "urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token",
  "subject_token_type": "urn:ietf:params:oauth:token-type:refresh_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	サブジェクトトークンのタイプ。Token Vault では、リフレッシュトークン urn:ietf:params:oauth:token-type:refresh_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 に値を渡すと、ユーザーにリンクされている複数のアカウントのうち、どのアカウントに対するリクエストかを明示的に指定できます。

​

ステップ 3: Auth0 認可サーバーがリフレッシュトークンを検証する

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

1. Auth0 は、ユーザープロファイルの connected_accounts 配列に、認可リクエストで渡された接続名を持つユーザーアカウントが含まれているかどうかを確認します。
2. 認可リクエストに login_hint が含まれている場合、Auth0 は接続名と login_hint の両方に一致する ID を探します。
3. 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 のアクセストークンの有効期限が切れている場合、Auth0 は Token Vault に保存されている Google のリフレッシュトークンを使用して、同じスコープを持つ新しい Google アクセストークンを取得します。

アプリケーションは Google アクセストークンを使用して、ユーザーに代わって Google Calendar API を呼び出します。

​

外部プロバイダーのリフレッシュトークン有効期限ポリシー

Auth0 は、外部プロバイダーで設定された有効期限に基づいて、有効期限切れとなった外部プロバイダーのリフレッシュトークンを削除します。また、1 年を超えてトークン交換に使用されていないトークンも削除されます。