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

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

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

​

移行シナリオ

状況に最も合うシナリオを選択してください。

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

​

移行前チェックリスト

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

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

​

移行手順

​

新しいカスタムドメインを追加する

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

​

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

新しいカスタムドメインごとに、ドメイン所有権の確認手続きを完了します。

​

Auth0 管理の証明書を使用する場合

1. Auth0 から提供された CNAME レコードを控えておきます
2. DNS プロバイダーに CNAME レコードを追加します
3. Auth0 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. DNS に必要な TXT レコードを追加します
2. リバースプロキシまたは CDN を設定します
3. SSL 証明書をアップロードします
4. ドメインを検証します

​

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

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

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 > アプリケーション に移動し、設定するアプリケーションを選択して、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. Branding > Custom Domains に移動します
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. 有効な OAuth リダイレクト URI に 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 起点の SAML リクエストを使用し、IdP が動的 ACS を受け入れる場合、IdP 側で ACS URL を手動で更新する必要はありません。

​

Azure AD 接続

1. Azure Active Directory > App registrations に移動します
2. アプリ > Authentication を選択します
3. リダイレクト URI に 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 の初期化設定と callback URL を更新する
メール内のリンクで誤ったドメインが使われる	デフォルトドメインが設定されていない	デフォルトドメインを設定するか、メールルーティングを設定する
ソーシャルログインに失敗する	Redirect URI が更新されていない	ソーシャルプロバイダーの許可済み Redirect URI に新しいカスタムドメインを追加する
トークン発行者が無効	JWT の検証で古いドメインを想定している	新しいドメインを issuer として受け入れるようにトークンの検証を更新する
SAML アサーションエラー	ACS URL が更新されていない	新しいカスタムドメイン URL で SAML の設定を更新する
証明書エラー	証明書がプロビジョニングされていないか、有効期限が切れている	ドメインを確認し、証明書のプロビジョニングが完了するまで待つか、証明書を更新する

​

サポートを受ける

移行中に問題が発生した場合は、以下をお試しください：

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

​

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

移行が完了したら:

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

​

詳しくはこちら

• 複数のカスタムドメイン
• デフォルトのカスタムドメイン
• 複数のカスタムドメイン向け Management API
• カスタムドメインを使用する機能を設定する