auth0-custom-domains

Auth0 カスタムドメイン

Auth0 Management API、DNS プロバイダー、検証ポーリング、そしてそれらをまとめる設定を使って、Auth0 カスタムドメインに関する作業をエンドツーエンドで行います。ユーザーの DNS プロバイダー（Cloudflare、Route 53、Azure DNS、その他）を検出し、プロバイダーが対応している場合はレコードの作成を自動化します。

概要

このスキルはステップベースではなく、機能ベースです。ユーザーが行いたい作業を、5 つの異なる機能（セットアップ、トラブルシューティング、管理、削除、ヘルスチェック）に分類し、それぞれ専用のリファレンスファイルに個別のフローを用意しています。メインの SKILL.md は案内板として機能し、すべてのフローに共通する機能の一覧表、重要な概念、前提条件、よくある間違いを記載しています。ユーザーがこのスキルを呼び出したら、一覧表から該当する機能を選び、そのリファレンスファイルを読み込んで、記載されたフローに従ってください。

機能ベースの設計は、ユーザーが実際に Auth0 カスタムドメインの作業に取りかかる際の意図に合致しています。「セットアップする」「動かなくなった」「何かを変更する」「削除する」「セットアップがまだ動作しているか確認する」といった意図です。それぞれの意図は、独自の安全確認と引き継ぎを伴う個別のフローに対応します。

やり取りのスタイル

質問は、通常の会話文として尋ねてください。破壊的または取り消し不能な操作（作成、PATCH、削除）の直前に行う、単一のはい／いいえ確認を除き、構造化された UI ウィジェット（例：AskUserQuestion）は使用しないでください。それ以外の場合は、次のようにします。

• 機能の振り分け：番号付きリストを提示し、ユーザーの返答を待ちます
• 入力の収集：焦点を絞った質問を一度に 1 つだけ尋ね、次の質問をする前に返答を待ちます
• 自由形式の値（ホスト名、ドメイン名など）：そのまま直接尋ねます。入力前にクリックを強制するウィジェットで囲まないでください

機能の振り分けに適したパターンの例：

What do you want to do?

1. Set up a custom domain
2. Troubleshoot verification
3. Manage an existing domain
4. Remove a domain
5. Check domain health (read-only, safe starting point)

単一の入力に適したパターンの例：

What's the hostname you want to set up? (e.g., login.example.com)

エラーコードのトリアージ — まずここを確認

ユーザーのメッセージが主に Management API の HTTP エラーコードに関するもの（例：「403 が出ました」「なぜ 409 が返されるのですか？」、貼り付けられたエラーボディ、ステータスコードを含むログエントリ）の場合は、まずこの表に基づいて回答してください。 一般的な Auth0 の知識をそのまま当てはめないでください。特に Free プランでの 403 のケースでは、誤ったアドバイスにつながります。エラーコードへの回答の後でのみ、ユーザーが続けたい場合は、該当する機能に案内することを提案してください（例：「修正を適用した状態でセットアップを進めますか？」）。

ステータスと状況	正しい診断と修正
Free プランでの POST /custom-domains に対する 403	プランの問題ではありません。 カスタムドメインは Free を含むすべてのプランで利用できます（Auth0 のドキュメントで確認済み：「無料のカスタムドメインを設定するには、認証と不正利用防止のため、Auth0 テナントに有効なクレジットカードを登録する必要があります。クレジットカードに請求されることはありません。」）。Dashboard → Tenant Settings → Billing でカードを追加してください。プランのアップグレードを提案しないでください。
type: self_managed_certs を指定した POST /custom-domains に対する 403	これはプランの問題です。セルフマネージド証明書は Enterprise 専用です。type: auth0_managed_certs（すべてのプランで利用可能）に変更するか、Enterprise にアップグレードしてください。
POST /custom-domains に対する 409	ドメインはこのテナントまたは別のテナントにすでに存在します。auth0 domains list を実行して確認してください。ユーザーが所有する別のテナントに存在する場合は、まずそのテナントで削除してください。新規作成を再試行しないでください。
リクエストボディに type が含まれる PATCH /custom-domains/{id} に対する 400	type は作成時に固定されるため、PATCH で拒否されます。削除（機能 4）してから再作成（機能 1）するよう案内してください。切り替え中に認証が停止することを警告してください。
relying_party_identifier に対する operation_not_supported を伴う 400	テナントで機能フラグによって制限されています。relying_party_identifier を指定せずに再試行し、フラグを有効にするよう Auth0 サポートに依頼してください。
いずれかのカスタムドメインエンドポイントに対する 404	custom_domain_id が誤っているか、テナントが異なります。auth0 tenants list と auth0 domains list で確認してください。
429	レート制限に達しています。間隔を空けて再試行してください。このスキルの検証ポーリング用バックオフパターン（5s、10s、20s、30s、60s）を使うと回避できます。

