複数のカスタムドメイン

マルチブランドおよびマルチリージョンのデプロイに対応するために、1 つの Auth0 テナント内で複数のカスタムドメインを設定および管理する方法を説明します。

Auth0 では、カスタムドメインを使用すると、ログイン体験を自社のブランドや製品に合わせて統一できます。Multiple Custom Domains を使用すると、1 つの Auth0 テナント内で複数のカスタムドメインを設定できます。この機能は、Public Cloud と Private Cloud の両方の環境で、Enterprise のお客様にご利用いただけます。

​

前提条件

MCD を開始する前に、以下の要件を確認してください。

• ご利用のテナントが Enterprise プランであること (Public Cloud or Private Cloud deployments) 。詳細については、 Manage Subscriptions を参照してください。
• Enterprise プランには、テナントごとに最大 20 件のカスタムドメインに対する基本利用枠が含まれています。
• 基本利用枠を超える追加のカスタムドメインは、アドオン SKU として利用できます。詳細については Auth0 の営業担当者までお問い合わせください。
• 設定するカスタムドメインの所有権を証明できる必要があります。

​

複数のカスタムドメインを設定する

Auth0 Dashboard または Management API を使用して、テナントに複数のカスタムドメインを追加し、管理できます。

Auth0 Dashboard

Auth0 Dashboard でカスタムドメインを作成するには、次の手順に従います。

1. Auth0 Dashboard > ブランディング > カスタムドメイン に移動します。

2. +Add custom domain を選択します。

3. 設定フォームで、次の情報を入力します。

   • ドメイン: 自身が所有する完全修飾ドメイン名を指定します。例: my.custom-domain.com
   • Certificate type: Auth0-managed certificates または Self-managed certificates を選択します。
   • Metadata (Key/Value): region、client_name、client_id などの任意のメタデータを追加すると、ドメインの整理や絞り込みに役立ちます。

4. カスタムドメインの詳細を設定したら、Save を選択します。

新しく追加したドメイン名は、検証が完了するまで pending と表示されます。

​

ドメインの表示と管理

Custom Domains ページには、設定済みのすべてのドメインが表示されます。次のことができます。

• Search: 検索ボックスを使用して名前でドメインを検索する
• Filter: 検証ステータス、証明書タイプ、またはメタデータの値でドメインを絞り込む
• Sort: 名前、作成日、または検証ステータスでドメインを並べ替える
• View details: 任意のドメインをクリックして、詳細な設定、検証ステータス、証明書情報を確認する
• Set default: ドメインをテナントのデフォルトドメインとして指定する

これらの機能により、テナント内の多数のカスタムドメインを効率的に管理できます。

Management API

Management API を使用してカスタムドメインを作成するには、Management API の使用が許可されたマシン間 (M2M) アプリケーションが必要です。詳細については、Management API アクセストークンを参照してください。

1. Dashboard > Applications > Applications に移動し、Create Application をクリックします。

2. アプリケーションを説明する名前を入力し、Machine to Machine Applications を選択します。次に、Create を選択します。

3. APIs ビューに切り替えてから、Auth0 Management API のトグルを有効にします。

4. 行を展開して API の権限を設定します。MCD では、次を選択する必要があります。

   • read:custom_domains
   • create:custom_domains
   • update:custom_domains
   • delete:custom_domains

5. Update を選択します。

6. 設定タブに移動し、クライアントID、クライアントシークレット、ドメインを取得します。

7. Management API アクセストークンの取得を参照し、アクセストークンを取得して保存してください。

​

カスタムドメインの作成

/api/v2/custom-domains エンドポイントに POST リクエストを送信することで、新しいカスタムドメインを作成できます。上記で取得した認証情報を使用して Management API エクスプローラーで新しいカスタムドメインを作成するには、以下の例を参照してください。

成功すると、新しいカスタムドメインの詳細 (確認ステータスを含む) が返されます。status の初期値は pending です。

