> ## 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のリフレッシュトークン (サブジェクトトークン) を外部プロバイダーのアクセストークン (要求対象のトークン) に交換できます。

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

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

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

* Web アプリケーション: ブラウザベースの生産性向上アプリがユーザーの Google Calendar に接続し、ユーザーに再認証を求めることなく、会議のスケジュール調整などの作業をユーザーに代わって行います。
* モバイルアプリケーション: モバイル向けの写真ギャラリーアプリがユーザーの 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 でリフレッシュトークン交換を設定する](/docs/ja-jp/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](/docs/ja-jp/manage-users/my-account-api) を使用する [Connected Accountsフロー](/docs/ja-jp/secure/tokens/token-vault/connected-accounts-for-token-vault#how-it-works) を通じて、Google でアプリケーションにログインします。アプリケーションが [Organizations](/docs/ja-jp/manage-users/organizations) を使用している場合、ユーザーは続行する前に対象の organization にサインインします。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はRefresh Tokenのローテーションをサポートしていませんが、追加のセキュリティ対策として、[DPoP](/docs/ja-jp/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"
}'
```

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

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

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 のアクセストークンを返します。

```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 年以上使用されていないトークンも削除されます。