すべてのケースと解決方法を含むエラーコードの完全なリファレンス：references/api.md#error-codes。

機能

このスキルが呼び出され、ユーザーがエラーコードについて質問していない場合は、どの機能を利用したいか、通常の番号付きリストでユーザーに尋ねてください（上記の「対話スタイル」を参照）。ユーザーが原因を特定できない問題を報告した場合、または必要な機能がわからない場合は、まず ドメインの健全性を確認 に案内してください。これは安全な読み取り専用の最初のステップで、適切な次の対応を案内します。

#	機能	内容
1	カスタムドメインを設定する	最初から最後まで対応します。Auth0 でドメインを作成し、DNS プロバイダーを検出して、CNAME レコードを作成します（Cloudflare／Route 53／Azure では自動化され、その他のプロバイダーでは手順を案内します）。所有権を確認し、ユーザーのアプリで更新する内容を報告します。初回の設定と MCD への追加に対応します。references/capability-setup.md を参照してください。
2	検証のトラブルシューティング	ドメインが pending_verification のままになっている場合や、検証に失敗する場合に対応します。診断手順では、DNS と想定値を比較し、プロキシ／CNAME フラット化／競合するレコード／伝播／プライベートゾーンの問題を確認してから再試行します。references/capability-troubleshoot.md を参照してください。
3	既存のドメインを管理する	設定済みのドメインを的確に編集します。デフォルトの設定または変更（MCD 用）、TLS ポリシーの更新、カスタムクライアント IP ヘッダーの設定、パスキーの証明書利用者識別子の設定、ドメインごとのメタデータの管理（最大 10 個のキーと値のペアを設定でき、Actions から読み取り可能）、ドメインの一覧表示とステータスの表示に対応します。ユーザーの意図に基づいて処理します。証明書の種類は作成時に固定され、PATCH で type の変更は拒否されます。references/capability-manage.md を参照してください。
4	カスタムドメインを削除する	ドメインを安全に削除します。デフォルトの場合は警告し、依存するアプリケーションを提示してから、Auth0 で削除し、DNS の CNAME をクリーンアップします。references/capability-remove.md を参照してください。
5	ドメインの健全性を確認する	読み取り専用です。すべてのカスタムドメインを一覧表示し、DNS レコードが想定値と一致するかを確認し、デフォルトドメインの設定を提示して、対応が必要な項目にフラグを立てます。安全な最初のステップとして利用できます。references/capability-health.md を参照してください。

機能を選択し、そのリファレンスファイルの手順に従ってください。以下の 前提条件 と 主要な概念 の各セクションは、すべての機能に適用されます。

主な概念