{
    "custom_domain_id": "cd_abc123def456",
    "domain": "your.example-custom-domain.com",
    "primary": false,
    "status": "pending",
    "type": "auth0_managed_certs",
    "verification": {
        "methods": [
            {
                "name": "CNAME",
                "record": "yourtenant.auth0.com",
                "domain": "your.example-custom-domain.com"
            }
        ]
    },
    "tls_policy": "recommended",
    "domain_metadata": {
        "environment": "development"
    }
}

​

MCD の機能

MCD には、Auth0 の実装をより効率的に管理し、ユーザーエクスペリエンスを向上させるための主要な機能が多数用意されています。必要なカスタムドメインの所有権を保持し、ドメイン名レジストラに登録する責任はお客様にあります。

Auth0 Management API は、これらのカスタムドメインに対する 作成、取得、更新、削除、検証 の各操作を包括的にサポートしており、そのライフサイクル全体をプログラムで完全に制御できます。

MCD は、Node.js、Go、Python、Java、および .NET の各 Auth0 Management SDK でサポートされています。Authentication SDK は、アプリケーションで設定すると、カスタムドメインで自動的に動作します。

​

デフォルトドメイン

複数のカスタムドメインが設定されている場合は、そのうちの 1 つをデフォルトドメインとして指定できます。デフォルトドメインは、Auth0 Management API エンドポイントでドメイン情報が必要な場合に、auth0-custom-domain ヘッダーでカスタムドメインが明示的に指定されていなければ使用されます。この情報は、メール通知 (パスワードのリセットやメールアドレスの確認など) をドメインに応じた内容にカスタマイズするために使用されます。

デフォルトドメインを設定するには、次の手順に従います。

1. Auth0 Dashboard > Branding > Custom Domains に移動します
2. 一覧から、デフォルトに設定するドメインを見つけます
3. そのドメインの Set as Default ボタンをクリックします

カスタムドメインの設定を更新することで、Management API を使用してデフォルトドメインを設定することもできます。設定すると、auth0-custom-domain ヘッダーで特定のドメインが指定されない限り、メール通知のカスタマイズには自動的にデフォルトドメインが使用されます。

デフォルトドメインを設定すると、通知をトリガーする Management API エンドポイントでは auth0-custom-domain ヘッダーの指定が不要になります。これらのエンドポイントの呼び出し時にカスタムドメインを指定しない場合、Auth0 はメール通知のカスタマイズにデフォルトドメインを自動的に使用します。

​

ドメインの検証

ドメイン名の所有権を検証する方法は、選択した管理方式によって異なります。

ドメインタイプ	検証方法	詳細
Auth0-Managed	CNAME DNS レコード	このレコードを設定してドメインの所有権を確認し、ドメインを有効にします。
Self-Managed	TXT DNS レコード	対象の TXT レコードの詳細は、Create API のレスポンスに含まれます。

カスタムドメインが Auth0 で検証されると、すぐにそれを使用するよう Auth0 の機能を設定できます。詳細については、カスタムドメインを使用するように機能を設定するを参照してください。

​

管理性を高めるためのメタデータ

整理しやすくし、将来のカスタマイズに備えるために、カスタムドメインごとに最大 10 個のメタデータフィールドを設定できます。今後のリリースでは、これらのメタデータフィールドを使用して、メールテンプレート、Universal Login、および認証ロジックを高度にカスタマイズできるようになります。

​

メールテンプレートをカスタマイズする

カスタムドメイン情報を活用してメールテンプレートをパーソナライズし、ブランドに合わせた設定を行うことで、一貫したユーザーエクスペリエンスを実現できます。これを容易にするため、MCD では Liquid 構文で使用できる custom_domain.domain 変数を提供しています。

たとえば、メールテンプレートの From Address を support@{{ custom_domain.domain }} に設定すると、[e-mail] として表示されます。この変数は、From Address、Subject、Message の各フィールドで Liquid 構文を通じて使用できます。詳しくは、メールテンプレートをカスタマイズする を参照してください。

​

