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

> ## Agent Instructions
> ### Authlete versions
> Authlete 3.0 is the current version. Unless the user says they use another version, answer for Authlete 3.0 using the 3.x documentation.
> Documentation for Authlete 2.x (pages under `/v2/` and `/ja/v2/`) is for the legacy version. Refer to it only when the user is on Authlete 2.x.
>
> ### Authlete architecture
> Authlete is a backend engine for OAuth 2.0 and OpenID Connect processing. End users and client applications do not call it directly; the service provider's authorization server and API server call Authlete's APIs. Authlete handles protocol processing and token, client, and service management, while the service provider owns the OAuth/OIDC endpoints and user authentication.
> See [Architecture](https://developers.authlete.com/get-started/introduction-to-authlete/architecture.md).
>
> ### Concepts
> If the user is new to Authlete, read these pages first:
> - [Request and Response](https://developers.authlete.com/get-started/concepts/request-and-response.md): Core API requests pass the client's request parameters as-is, and responses return `resultCode`, `action`, and `responseContent`.
> - [Action Handling](https://developers.authlete.com/get-started/concepts/action-handling.md): Branch on `action`, never on `resultCode`, and map each action to the HTTP response your server returns.
> - [Two-Step API Calls](https://developers.authlete.com/get-started/concepts/two-step-api-calls.md): Actions such as `INTERACTION` are completed with a second call (`/auth/authorization/issue` or `/auth/authorization/fail`) linked by a `ticket`.
> - [Management API Overview](https://developers.authlete.com/get-started/concepts/overview.md): The Management API configures services, manages clients, and operates issued tokens, separately from the protocol flows handled by the Core API.
> - [API Authentication](https://developers.authlete.com/get-started/concepts/authentication.md): Authlete APIs use bearer tokens: a Service Access Token (one service) or an Organization Token (the whole organization).

# Authlete 3.0 へのトークンの移行

> Authlete 2.2 または 2.3 から Authlete 3.0 へトークンをコピーし、認可サーバーの切り替えを計画します。

## 概要

トークン移行は、Authlete 2.2/2.3 環境（移行元環境）で発行されたトークンを、新しい Authlete 3.0 環境（移行先環境）へコピーする処理です。トークンを移行すると、認可サーバーを Authlete 3.0 環境へ切り替えた後も、それらのトークンを有効なまま利用できます。トークン移行は任意です。

トークンを移行しない場合、移行元環境で発行されたトークンは Authlete 3.0 環境には存在しないものとして扱われます。実装にもよりますが、それらのトークンを使った更新やイントロスペクションが失敗するため、多くの場合ユーザーの再認証が必要になります。

トークン移行は、Authlete が提供するサービスであるトークン移行ツールが行います。トークン移行ツールは、実行中に移行元環境を定期的に確認して新しいトークンと既存トークンの変更を検出し、移行先環境へコピーします。トークン移行ツールは移行元のデータベースに対する読み取りアクセス権のみを持ち、移行元のデータは変更しません。

### 移行されるもの

* 移行対象のクライアントのアクセストークン。「[クライアントのトークン移行の条件](#クライアントのトークン移行の条件)」を満たすクライアントが移行対象となります。
* リフレッシュトークン。リフレッシュトークンは対応するアクセストークンと一緒に保存されているため、アクセストークンとあわせて移行されます。リフレッシュトークン用の個別の手順や設定はありません。

### 移行されないもの

* トークンの削除イベント。
* 認可コード、リクエスト URI などの一時的に保存されるデータ。
* 移行先環境で発行・変更されたトークン。コピーは移行元環境から移行先環境への一方向です。

## 対応バージョンとデプロイメントモデル

トークン移行は、Authlete 2.2/2.3 から最新の Authlete 3.0 リリースへ、同じデプロイメントモデルかつ同じリージョンの場合に限り可能です。現在 Authlete 2.2 または 2.3 を使用しておらず、Authlete 3.0 への移行を希望する場合は、サポートチームにお問い合わせください。環境のアップグレードを支援します。

トークン移行ツールを誰が実行するかは、デプロイメントモデルによって異なります。

| デプロイメントモデル | トークン移行ツールの実行者 | 開始と停止 | ドライラン |
| - | - | - | - |
| 共用環境 | Authlete | 常時稼働しており、停止できない | 利用不可 |
| 専用環境 | Authlete | Authlete サポートに依頼する | 利用不可 |
| セルフマネージド環境 | 利用者 | 利用者がデプロイ・削除する | 利用可能 |

ドライランは、移行先環境へ書き込まずにトークン移行ツールを実行するモードです。

共用環境と専用環境には、次の注意点があります。

* クライアントの「Synchronize Client Tokens」設定を無効にしても、そのクライアントが移行対象から外れるのは次回の確認以降です。「Synchronize Client Tokens」は、クライアントをトークン移行の対象として指定する設定です。
* 移行元のサービスを削除しても、トークン移行ツールは停止しません。

セルフマネージドの Kubernetes 環境でトークン移行ツールを実行する方法は、Kubernetes インストールガイドの「[移行フェーズ（任意）](/ja/deployment-and-operations/self-managed-deployment/kubernetes-installation-guide#移行フェーズ（任意）)」を参照してください。トークン移行ツールの運用については、「[トークン移行ツールの処理時間と間隔](/ja/deployment-and-operations/self-managed-deployment/token-migrator/token-migrator-timing-and-intervals)」「[トークン移行ツールの停止と再開](/ja/deployment-and-operations/self-managed-deployment/token-migrator/stopping-and-resuming-token-migrator)」「[トークン移行ツールのログの読み方](/ja/deployment-and-operations/self-managed-deployment/token-migrator/interpreting-token-migrator-logs)」もあわせて参照してください。

## クライアントのトークン移行の条件

トークン移行ツールがクライアントのトークンを移行するのは、移行元環境のクライアントと移行先環境のクライアントを、対応するクライアントとして識別できた場合のみです。これらの要件は、クライアントのトークンが移行先環境の正しいクライアントへ移行されることを保証するため、厳密に定められています。両方のクライアントが、次の条件を満たす必要があります。

* `clientId` の値が一致していること（`clientIdAlias` は考慮されません）
* 両方のクライアントが属する `serviceId`（`api_key`）が、両方の環境で同じであること
* 移行先のクライアントで「Synchronize Client Tokens」設定が有効になっていること
* `clientSecret` の値が一致していること

### 条件を満たす方法

サービスとクライアントの設定を移行するときに、次のように設定すると、クライアントが条件を満たします。

* [Authlete 管理コンソールでインポートする](/ja/deployment-and-operations/migration-from-existing-system/migrating-settings-from-an-older-version-of-authlete#authlete-管理コンソールによる移行（共用環境のみ）)場合（共用環境）は、「Synchronize Client Tokens」と「Migrate Client Secrets」のチェックボックスを選択します。「Migrate Client Secrets」を選択しない場合、クライアントシークレットはランダムに生成されます。
* [Configuration Migrator](/ja/deployment-and-operations/migration-from-existing-system/migrating-settings-from-an-older-version-of-authlete#configuration-migrator-による移行（専用環境・セルフマネージド環境）) を使用する場合（専用環境・セルフマネージド環境）は、`SYNC_CLIENT_TOKENS=true` と `MIGRATE_CLIENT_SECRETS=true`（デフォルト値）のままにします。

インポート後に、個々のクライアントを更新することもできます。

* 「クライアント設定」>「基本設定」>「詳細設定」>「Migration Settings」で「Synchronize Client Tokens」を有効にします。
* [Update Client Secret](/api-reference/client-management/update-client-secret) API（`/api/{serviceId}/client/secret/update/{clientIdentifier}`）を呼び出して、特定のクライアントのシークレットを更新します。

エンドツーエンドの移行プロセスを小規模でテストするには、ひとつのクライアントだけで「Synchronize Client Tokens」を有効にし、そのクライアントのトークンのみを移行します。トークンが移行されるのはトークン移行ツールの実行中に限られる点に注意してください。

### 移行対象外のクライアントの確認

* 共用環境・専用環境: トークン移行の対象外となったクライアントは通知されません。移行を始める前に、上記の条件を確認してください。
* セルフマネージド環境: トークン移行ツールが、移行対象のクライアントと、シークレットが一致しないクライアントをログに出力します。「[移行対象クライアントの決定](/ja/deployment-and-operations/self-managed-deployment/token-migrator/interpreting-token-migrator-logs#移行対象クライアントの決定)」を参照してください。

## 移行の所要時間

所要時間は、主に次の要素で決まります（影響の大きい順）。

* 移行対象のクライアント数: 初回は 1 クライアントあたり約 1〜2 秒
* トークンの量: 1 クライアント内で 100 万トークンあたり約 70 分

ダウンタイムの時間帯を決める前に、検証環境で計測してください。

共用環境では、同時に他のユーザーがトークンを移行している可能性があるため、遅延が発生することもあります。

## 切り替え方式の選択

切り替え（カットオーバー）とは、認可サーバーの接続先を移行元環境から Authlete 3.0 環境へ切り替えることです。Authlete の移行元環境と通信しているアプリケーションは、新しい Authlete 3.0 環境を指すように更新する必要があります。

必要な変更は構成によって異なりますが、次のようなものがあります。

* Authlete の SDK を使用している場合は、API バージョンの変更
* Authlete 2.2/2.3 と Authlete 3.0 でエンドポイント構造が異なることに伴う、エンドポイントの更新
* Authlete 2.2/2.3 と Authlete 3.0 で認証方式が異なることに伴う、認証情報の更新
* 設定の変更
* 自社の認可サーバーのバージョン更新

次のいずれかの方式を選択します。

| 方式 | 概要 | ダウンタイム | 前提条件 |
| - | - | - | - |
| [一括トークン移行](#一括トークン移行) | アプリケーションを停止してトークンを移行し、切り替える | 手順 1〜4 の間 | — |
| [ジャストインタイム（JIT）移行同期](#ジャストインタイム（jit）移行同期) | アプリケーションの稼働中にトークンを移行して同期し続け、切り替える | 手順 3 のみ | — |
| [無停止（並行切り替え）](#無停止（並行切り替え）) | トークンの移行中、認可サーバーが両方の環境を使用する | なし | サービスとクライアントの移行より前に、認可サーバーの変更をデプロイしておくこと |

一括トークン移行とジャストインタイム（JIT）移行同期のどちらを選ぶかは、主に移行するトークンの量と、自社サービスで許容できるダウンタイムの長さによって決まります。

認可サーバーを移行元環境に再接続してロールバックした場合、切り替え後に Authlete 3.0 環境で発行されたトークンは 3.0 環境には残りますが、移行元環境へはコピーされないため、サービスからは失われます。

### 一括トークン移行

1. Authlete の移行元環境に接続しているアプリケーションを停止します（専用環境では、Authlete サポートと調整した日時に実施）
2. クライアントを移行して設定を同期し、「[クライアントのトークン移行の条件](#クライアントのトークン移行の条件)」を満たすようにします（「[条件を満たす方法](#条件を満たす方法)」を参照してください）。これにより、そのクライアントのトークンがトークン移行ツールによって移行されます。専用環境では、あわせて Authlete サポートにトークン移行ツールの開始を依頼します。セルフマネージド環境では、トークン移行ツールをデプロイします
3. 移行が完了するまで待ちます（専用環境では Authlete サポートから連絡があります。それ以外の場合は「[進捗の確認](#進捗の確認)」を参照してください）
4. アプリケーションを更新し、新しい Authlete 3.0 環境に接続します
5. 専用環境とセルフマネージド環境では、トークン移行ツールを停止します（「[切り替え後の対応](#切り替え後の対応)」を参照してください）

* ロールバック: 認可サーバーの変更を元に戻し、Authlete の移行元環境に再接続します

### ジャストインタイム（JIT）移行同期

1. クライアントを移行して設定を同期し、「[クライアントのトークン移行の条件](#クライアントのトークン移行の条件)」を満たすようにします（「[条件を満たす方法](#条件を満たす方法)」を参照してください）。これにより、そのクライアントのトークンがトークン移行ツールによって移行されます。専用環境では、あわせて Authlete サポートと決めた日時にトークン移行ツールの開始を依頼します。セルフマネージド環境では、トークン移行ツールをデプロイします
2. すべてのトークンが Authlete 3.0 環境に作成されるまで待ちます（専用環境では Authlete サポートから連絡があります）
3. アプリケーションを更新し、新しい Authlete 3.0 環境に接続します
4. 専用環境とセルフマネージド環境では、トークン移行ツールを停止します（「[切り替え後の対応](#切り替え後の対応)」を参照してください）

手順 2 から手順 4 までの間、トークン移行ツールは移行元環境のトークンの変更を監視し、移行先環境へコピーし続けます。

* ロールバック: 認可サーバーの変更を元に戻し、Authlete の移行元環境に再接続します

### 無停止（並行切り替え）

この方式では、サービスとクライアントの Authlete 3.0 環境への移行を始める前に、認可サーバーを変更する必要があります。また、その時点で Authlete 3.0 環境が利用可能になっていなければなりません。
この方式を実装した認可サーバーのサンプルを [authlete/java-oauth-server-migration](https://github.com/authlete/java-oauth-server-migration) で公開しています。

この方式では、認可サーバーが Authlete 3.0 サーバー（プライマリ）と Authlete 2.2/2.3 サーバー（セカンダリ）の両方に接続します。受信したリクエストは、デフォルトでまずプライマリに委譲されます。認可サーバーは、プライマリの応答、または 3.0 専用のエンドポイントかどうかに応じて、プライマリの応答を返すか、リクエストをセカンダリに委譲します。

トークン移行ツールがバックグラウンドで動作し、トークンが Authlete 3.0 環境で利用可能になるにつれて、プライマリの API が処理できるリクエストの割合が増えていきます。

すべてのトークンが Authlete 3.0 環境にコピー・更新されると、アプリケーションへのすべてのリクエストが Authlete 3.0 環境で処理されるようになります。この時点で移行は完了です。Authlete 2.2/2.3 環境ではそれ以上トークンの変更が発生しないはずです。

## 進捗の確認

トークン移行の進捗は、組織の監査ログで確認できます。

* 監査ログのエントリーには、4 時間のローリングウィンドウ内で作成・更新されたトークン数が表示されます。
* エントリーは、トークンが移行先環境に実際に永続化されたときにのみ書き込まれます。
* エントリーのタイムスタンプは更新されません。トークンが移行されるにつれて、作成数と更新数のみが増えます。
* エントリーが変化していなくても、トークン移行ツールが停止しているとは限りません。

セルフマネージド環境では、ログの読み方の「[トークン移行のイテレーション](/ja/deployment-and-operations/self-managed-deployment/token-migrator/interpreting-token-migrator-logs#トークン移行のイテレーション)」もあわせて参照してください。

## 移行の検証

移行の完了後は、次の方法でトークンが正しく移行され有効であることを確認できます。

* 3.0 環境の Authlete の [Process Introspection Request](/api-reference/introspection-endpoint/process-introspection-request) API にトークンを渡します。
* セルフマネージド環境でデータベースに直接アクセスできる場合は、移行元と移行先のデータベースでクライアントまたはサービスごとのトークン数を比較します。

## 切り替え後の対応

切り替えの完了後は、トークンに対するすべての操作を Authlete 3.0 環境でのみ行ってください。

デプロイメントモデルに応じて、トークン移行ツールを停止します。

* 共用環境: トークン移行ツールは稼働し続け、停止できません。
* 専用環境: Authlete サポートに停止を依頼します。
* セルフマネージド環境: 「[トークン移行ツールの削除](/ja/deployment-and-operations/self-managed-deployment/kubernetes-installation-guide#5-トークン移行ツールの削除)」の手順で削除します。

## トラブルシューティング

### クライアントのトークンが移行されない

クライアントが「[クライアントのトークン移行の条件](#クライアントのトークン移行の条件)」をすべて満たしているかを確認します。クライアントシークレットが一致しない場合は、次のいずれかを行います。

* `MIGRATE_CLIENT_SECRETS=true` で Configuration Migrator を再実行します。
* [Update Client Secret](/api-reference/client-management/update-client-secret) API を呼び出して、移行先のクライアントのシークレットを更新します。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.