デフォルトのカスタムドメイン

一貫したユーザー体験を提供するために、テナントでデフォルトのカスタムドメインを設定する方法を紹介します。

複数のカスタムドメイン が Auth0 テナントに設定されている場合、そのうち 1 つをデフォルトのカスタムドメインとして指定できます。デフォルトのカスタムドメインを設定すると、設定が簡単になり、カスタムドメインが明示的に指定されていない場合でも、一貫したユーザー体験を実現できます。

​

デフォルトのカスタムドメインとは何ですか？

デフォルトのカスタムドメインとは、Auth0 が次の用途で自動的に使用するカスタムドメインです。

• メールおよび電話での連絡: 特定のカスタムドメインが指定されていない場合に、パスワードリセットメール、メールアドレス確認用リンク、その他 Auth0 が生成する通知を送信するために使用されます。これには、認証中に送信される通知も含まれます。
• Management API 呼び出し: auth0-custom-domain ヘッダーなしで通知をトリガーする API リクエストを処理する場合

正規のテナントドメイン (YOUR_TENANT.auth0.com または YOUR_TENANT.REGION.auth0.com) をデフォルトのカスタムドメインとして設定できます。テナントには、常に 1 つのデフォルトのカスタムドメインが設定されます。

​

デフォルトドメインを設定するメリット

デフォルトのカスタムドメインを設定すると、次のようなメリットがあります。

• 設定の簡素化: Management API の呼び出しや各種設定のたびにカスタムドメインを指定する手間を減らせます
• 一貫したブランディング: 特定のドメインが指定されていない場合でも、ユーザーには常に自社のブランドを表示できます
• auth0-custom-domain ヘッダーの指定が任意: Management API リクエストでカスタムドメインヘッダーの指定が不要になります
• フォールバック動作: マルチブランドまたはマルチテナントの実装で、妥当なデフォルト値を提供します
• 移行の容易さ: 単一のカスタムドメインから複数のカスタムドメインへの移行を簡単にします

​

デフォルトドメインを設定する

Auth0 Dashboard または Management API で、デフォルトのカスタムドメインを設定できます。

​

Auth0 Dashboard を使用する

Auth0 Dashboard でデフォルトのカスタムドメインを設定するには、次の手順に従います。

1. Auth0 Dashboard > Branding > Custom Domains に移動します
2. 一覧から、デフォルトに設定したい検証済みのカスタムドメインを探します
3. 対象のドメインの Set as Default ボタンをクリックします
4. 表示されるダイアログで確定します

設定すると、そのドメインにはカスタムドメインの一覧で「Default」バッジが表示されます。

デフォルトに設定できるのは、検証済みのカスタムドメインのみです。カスタムドメインをデフォルトとして指定する前に、検証が完了し、有効になっていることを確認してください。

​

Management API を使用する

Management API を使用してデフォルトのカスタムドメインを設定するには、PATCH /api/v2/custom-domains/default エンドポイントを使用します。

​

デフォルトドメイン指定を解除する

カスタムドメインからデフォルト指定を解除するには、次のいずれかを行います。

1. 別のカスタムドメインをデフォルトとして設定する (一度にデフォルトにできるドメインは 1 つのみです) 、または
2. Management API を使用して、現在のデフォルトドメインに is_default: false を設定する

デフォルトに設定されたカスタムドメインがない場合、Auth0 はテナントの正規ドメインを使用します。

​

デフォルトドメインの使われ方

​

メール通知

Auth0 がメール通知 (パスワードリセット、メールアドレスの確認、ウェルカムメール) を送信する際、これらの通知に含まれるリンクやカスタマイズにはデフォルトドメインが使用されます。メールテンプレートをカスタマイズすると、“From” アドレス、件名、メール本文でカスタムドメインの情報を使用できます。

​

通知を発生させる Management API エンドポイント

デフォルトのカスタムドメインは、メールまたは電話による通知を発生させる Management API エンドポイントで特に使用されます。デフォルトドメインが設定されている場合、これらのエンドポイントでは auth0-custom-domain ヘッダーは省略可能です。

メール通知を発生させるエンドポイント:

• POST /api/v2/tickets/password-change - パスワードリセットメールを送信
• POST /api/v2/tickets/email-verification - メールアドレス確認を送信
• POST /api/v2/jobs/verification-email - ユーザーに確認メールを送信
• POST /api/v2/users - 設定によってはウェルカムメールを送信
• PATCH /api/v2/users/{id} - メールアドレス更新時に確認メールを送信する場合があります

電話通知を発生させるエンドポイント:

• POST /api/v2/users/{id}/phone/verification - SMS で確認コードを送信

例:

これらの通知エンドポイントで auth0-custom-domain ヘッダーを指定しない場合、Auth0 はメールまたは SMS のリンクやカスタマイズにデフォルトのカスタムドメインを自動的に使用します。auth0-custom-domain ヘッダーを含めることで、リクエストごとにこれを上書きできます。

​

Actionsでデフォルトドメインを使用する

カスタムドメインに応じたロジックを実装するには、Actions を使用します。

exports.onExecutePostLogin = async (event, api) => {
  const domain = event.custom_domain?.domain;

  // ログインドメインをユーザーのメタデータに保存する
  if (domain) {
    api.user.setAppMetadata('login_domain', domain);
  }
};

Actionsでのカスタムドメイン情報の使用方法について詳しくは、複数のカスタムドメインとのActions連携を参照してください。

​

ベストプラクティス

デフォルトのカスタムドメインを設定する際は、次のベストプラクティスを参考にしてください。

• 安定したドメインを選ぶ: デフォルトには、頻繁に変更する必要のない安定したドメインを選択します
• 設定前に確認する: デフォルトに設定する前に、そのドメインが完全に検証され、正常に動作していることを確認します
• 決定内容を文書化する: 今後参照できるように、特定のドメインをデフォルトとして選んだ理由を記録します
• メール関連のフローをテストする: デフォルトドメインを設定した後は、パスワードリセットフローとメールアドレス確認フローをテストします
• トークンの発行元を確認する: デフォルトを設定した後、トークンに想定どおりの iss claim が含まれていることを確認します
• マルチブランド構成を考慮する: 複数のブランドを提供している場合は、デフォルトとして汎用的なドメインまたは管理用ドメインを選択します
• 連携設定を更新する: 適切な連携設定が行えるよう、デフォルトドメインについてチームに周知します

​

さらに詳しく

• 複数のカスタムドメイン
• カスタムドメインを使用する機能を設定する
• カスタムドメインの概要
• メールでカスタムドメインを使用する
• カスタムドメインとActionsの連携