複数のカスタムドメインへの移行

Auth0 で単一のカスタムドメインから複数のカスタムドメインに移行する方法を説明します。

このガイドでは、単一のカスタムドメイン構成から複数のカスタムドメインへ移行する方法を説明します。ブランド、リージョン、顧客セグメントごとにドメインを追加する場合でも、スムーズに移行できるよう、このガイドで手順を追って説明します。

​

移行シナリオ

ご自身の状況に最も合ったシナリオを選択してください。

シナリオ	説明	ユースケース	複雑さ	ダウンタイム
ドメインを追加する	現在 1 つのカスタムドメインを使用しており、既存のドメインを稼働させたままさらに追加したい場合	複数のブランドやリージョンに対応するための拡張	低	なし
既存のドメインを置き換える	現在のカスタムドメインを新しいものに置き換えたい場合	リブランディングまたはドメイン所有権の変更	中	最小限 (DNS 切り替え時)
正規ドメインから移行する	現在 Auth0 の正規ドメイン (例: tenant.auth0.com) を使用しており、カスタムドメインに移行したい場合	複数のドメインを使用する初回のカスタムドメイン実装	中～高	なし (並行運用)

​

移行前チェックリスト

移行を開始する前に、以下の項目が完了していることを確認してください。

• すべての新しいカスタムドメインのドメイン所有権を確認している
• 現在の認証プロセスと API 統合を確認している
• 現在のドメインを使用しているすべてのアプリケーションを特定している
• 現在のメールテンプレートとリンクを文書化している
• SSL/TLS 証明書を取得している (自己管理証明書を使用している場合)
• 新しいカスタムドメインの設定を開発環境またはステージング環境でテストしている
• ロールバック計画を準備している
• トラフィックの少ない時間帯に移行を予定している (該当する場合)
• 関係者とユーザーに通知している (必要な場合)

​

移行手順

​

新しいカスタムドメインの追加

Auth0 Dashboard または Management API を使用して、新しいカスタムドメインを追加します。

​

ドメインの所有権を確認する

新しいカスタムドメインごとに、ドメインの検証手順を完了します。

​

Auth0 が管理する証明書の場合

1. Auth0 から提供された CNAME レコードを控えます
2. DNS プロバイダーに CNAME レコードを追加します
3. Dashboard または API でドメインを検証します

# 検証の詳細を取得する
curl --request GET \
  --url 'https://{yourDomain}/api/v2/custom-domains/{customDomainId}' \
  --header 'authorization: Bearer {yourMgmtApiAccessToken}'

# DNSレコードを追加した後に検証する
curl --request POST \
  --url 'https://{yourDomain}/api/v2/custom-domains/{customDomainId}/verify' \
  --header 'authorization: Bearer {yourMgmtApiAccessToken}'

​

自己管理の証明書の場合

1. 必要な TXT レコードを DNS に追加します
2. リバースプロキシまたは CDN を設定します
3. SSL 証明書をアップロードします
4. ドメインを検証します

​

デフォルトドメインを設定する (任意)

メールおよび API 呼び出しで特定のドメインをデフォルトで使用する場合は、デフォルトドメインとして設定:

curl --request PATCH \
  --url 'https://{yourDomain}/api/v2/custom-domains/{customDomainId}' \
  --header 'authorization: Bearer {yourMgmtApiAccessToken}' \
  --header 'content-type: application/json' \
  --data '{
    "is_default": true
  }'

​

アプリケーションの設定を更新する

各アプリケーションが適切なカスタムドメインを使用するように設定を更新します。

​

SDK の設定

Auth0 SDK の初期化設定を更新します。

必要なのは、domain パラメータを Auth0 の正規ドメインから新しいカスタムドメインに更新することだけです。

​

コールバックURL

Auth0 Dashboard でアプリケーションのコールバックURLを更新します。

1. Auth0 Dashboard > Applications に移動します。設定するアプリケーションを選択し、Settings タブを開きます。
2. Allowed Callback URLs を更新し、新しいドメインを追加します。
   https://new-domain.example.com/callback
   
3. Allowed Logout URLs を更新します。
   https://new-domain.example.com/logout
   
4. Allowed Web Origins を更新します。
   https://new-domain.example.com
   

​

メールテンプレートを更新する

メールテンプレートでカスタムドメインの情報を利用できるようにするには、次の手順を実行します。

1. ブランディング > カスタムドメイン に移動します
2. 使用するドメインをデフォルトに設定します
3. 必要に応じてメールテンプレートをカスタマイズし、“From” アドレス、件名、本文でカスタムドメインの情報を使用します