概念	説明
CNAME レコード	カスタムドメインを Auth0 のエッジ（例：{tenant}.edge.tenants.auth0.com）に向ける DNS レコードです。証明書を更新するには、DNS に恒久的に残しておく必要があります
Auth0 管理証明書	Auth0 が TLS 証明書を発行し、約 3 か月ごとに自動更新します。デフォルトであり、推奨される方式です。種類は作成時に固定され、PATCH では変更できません
セルフ管理証明書	TLS はリバースプロキシ（Cloudflare、CloudFront、Azure Front Door、または GCP LB）で終端されます。Enterprise のみ利用できます。検証には CNAME ではなく TXT を使用します。種類は作成時に固定され、PATCH では変更できません。変更するには、ドメインを削除して再作成する必要があります
NS 検出	ルートドメインのネームサーバーを照会して DNS プロバイダーを特定し、適切な自動化階層に振り分けます
複数のカスタムドメイン（MCD）	Enterprise の機能です。マルチブランドまたはマルチリージョン向けに、テナントごとに最大 20 個のドメインを設定できます
デフォルトのカスタムドメイン	MCD が設定されている場合に、Management API 呼び出しで auth0-custom-domain ヘッダーが指定されなかったときに使用されるドメインです
依拠当事者識別子（RPID）	ドメインごとの relying_party_identifier で、カスタムドメインのホスト名とパスキーの rpId を切り離します。作成時または PATCH で設定できます。login.example.com で認証を提供しながら、パスキーを example.com に紐付けて、複数のサーフェスで再利用できます
TLS ポリシー	ドメインの tls_policy は、Auth0 管理証明書の最小 TLS バージョンと暗号スイートの設定を制御します。デフォルトは recommended です。作成時または PATCH で設定できます
カスタムクライアント IP ヘッダー	custom_client_ip_header は、トラフィックがリバースプロキシを通過する際に、実際のクライアント IP を格納するリクエストヘッダーを Auth0 に指定します。有効な値：true-client-ip、cf-connecting-ip、x-forwarded-for、x-azure-clientip。作成時または PATCH で設定できます
ドメインメタデータ	カスタムドメインに付加できるカスタムのキーと値のペアは最大 10 個です（キーと値はそれぞれ 255 文字以下）。Actions から event.custom_domain.domain_metadata を読み取り、ドメインごとのロジック（リージョン、ブランド、環境のタグ付け）に使用できます

スキーマ全体とトークン／iss の動作については、references/advanced.md を参照してください。

前提条件

これらは、テナントに書き込みを行うすべての機能に適用されます。ドメインの健全性を確認する機能は読み取り専用で、これらの前提条件を確認するために最初に実行できます。

Auth0 Management API へのアクセス

すべての機能で Management API を使用します。次のいずれかを使用します。

• 対象テナントで認証済みの Auth0 CLI（auth0 ...）（auth0 tenants use <name>）、または
• references/api.md に記載されているスコープを持つ Machine-to-Machine アプリケーション

機能の呼び出し時ではなく、機能内で最初の Auth0 CLI コマンドを実行する直前に、アクティブなテナントを確認してください。 ユーザーが機能を選ぶ前に、テナントを確認しないでください。機能が CLI 以外のツール（例：DNS 照会、Cloudflare MCP、curl による Management API の直接呼び出し）のみを使用する場合は、テナントの確認を完全に省略してください。

選択した機能で Auth0 CLI を使用する場合は、最初の CLI コマンドの前に次を実行してください。

auth0 tenants list

アクティブとして示された行を確認するか、JSON 出力の active フィールドを確認してください。アクティブなテナントをユーザーに伝え、それが意図した対象かどうか確認を求めてください。異なる場合は中止し、次を実行するようユーザーに依頼してください。

auth0 tenants use <tenant-name>

その後、続行する前にあらためて確認してください。変更を伴う呼び出し（作成、PATCH、削除）では、明示的な確認を必須とします。読み取り専用の CLI フローでは、テナント名を提示し、出力レポートにも記載すれば十分です。ただし、会話の文脈だけを根拠にアクティブなテナントが正しいと決めつけてはいけません。

DNS プロバイダーへのアクセス（設定、トラブルシューティング、削除）

カスタムドメインの設定では CNAME を書き込み、カスタムドメインの削除では CNAME を削除します。検証のトラブルシューティングでは、DNS の編集が必要な修正方法を提案することがあります。スキルが必要とするものは、プロバイダーのティアによって異なります。

• Tier 1 Cloudflare：Cloudflare MCP に接続します。未接続の場合、スキルはユーザーに claude mcp add --transport http cloudflare https://mcp.cloudflare.com/mcp の実行と、ブラウザーでの認可を促します。
• Tier 2 AWS Route 53：AWS 認証情報を設定します（環境変数、共有設定、または SSO セッション）。aws sts get-caller-identity で確認します。
• Tier 3 Azure DNS：Azure CLI にサインインします。az account show で確認します。
• Tier 4 その他：プログラムからのアクセス手段はありません。ユーザーがプロバイダーのダッシュボードでレコードを手動で追加します。

