Skip to main content

​
概要

Authlete 3.0へのアップグレードは、稼働中のAuthlete 2.3に対して直接行うことはできません。そのため、Authlete 3.0環境を新しく作成し、最初に設定、サービス、およびクライアントを移行させる必要があります。 サービスおよびクライアントの移行中は、token-migrationを通してアクセストークンを移行させることも可能です。これはAuthlete 2.3環境からAuthlete 3.0環境へトークンをコピー、および更新する新機能です。これにより、Authlete 2.3環境にて発行された既存のトークンが、新しく作成されたAuthlete 3.0環境でも利用可能になります。 一般的なアップグレード手順は以下の通りになります：
  1. 新しく作成されたAuthlete 3.0の管理コンソールにログイン
  2. 移行に必要な組織数を作成および設定
  3. サービスおよびクライアントの移行（下記セクションを参照）- Import/Migrate機能を使用して、該当するサービスおよびクライアントを作成された組織にインポート
  4. トークン移行 - 既存トークンを新しい3.0環境で利用可能にする必要がある場合のみ実施
  5. OAuthサーバー / アプリケーションの更新
注記 : トークン移行ツールはソースDBに対して参照アクセス権のみを持ち、いかなるデータも変更することはできません

​
サービス設定の移行の流れ

  1. Authlete 3の管理コンソールへログインし、組織設定 > 基本設定 > データインポート/移行のメニューを開きます
  2. Authlete 2のサービスオーナーコンソールへログインし、アカウント設定から、サービスオーナーAPIキー、およびAPIシークレットをコピーして、移行フォームに貼り付けます
authlete2-so-console Authlete 2のアカウント設定画面
  1. 利用中のクラスターのAuthlete API URLを記入します
  1. 続行ボタンをクリックします
migration-form サービス設定の移行フォーム
  1. APIからそのアカウントに紐づいたサービスのリストが返されます
  2. 移行したいサービスのチェックボックスにチェックを入れます
  3. クラスターを選択のドロップダウンをクリックし、移行先となるクラスターを選択します
service-selection サービスの選択画面
  1. 続行ボタンをクリックします
  2. 確認画面に表示されるインポートボタンをクリックします
  3. Authlete 3のコンソールUIにサービスとそれに紐づいたクライアントが表示されるようになります
migration-confirmation 移行の確認画面

​
トークン移行

任意なトークン移行は、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>エンドポイントを呼び出して更新可能

​
OAuth サーバー / アプリケーションの更新

Authlete 2.3環境と通信しているアプリケーションは、新しいAuthlete 3.0環境を指すように更新する必要があります。 必要な変更は使用中のシステムよって異なりますが、主なものとしては：
  • SDKを使用している場合のAPI バージョンの変更
  • Authlete 3.0における認証メカニズムおよびエンドポイント構造の変更に伴う、エンドポイントまたは認証情報の更新
  • 設定変更
  • 認証サーバーのバージョン更新
ダウンタイムを伴うハードカットオーバー方式、および移行期間中にダウンタイムを発生させないスローカットオーバー方式の両方についてサポートを提供することも可能です。

​
即時カットオーバーアップグレード

この方法でも認証アプリケーションの変更は必要になりますが、それに加えてAuthlete 2.3環境からAuthlete 3.0環境へ切り替えるためにハードカットオーバーを実施する必要があります。 この方法には、主に移行するトークン数と、許容可能なサービス停止時間に依存する2つの選択肢があります：

​
バルクトークン移行（ステップ a → d の間でダウンタイムが発生）

  1. Authlete 2.3環境に接続されているアプリケーションを停止（Authleteチームと調整したスケジュールで実施）
  2. Authleteサポートチームへ通知し、token-migrationサービスを開始
  3. token-migration完了後にAuthleteチームから通知
  4. アプリケーションを更新し、新しいAuthlete 3.0環境へ接続
  5. ロールバック：認証サーバーの変更を元に戻し、Authlete 2.3環境へ再接続

​
Just In Time (JIT) 移行同期（ステップ c のみでダウンタイムが発生）

  1. Authleteチームとtoken-migrationサービス有効化の時間を設定
  2. すべてのトークンが作成され、以降の変更がtoken-migrationサービスによって監視・コピーされることの通知を受け取る
  3. アプリケーションを更新し、新しいAuthlete 3.0環境へ接続
  4. ロールバック：認証サーバーの変更を元に戻し、Authlete 2.3環境へ再接続

​
無停止（並行カットオーバー）アップグレード

この方法では、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へ移行したい場合は、サポートチームまでお問い合わせください。

​
トラブルシューティング & FAQ

Q: 移行の進捗を確認するには？
A: 組織画面の監査ログ内の専用ログエントリを更新することによって、リアルタイムで進捗を確認することできます。
Q: クライアントのシークレットが新しい3.0環境でも同じになるようにするには？
A: サービス設定の移行時にMigrate Client Secretsチェックボックスにチェックを入れてください。チェックが入らなかった場合、クライアントシークレットはランダムに生成されます。
Q: 単一クライアントのみでトークン移行機能をテストするには？
A: UIのSynchronize Client Tokensフラグを使用し、そのクライアントのみをトークン移行対象として指定することできます。これにより、小規模でのE2E移行テストが可能になります。
Q: トークンの変更や新規トークンはどのように扱われますか？
A: token-migratorサービスが対象クライアントのトークン変更および新規作成イベントをポーリングし、検出時に移行先データベースへ更新／作成を行います。