> ## Documentation Index
> Fetch the complete documentation index at: https://translations.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

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

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

<div id="use-cases">
  ## ユースケース
</div>

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

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

<div id="how-it-works">
  ## 仕組み
</div>

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

<Frame>
  <img src="https://mintcdn.com/translations/S4csL9vq6QUX5-Rr/docs/images/token-vault/refresh_token_exchange_flow_diagram.png?fit=max&auto=format&n=S4csL9vq6QUX5-Rr&q=85&s=b068da9250227eabdfd307fcfbb34587" alt="" width="1294" height="846" data-path="docs/images/token-vault/refresh_token_exchange_flow_diagram.png" />
</Frame>

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

<div id="prerequisites">
  ## 前提条件
</div>

開始する前に、[Token Vault でのリフレッシュトークン交換を設定する](/ja/docs/secure/tokens/token-vault/configure-token-vault#configure-refresh-token-exchange)必要があります。

<div id="step-1-connect-and-authorize-access">
  ## ステップ 1: 接続してアクセスを承認する
</div>

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

ユーザーは、[My Account API](/ja/docs/manage-users/my-account-api) を使用する [Connected Accounts flow](/ja/docs/secure/tokens/token-vault/connected-accounts-for-token-vault#how-it-works) を通じて、Google 経由でアプリケーションにログインします。アプリケーションで [組織](/ja/docs/manage-users/organizations) を使用している場合、ユーザーは続行する前に対象の組織にサインインします。My Account API は Connected Accounts リクエストを検証して完了した後、要求されたカレンダー用のスコープとともに、Google のアクセストークンとリフレッシュトークンを Token Vault に保存します。

<div id="step-2-perform-refresh-token-exchange">
  ## ステップ 2: リフレッシュトークン交換を実行する
</div>

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  Token Vault はリフレッシュトークンローテーションをサポートしていませんが、セキュリティをさらに強化するために、[DPoP](/ja/docs/secure/sender-constraining/demonstrating-proof-of-possession-dpop) を使用して Auth0 が発行したトークンをクライアントにバインドできます。Token Vault でリフレッシュトークン交換を正常に実行するには、Auth0 Dashboard でアプリケーションの Allow Refresh Token Rotation を無効にしてください。
</Callout>

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

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

```bash lines theme={null}
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` に値を渡すと、ユーザーにリンクされている複数のアカウントのうち、どのアカウントに対するリクエストかを明示的に指定できます。 |

<div id="step-3-auth0-authorization-server-validates-refresh-token">
  ## ステップ 3: Auth0 認可サーバーがリフレッシュトークンを検証する
</div>

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

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

Auth0 認可サーバーがユーザーを検証すると、Token Vault 内で Google のアクセストークンを特定します。トークンがまだ有効であれば、Auth0 は Google のアクセストークンを、そのスコープおよび有効期限とともに返します。

```json lines theme={null}
{
  "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 を呼び出します。

<div id="external-provider-refresh-token-expiration-policy">
  ## 外部プロバイダーのリフレッシュトークン有効期限ポリシー
</div>

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