複数のカスタムドメイン

マルチブランドおよびマルチリージョンでの展開に向けて、1 つの Auth0 テナント内で複数のカスタムドメインを設定・管理する方法を学びます。

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

​

前提条件

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

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

​

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

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

Auth0 Dashboard

Auth0 Dashboard でカスタムドメインを作成するには:

1. Auth0 Dashboard > Branding > Custom Domains に移動します。

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

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

   • Domain: 自分が所有する完全修飾ドメイン名。例: 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 Access Tokens を参照してください。

1. Auth0 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. Client ID、Client Secret、Domain を確認するには、Settings タブに移動します。

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

​

カスタムドメインの作成

新しいカスタムドメインを作成するには、POST リクエストを /api/v2/custom-domains エンドポイントに送信します。上記で取得した資格情報を使用して 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 は、次の Auth0 Management SDK でサポートされています: Node.js、Go、Python、Java、および .NET。認証 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 機能を設定できます。詳しくは、Configure Features to Use Custom Domains を参照してください。

​

管理を強化するためのメタデータ

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

​

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

カスタムドメインの情報を活用してメールテンプレートをパーソナライズし、ブランドイメージを反映させることで、一貫したユーザー体験を実現できます。そのために、MCD では Liquid Syntax で使用できる custom_domain.domain 変数を提供しています。

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

​

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

Multiple Custom Domains を設定し、メールでカスタムドメインを使用 を有効にしている場合は、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 ステータスコード	メッセージ
409	テナントに、検証済みのカスタムドメインが複数存在します。
400	そのテナントにはカスタムドメインが存在しません。
400	auth0-custom-domain HTTP ヘッダーの形式が無効です。

MCD を有効にし、Auth0 Dashboard を使用して Email Templates を設定している場合、Try 機能は標準の Auth0 ドメインではなく、既定のカスタムドメインを使用して実行されます。

​

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

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

​

複数のカスタムドメインでのActionsの利用

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

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

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

​

ユースケース: カスタムドメイン に基づいてユーザーの Organization へのアクセスを制限する

ドメインの許可リストと拒否リスト (例: allow_domains と deny_domains) を Organization のメタデータに保存します。

以下を行う 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) organizationの 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) organizationの 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 管理ドメインでのみサポートされています。

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