ドメインをデフォルトに設定しても、メールの内容が自動的に変更されるわけではありません。これにより、デフォルトドメインのコンテキストをメールテンプレートで利用できるようになります。その情報を使用するには、テンプレートをカスタマイズする必要があります。auth0-custom-domain ヘッダーで特定のドメインが指定されていない場合は、デフォルトドメインのコンテキストが利用可能になります。

​

ソーシャルIDプロバイダー (IdP) を更新する

ソーシャルIDプロバイダーのリダイレクトURIを更新します。

​

Google

1. Google Cloud Console を開きます
2. APIs & Services > Credentials に移動します
3. Authorized redirect URIs に https://new-domain.example.com/login/callback を追加します

​

Facebook

1. Facebook Developers にアクセスします
2. アプリの Facebook Login > Settings に移動します
3. Valid OAuth Redirect URIs に https://new-domain.example.com/login/callback を追加します

​

その他のプロバイダー

各プロバイダーのドキュメントに従って、設定済みのすべてのソーシャルプロバイダーのリダイレクト URI を更新してください。

​

エンタープライズ接続を更新する (該当する場合)

SAML、WS-Fed、Azure AD、またはその他のエンタープライズ接続を使用している場合は、各接続の設定を更新します。

​

SAML 接続

Assertion Consumer Service (ACS) URL を更新します。

https://new-domain.example.com/login/callback?connection={connectionName}

SP-initiated SAML リクエストを使用していて、IdP が動的 ACS をサポートしている場合は、IdP 側で ACS URL を手動で更新する必要はありません。

​

Azure AD 接続

1. Azure Active Directory > App registrations に移動します
2. 対象のアプリを選択し、Authentication を選択します
3. Redirect URIs に https://new-domain.example.com/login/callback を追加します

​

ADFS 接続

ADFS の設定でエンドポイントを更新し、新しいカスタムドメインを使用するようにします。

​

認証のテスト

移行を完了する前に、次の項目を十分にテストしてください。

1. ユーザーログイン: ユーザーが新しいドメイン経由で認証できることを確認します
2. パスワードリセット: パスワードリセットメールで正しいドメインが使用されていることを確認します
3. メールアドレス確認: メールアドレス確認用のリンクが機能することを確認します
4. ソーシャルログイン: 設定済みの各ソーシャルプロバイダーをテストします
5. API 呼び出し: API 呼び出しが新しいドメインで正しく動作することを確認します
6. トークン検証: JWT に正しい iss クレームが含まれていることを確認します

​

監視と検証

移行後:

1. 認証ログを監視し、エラーがないか確認する
2. メールの配信状況とリンクが正しく機能するかを確認する
3. SSL 証明書の有効性と有効期限を確認する
4. 異なる地域からテストする (該当する場合)
5. すべてのアプリケーションで想定したカスタムドメインが使用されていることを確認する

​

古いドメインを廃止する (該当する場合)

既存のカスタムドメインを置き換える場合:

1. すべてのアプリケーションが新しいドメインに移行済みであることを確認します
2. 古いドメインへのトラフィックを監視し、すでに使用されていないことを確認します
3. 猶予期間中は古いドメインを有効なまま維持することを検討します
4. 準備ができたら、古いカスタムドメインを削除します:

curl --request DELETE \
  --url 'https://{yourDomain}/api/v2/custom-domains/{oldCustomDomainId}' \
  --header 'authorization: Bearer {yourMgmtApiAccessToken}'

​

移行パターン

並行運用（ダウンタイムなし）

古いカスタムドメインと新しいカスタムドメインを同時に運用します。

1. 新しいカスタムドメインを追加する
2. 新しいアプリケーションが新しいドメインを使用するように更新する
3. 既存のアプリケーションは古いドメインのまま維持する
4. アプリケーションを段階的に移行する
5. 移行完了後に古いドメインを廃止する

利点: ダウンタイムなし、段階的なロールアウト、容易なロールバック

欠点: 一時的に管理負荷が増える

アプリケーションごとの段階的移行

アプリケーションを1つずつ移行します。

1. 優先度またはリスクに基づいてアプリケーションを特定する
2. リスクの低いアプリケーションから先に移行する
3. 問題がないか監視してから次に進む
4. 残りのアプリケーションを移行する
5. 古い設定をクリーンアップする

利点: 制御しやすいロールアウト、問題の早期検出