Management API を使用してメールの処理をカスタマイズする

複数のカスタムドメイン を設定し、Use Custom Domains in Emails を有効にしている場合は、Auth0 Management API の使用時に auth0-custom-domain HTTP ヘッダーを利用できます。このヘッダーは、メールテンプレート内の domain object の値として渡されます。

次の Management API エンドポイントでは、auth0-custom-domain HTTP ヘッダーを受け付けます。

• メールアドレスの確認メールを送信する
• メール確認チケットを作成する
• 組織への招待を作成する
• ユーザーを作成する
• 多要素認証の登録チケットを作成する
• パスワード変更チケットを作成する
• ユーザーを更新する

例: Node.js 用の Auth0 SDK を使用してパスワード変更チケットを作成する場合。

import { ManagementClient, CustomDomainHeader } from "auth0";

// クライアントレベル: ホワイトリスト登録済みエンドポイントに自動適用
const auth0 = new ManagementClient({
    domain: '{yourDomain}',
    clientId: '{yourClientId}',
    clientSecret: '{yourClientSecret}',
    withCustomDomainHeader: 'my-custom-domain.com',});

(async () => {
    try {
        const ticket = await auth0.tickets.changePassword({
            user_id: 'auth0|abc123',
            result_url: 'https://example.com/success'
        });
        console.log('Password change ticket created:', ticket.data.ticket);
    } catch (err) {
        console.error('Error creating password change ticket:', err);
    }
})();

// または、リクエストごとに個別指定する方法
const reqOptions = {
    ...CustomDomainHeader('my-custom-domain.com'),
};
const ticket = await auth0.tickets.changePassword(
    { user_id: 'auth0|abc123', result_url: 'https://example.com/success' },
    reqOptions
);

レスポンスの例: カスタムドメインは、チケットURLの生成に使用するヘッダーで渡されます。

{
    "ticket": "https://my-custom-domain.com/u/reset-verify?ticket=abc123"
}

レスポンスメッセージ

auth0-custom-domain HTTP ヘッダーを指定すると、次の追加レスポンスが返される場合があります。

HTTP status code	メッセージ
409	テナントに複数の検証済みカスタムドメインがあります。
400	そのカスタムドメインはテナントに存在しません。
400	auth0-custom-domain HTTP ヘッダーの形式が無効です。

MCD を有効にし、Auth0 Dashboard を使用してメールテンプレートを設定すると、Try 機能は標準の Auth0 ドメインではなく、デフォルトのカスタムドメインで実行されます。

​

アプリケーションURLプレースホルダー

コールバックURL、ログアウトURL、Application Login URI (initiate_login_uri) などのアプリケーションURLでは、カスタムドメインのメタデータを動的なプレースホルダーとして使用できます。これにより、実行時に各カスタムドメインがそれぞれ異なるアプリケーションURLに解決されるようにできます。詳しくは、カスタムドメインURLプレースホルダーを参照してください。

​

Actions を使用した複数のカスタムドメイン

Auth0 の Actions を使用すると、カスタムドメインに応じて異なるトランザクションを処理するカスタムロジックを作成できます。

たとえば、ユーザーを関連する組織に誘導する Action を作成したり、特定のアクセス制御ポリシーを適用したりできます。

このため、Post Login Action では event.custom_domain オブジェクトを使用でき、認証フローで使用されているカスタムドメインを取得できます。

​

ユースケース: カスタムドメインに基づき、ユーザーの組織へのアクセスを制限する

組織のメタデータに、ドメインの許可リストと拒否リスト (たとえば allow_domains と deny_domains) を保存します。

次の処理を行う Action を作成します。

1. event.custom_domain?.domain プロパティからユーザーのドメインを取得する
2. そのドメインを両方のリストと比較する
3. 比較結果に応じて、ユーザーのアクセスを許可または拒否する

