> ## Documentation Index
> Fetch the complete documentation index at: https://auth0.generaltranslation.app/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 アプリケーション: Web ベースの生産性向上アプリがユーザーの Google Calendar に接続し、ユーザーに再認証を求めることなく、ミーティングのスケジュール設定などのタスクをユーザーに代わって実行します。
* モバイルアプリケーション: モバイルのフォトギャラリーアプリがユーザーの Google Photos アカウントに接続し、写真が撮影されるたびに自動的にアップロードし、バックグラウンドでアクセストークンを更新することでユーザーのログイン状態を維持します。

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

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

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

具体的な例で見ていきましょう。あるユーザーが、ウェブアプリケーションを使用して自身の Google カレンダーに会議を予約したいとします。

<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 へのアクセスをユーザーに許可してもらう必要があります。

ユーザーは、[Connected Accounts フロー](/docs/ja-JP/secure/tokens/token-vault/connected-accounts-for-token-vault#how-it-works) を使用して Google 経由でアプリケーションにログインします。このフローは [My Account API](/docs/ja-JP/manage-users/my-account-api) を利用します。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](/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"
}'
```

<table class="table">
  <thead>
    <tr>
      <th><strong>パラメーター</strong></th>
      <th><strong>説明</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>grant\_type</code></td>
      <td>グラントタイプ。Token Vault の場合、<code>urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token</code> を設定します。</td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>クライアントアプリケーションの ID</td>
    </tr>

    <tr>
      <td><code>client\_secret</code></td>
      <td>クライアントシークレット。<strong>注:</strong> 外部プロバイダーのアクセストークンを取得するために、任意のクライアント認証方式を使用できます。</td>
    </tr>

    <tr>
      <td><code>subject\_token\_type</code></td>
      <td>サブジェクトトークンのタイプ。Token Vault の場合、リフレッシュトークンを表す <code>urn:ietf:params:oauth:token-type:refresh\_token</code> を設定します。</td>
    </tr>

    <tr>
      <td><code>subject\_token</code></td>
      <td>Auth0 認可サーバーがユーザーを特定するために検証する Auth0 のリフレッシュトークン。</td>
    </tr>

    <tr>
      <td><code>requested\_token\_type</code></td>
      <td>要求するトークンタイプ。Token Vault の場合、外部プロバイダーのアクセストークン、または <code>[http://auth0.com/oauth/token-type/federated-connection-access-token](http://auth0.com/oauth/token-type/federated-connection-access-token)</code> を設定します。</td>
    </tr>

    <tr>
      <td><code>connection</code></td>
      <td>接続名。この例では <code>google-oauth2</code> です。</td>
    </tr>

    <tr>
      <td><code>login\_hint</code></td>
      <td>(オプション) ユーザーが同じ接続に対して複数のアカウントを持つ場合にのみ、`login_hint` を使用します (例: 仕事用 Google アカウントと個人用 Google アカウント)。トークン交換時に `login_hint` に値を渡すことで、ユーザーの複数のリンク済みアカウントのうち、どのアカウントに対するリクエストかを明示的に指定します。</td>
    </tr>
  </tbody>
</table>

<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` の両方に一致するアイデンティティを検索します。
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 年以上トークン交換で使用されていない場合も削除されます。