Token Vaultでのリフレッシュトークン交換

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

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

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

​

ユースケース

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

• Web アプリケーション: ブラウザベースの生産性向上アプリがユーザーの Google Calendar に接続し、ユーザーに再認証を求めることなく、会議のスケジュール調整などの作業をユーザーに代わって行います。
• モバイルアプリケーション: モバイル向けの写真ギャラリーアプリがユーザーの Google Photos アカウントに接続し、撮影した写真を自動的にアップロードするとともに、バックグラウンドでアクセストークンを更新してログイン状態を維持します。

​

仕組み

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

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

​

前提条件

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

​

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

ミーティングを予定するには、Web アプリケーションが Auth0 経由で Google に接続し、そのうえで Google Calendar API へのアクセスについてユーザーの許可を得る必要があります。

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

​

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

Token VaultはRefresh Tokenのローテーションをサポートしていませんが、追加のセキュリティ対策として、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"
}'

パラメータ	説明
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 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 に値を渡すと、そのリクエストがユーザーの複数のリンクされたアカウントのうち、どのアカウントを対象としているかを明示的に指定できます。

​

ステップ 3: Auth0 Authorization Server がリフレッシュトークンを検証

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

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

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

​

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

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