exports.onExecutePostLogin = async (event, api) => {
    const customDomain = event?.custom_domain?.domain;
    
    console.log(`org ${event?.organization?.name} accessed from domain ${customDomain || event?.request?.hostname}`);

    if (event?.organization?.metadata?.deny_domains && event?.organization?.metadata?.allow_domains) {
        console.warn(`[WARNING] configuration issue. org ${event?.organization?.name} has both deny_domains and allow_domains`);
    }

    // 拒否 (A) または許可 (B) のいずれかを確認（両方は不可）
    // (A) 組織の deny_list を確認
    const isDomainDenied = () =>
        (event?.organization?.metadata?.deny_domains ? event?.organization?.metadata?.deny_domains.split(',').map(d => d.trim()).includes(customDomain) : false);
        
    if (isDomainDenied()) {
        return api.access.deny(`access to org ${event?.organization?.name} not allowed on domain ${customDomain}`);
    }

    // (B) 組織の allow_list を確認
    const isDomainAllowed = () =>
        (event?.organization?.metadata?.allow_domains ? event?.organization?.metadata?.allow_domains.split(',').map(d => d.trim()).includes(customDomain) : false);
        
    if (!isDomainAllowed()) {
        return api.access.deny(`access to org ${event?.organization?.name} not allowed on domain ${customDomain}`);
    }
};

MCD では、event.custom_domain オブジェクトを通じて、Actions からカスタムドメインのメタデータにアクセスできます。この情報をテナントで設定したカスタムドメインのメタデータと組み合わせることで、Actions にドメイン固有のロジックを実装できます。

​

カスタムドメイン属性

MCD は、カスタムドメインの検証および SSL/TLS 証明書の管理に関する次の属性を提供します。これらの属性により、カスタムドメインのプロビジョニング状況や運用状態をより詳細に把握できます。

​

更新された属性

属性	説明
status	status 属性に、新しい列挙値 failed が追加されました。この値は、カスタムドメインの検証プロセスでエラーが発生し、検証に失敗したことを示します。既存のサポート値である pending および ready に加えて、新たにサポートされる値です。

​

新しい属性

以下の属性は、Auth0 管理ドメインでのみサポートされます。

Attribute	Description
verification.status	DNS レコードの検証プロセスのステータス。指定可能な値は verified、pending、failed です。
verification.error_msg	verification.status が失敗を示している場合、この文字列属性には、検証失敗の原因を示す人が理解しやすいエラーメッセージが格納されます。
verification.last_verified_at	このタイムスタンプ属性には、カスタムドメインの最後の検証成功日時が記録されます。このタイムスタンプの形式は ISO 8601 に準拠します。
certificate	このオブジェクトには、カスタムドメインに関連付けられた SSL/TLS 証明書に関する情報が含まれます。
certificate.status	この属性は、SSL/TLS 証明書の現在のプロビジョニングステータスを示します。指定可能な値には、provisioning、provisioned、provisioning_failed、renewing_failed などがあります。
certificate.error_msg	certificate.status が provisioning_failed または renewing_failed の場合、この文字列属性には、失敗の理由を詳しく説明するわかりやすいエラーメッセージが含まれます。
certificate.certificate_authority	この文字列属性は、カスタムドメインの SSL/TLS 証明書を発行した認証局を示します。
certificate.renews_before	Auth0 管理のカスタムドメインでは、この新しいタイムスタンプ属性は、SSL/TLS 証明書を更新する必要がある期限の日時を示します。このタイムスタンプの形式は ISO 8601 に準拠します。

​

制限事項

以下の制限は 複数のカスタムドメイン に適用されます。

• WebAuthn/パスキー:
  • 各カスタムドメインでは、パスキー登録が個別に管理されます。あるカスタムドメインで登録されたパスキーは、その特定の Relying Party ID (RP ID) に紐付けられているため、他のドメインでは使用できません。
  • ユーザーがドメイン A でローミング セキュリティ キーを登録し、ドメイン B 経由でログインしようとした場合でも、認証が単に失敗するだけではありません。代わりに、RP ID が一致しないため、システムは直ちにユーザーに新しい登録画面を表示します。