欠点: 移行期間が長くなる

ブルーグリーンデプロイメント

テスト用に別々の環境を使用します。

1. ステージング環境に新しいカスタムドメインを設定する
2. すべての機能を十分にテストする
3. 1回の作業で本番環境を切り替える
4. 古いドメインをバックアップとして残す
5. 検証期間の後に廃止する

利点: 十分なテスト、迅速なロールバック

欠点: 別環境が必要

​

既存のユーザーセッションへの対応

カスタムドメインの移行時には、既存のユーザーセッションに影響が生じる可能性があります。

​

セッションに関する考慮事項

• 旧ドメインで作成されたセッションは、有効期限が切れるまで引き続き有効です
• 新規ログインでは、新ドメインのセッションが作成されます
• クロスドメインのセッションは慎重に計画する必要があります

​

推奨アプローチ

1. ユーザーへの通知: 再度ログインが必要になる可能性があることをユーザーに通知します
2. 猶予期間: 移行期間中は古いドメインを引き続き有効にしておきます
3. セッションの移行: セッションの移行にはUniversal Loginを使用します
4. 明確な案内: 問題が発生した場合に備えて、ユーザーに明確な手順を案内します

​

ロールバック計画

移行中に問題が発生した場合は、次の手順に従ってください。

​

即時ロールバック

1. アプリケーション設定を以前のドメインを使用するように戻します
2. 今後の再試行に備えて、新しいカスタムドメインの設定は維持します
3. トラブルシューティングのために問題を記録します

​

部分的なロールバック

1. 影響を受けるアプリケーションを特定します
2. 該当するアプリケーションだけを古いドメインに戻します
3. 問題を調査して修正します
4. 準備が整ったら再移行します

​

完全なロールバック

1. すべてのアプリケーション設定を更新し、古いドメインを使用するように戻す
2. デフォルトドメインを設定している場合は、それも古いドメインに戻す
3. 必要な対応がある場合は、ユーザーに通知する
4. あらためて移行を試行する予定を立てる

​

トラブルシューティング

​

よくある問題と解決策

問題	原因	解決策
ドメイン検証に失敗する	DNS レコードがまだ伝播していない	DNS の伝播を待ちます (最大 48 時間かかる場合があります) 。CNAME レコードが正しいことを確認します
ログイン時に古いドメインへリダイレクトされる	アプリケーション設定が更新されていない	SDK の初期化設定とコールバック URL を更新します
メール内のリンクで誤ったドメインが使用される	デフォルトドメインが設定されていない	デフォルトドメインを設定するか、メールのルーティングを構成します
ソーシャルログインに失敗する	リダイレクト URI が更新されていない	ソーシャルプロバイダーの許可済みリダイレクト URI に新しいカスタムドメインを追加します
トークンの発行元が無効	JWT の検証で古いドメインを想定している	新しいドメインを発行元として受け入れるようにトークン検証を更新します
SAML アサーション エラーが発生する	ACS URL が更新されていない	新しいカスタムドメインの URL を使用して SAML 設定を更新します
証明書エラー	証明書がプロビジョニングされていない、または有効期限が切れている	ドメインを確認し、証明書のプロビジョニング完了を待つか、証明書を更新します

​

サポートを受ける

移行中に問題が発生した場合は、次の手順を実施してください。

1. Auth0 Community で同様の問題が報告されていないか確認します
2. トラブルシューティングのドキュメント を確認します
3. 次の情報を添えて Auth0 Support にお問い合わせください:
   • テナント名
   • カスタムドメイン ID
   • 問題の詳細な説明
   • 再現手順
   • エラーメッセージまたはログ

​

移行後のベストプラクティス

移行が完了したら:

1. 設定を文書化する: どのアプリケーションがどのカスタムドメインを使用しているかを記録します
2. 証明書の有効期限を監視する: 証明書の更新に備えてアラートを設定します
3. 定期的に見直す: カスタムドメインの設定がビジネス要件に合っていることを確認します
4. ランブックを更新する: 新しいカスタムドメイン情報を運用ドキュメントに反映します
5. チームメンバーをトレーニングする: チームが新しいマルチドメイン構成を理解していることを確認します
6. 拡張を見据えて計画する: 今後、追加のドメインをどのように管理するかを検討します

​

詳しく見る

• 複数のカスタムドメイン
• デフォルトのカスタムドメイン
• 複数のカスタムドメインの Management API
• 機能でカスタムドメインを使用するよう設定する
• カスタムドメインのトラブルシューティング