Table of Contents
こちらのドキュメントでは、Authlete 2.xからAuthlete 3.0へのサービス設定の移行について解説します。
Authlete 3.0へのアップグレードは、稼働中のAuthlete 2.3に対して直接行うことはできません。そのため、Authlete 3.0環境を新しく作成し、最初に設定、サービス、およびクライアントを移行させる必要があります。
サービスおよびクライアントの移行中は、token-migrationを通してアクセストークンを移行させることも可能です。これはAuthlete 2.3環境からAuthlete 3.0環境へトークンをコピー、および更新する新機能です。これにより、Authlete 2.3環境にて発行された既存のトークンが、新しく作成されたAuthlete 3.0環境でも利用可能になります。
一般的なアップグレード手順は以下の通りになります：
Import/Migrate機能を使用して、該当するサービスおよびクライアントを作成された組織にインポート注記 : トークン移行ツールはソースDBに対して参照アクセス権のみを持ち、いかなるデータも変更することはできません
組織設定 > 基本設定 > データインポート/移行のメニューを開きます
続行ボタンをクリックします
クラスターを選択のドロップダウンをクリックし、移行先となるクラスターを選択します
続行ボタンをクリックしますインポートボタンをクリックします
任意なトークン移行は、Authlete 2.3環境で以前に発行されたトークンを、引き続きAuthlete 3.0環境でも利用可能かつ有効にすることができます。
token-migrationサービスは、Authlete 2.3環境からAuthlete 3.0環境へアクセストークンをコピーします。実行中はAuthlete 2.3環境をポーリングし、新しいトークンまたはトークンアップデートを検出し、それらをAuthlete 3.0環境へ反映させます。トークンは、Authlete 2.3とAuthlete 3.0の両方の環境に存在し、かつSynchronize Client Tokens設定が有効になっているクライアントに対してのみコピーされます。
この処理は、移行対象データの量によって時間を要する可能性がありますので注意が必要です。現時点では、100万トークンの移行に対して約60分かかります。トークン数が多いクライアントの場合、これらのトークンがAuthlete 3.0環境で利用可能になるまでに遅延が発生する可能性があります。
また、Authleteの共有環境においては、同時にトークン移行を行っている他のユーザーがいる可能性もあるため、遅延が発生する場合があります。
トークン移行の進捗は、組織の監査ログにて確認ができ、4時間のローリングウィンドウ内で作成および更新されたトークン数が表示されます。
移行完了後は、トークンイントロスペクションエンドポイント（3.0におけるPOST /api/{serviceId}/auth/introspection）を使用することで、トークンが正しく移行され有効であることが確認できます。また、オンプレミス環境にてデータベースへ直接アクセスができる場合は、ソースおよび移行先データベースにおいてクライアントもしくはサービスごとのトークン数を比較することでも確認することができます。
トークン移行ツールがクライアントを正しく一致するものとして識別し、そのトークンを移行させるためには、ソースおよび移行先の両方のシステムにおいて特定の要件を満たす必要があります。
これらの要件は、クライアントのシークレットが移行先システムにおいて正しいクライアントに移行されることを保証するために厳密に定義されています。
以下の条件は、両クライアント（ソースシステムに存在するものと、移行先システムに存在するもの）で満たされる必要があります：
clientIdの値が一致していること（clientIdAliasは無視されます）serviceId（api_key）が両システムにおいて同一であることSynchronize Client Tokens設定が有効であること
Client Settings > Basic Settings > Advanced > Migration Settingsの設定画面から設定可能clientSecretの値が一致していること
/api/<service-id>/client/secret/update/<client-id>エンドポイントを呼び出して更新可能Authlete 2.3環境と通信しているアプリケーションは、新しいAuthlete 3.0環境を指すように更新する必要があります。
必要な変更は使用中のシステムよって異なりますが、主なものとしては：
ダウンタイムを伴うハードカットオーバー方式、および移行期間中にダウンタイムを発生させないスローカットオーバー方式の両方についてサポートを提供することも可能です。
この方法でも認証アプリケーションの変更は必要になりますが、それに加えてAuthlete 2.3環境からAuthlete 3.0環境へ切り替えるためにハードカットオーバーを実施する必要があります。
この方法には、主に移行するトークン数と、許容可能なサービス停止時間に依存する2つの選択肢があります：
token-migrationサービスを開始token-migration完了後にAuthleteチームから通知token-migrationサービス有効化の時間を設定token-migrationサービスによって監視・コピーされることの通知を受け取るこの方法では、Authlete 3.0への移行／アップグレード前に認証アプリケーションの変更が必要ですが、利用可能なAuthlete 3.0環境の立ち上げが必要になります。
OAuthサーバーのサンプル実装は以下のリポジトリにて公開されています： https://github.com/authlete/java-oauth-server-migration。
ここでは、認可サーバーがAuthlete 3.0（プライマリ）およびAuthlete 2.3（セカンダリ）の両方に接続するように変更されています。受信リクエストはデフォルトでまずプライマリに送信され、その応答（または3.0専用エンドポイントであるかどうか）に応じて、そのまま応答を返すか、セカンダリAPIへフォールバックするかが決定されます。
これらのアプリケーション変更は、サービスおよびクライアントのAuthlete 3.0環境への移行を開始する前に行う必要があります。
token-migrationサービスがバックグラウンドで動作し、トークンがAuthlete 3.0環境で利用可能になっていくにつれて、プライマリAPIが処理できるリクエストの割合が徐々に増加します。
トークンのAuthlete 3.0環境へのコピー／更新が完了すれば、すべてのリクエストがAuthlete 3.0環境によって処理されるようになります。この時点で移行は完了し、以降Authlete 2.3環境においてトークンの変更は発生せず、すべての処理が最新のAuthlete 3.0環境にて行われます。
現時点では、トークン移行はAuthlete 2.3と最新となるAuthlete 3.0パッチバージョン間でのみ可能となっており、また同一のデプロイメントモデルおよびリージョンである必要があります。
将来的には、共有クラスターから専用クラスターへのトークン移行のサポートや、オンプレミス環境における移行に関する移行手順のドキュメントなどの提供も予定しています。
Authlete 2.3を使用していないがAuthlete 3.0へ移行したい場合は、サポートチームまでお問い合わせください。
A: 組織画面の監査ログ内の専用ログエントリを更新することによって、リアルタイムで進捗を確認することできます。
A: サービス設定の移行時にMigrate Client Secretsチェックボックスにチェックを入れてください。チェックが入らなかった場合、クライアントシークレットはランダムに生成されます。
A: UIのSynchronize Client Tokensフラグを使用し、そのクライアントのみをトークン移行対象として指定することできます。これにより、小規模でのE2E移行テストが可能になります。
A: token-migratorサービスが対象クライアントのトークン変更および新規作成イベントをポーリングし、検出時に移行先データベースへ更新／作成を行います。