メインコンテンツへスキップ
Token Vault はリフレッシュトークンの交換をサポートしており、これによりクライアントアプリケーションは Token Vault にアクセスして、Auth0 のリフレッシュトークン（subject token）を外部プロバイダーのアクセストークン（requested token）と交換できます。 リフレッシュトークンはクライアントと認可サーバー間の安全なバックチャネル上でのみ交換されるため、エンドユーザーに公開されることはありません。その結果、クライアントはユーザーに再度認可を求めることなく、ユーザーセッションを維持できます。

​
ユースケース

リフレッシュトークン交換の一般的なユースケースには、次のようなものがあります。
  • Web アプリケーション: Web ベースの生産性向上アプリがユーザーの Google Calendar に接続し、ユーザーに再認証を求めることなく、ミーティングのスケジュール設定などのタスクをユーザーに代わって実行します。
  • モバイルアプリケーション: モバイルのフォトギャラリーアプリがユーザーの Google Photos アカウントに接続し、写真が撮影されるたびに自動的にアップロードし、バックグラウンドでアクセストークンを更新することでユーザーのログイン状態を維持します。

​
仕組み

次のシーケンス図は、Auth0 でのリフレッシュトークンのエクスチェンジを使用して外部 API を呼び出すエンドツーエンドの動作を示しています。
具体的な例で見ていきましょう。あるユーザーが、ウェブアプリケーションを使用して自身の Google カレンダーに会議を予約したいとします。

​
前提条件

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

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

ミーティングをスケジュールするには、Web アプリケーションが Auth0 経由で Google に接続し、Google Calendar API へのアクセスをユーザーに許可してもらう必要があります。 ユーザーは、Connected Accounts フロー を使用して Google 経由でアプリケーションにログインします。このフローは My Account API を利用します。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"
}'
パラメーター説明
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_tokenAuth0 認可サーバーがユーザーを特定するために検証する 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 の両方に一致するアイデンティティを検索します。
  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 年以上トークン交換で使用されていない場合も削除されます。