自動化に必要なプラン：自動化に対応する 3 つのティアのいずれも、DNS プロバイダー側の有料プランは必要ありません。MCP を介した Cloudflare DNS レコードの CRUD は Free プランで利用できます（2024 年 9 月以降に作成された Free ゾーンでは、1 ゾーンあたりの DNS レコード数が 200 件に制限されます。Auth0 の CNAME も 1 件として数えられます）。Route 53 は従量課金制です（ホストゾーン 1 つにつき月額約 $0.50 ＋クエリ料金。AWS 無料利用枠の対象外です）。Azure DNS はサブスクリプションベースで、ティアによる制限はありません。サインイン済みの ID には DNS Zone Contributor ロールが必要です。各ティアの詳細は、プロバイダー別のサブファイル references/providers/（ルーター：references/providers.md）をご覧ください。

登録済みのクレジットカード（Free テナント）

カスタムドメインは Free を含むすべてのプランティアで利用できます。Free テナントでは本人確認のためにクレジットカードの登録が必要です（カードに請求は発生しません）。登録されていない場合、POST /custom-domains は 403 を返します。Dashboard → Tenant Settings → Billing で解決できます（Teams 管理のテナントでは Teams セクションを使用します）。

403 が発生した場合は、プランのアップグレードを提案するのではなく、これが原因である可能性が高いことを伝えてください。

よくある間違い

クイックインデックスです。各項目から、該当する機能ファイルの正式な説明に移動できます。

間違い	参照先
作成時の 403 はプランのアップグレードが必要だと思い込む	api.md エラーコード
検証後に CNAME を削除する（証明書の更新に支障が出ます）	capability-5 結果の解釈
relying_party_identifier を設定せずにパスキーでサブドメインを使用する	capability-3 RPID セクション
PATCH で証明書の種類を変更しようとする	capability-3 対象範囲の注記
CNAME の DNS プロキシを有効にする（Cloudflare のオレンジ色の雲）	capability-2 プロキシの確認
ゾーンで CNAME フラット化を有効にする	capability-2 フラット化の確認
検証の「行き詰まり」を解消するために削除して作り直す	capability-2 やってはいけないこと
検証後に SDK の domain / issuerBaseURL を更新しない	capability-1 報告後の次の手順
MCD でテナントドメイン経由で Management API を呼び出す	advanced.md auth0-custom-domain ヘッダー

関連スキル

• auth0-branding：Universal Login の表示をカスタマイズします（ページテンプレートには検証済みのカスタムドメインが必要です）
• auth0-organizations：B2B マルチテナント向けに組織別のブランディングを設定します

参考資料

• references/capability-setup.md：カスタムドメインを設定する
• references/capability-troubleshoot.md：検証のトラブルシューティングを行う
• references/capability-manage.md：既存のドメインを管理する
• references/capability-remove.md：カスタムドメインを削除する
• references/capability-health.md：ドメインの状態を確認する
• references/providers.md：DNS プロバイダーのルーター — NS からプロバイダーへのマップ。references/providers/ 配下にあるプロバイダー別サブファイル（cloudflare.md、route53.md、azure-dns.md、manual.md）へのリンクを含みます。検出されたプロバイダーに一致するサブファイルのみを開いてください。
• references/examples.md：cURL のサンプル、エンドツーエンドの CI/CD 自動化、および複数環境のパターン
• references/api.md：エンドポイントのリファレンス、CLI コマンド、エラーコード、スコープ
• references/advanced.md：MCD、デフォルトドメイン、auth0-custom-domain ヘッダー、セルフ管理証明書、トークンの iss の動作、検証のトラブルシューティングの詳細

外部ドキュメント

• カスタムドメインの概要
• Auth0 管理証明書
• セルフ管理証明書
• 複数のカスタムドメイン
• デフォルトのカスタムドメイン
• カスタムドメインを使用する機能の設定
• カスタムドメインのトラブルシューティング
• Cloudflare MCP サーバー