Back to Details

auth0-custom-domains

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Auth0 Custom Domains

Auth0自定义域名

Drive Auth0 custom-domain work end-to-end: Auth0 Management API, DNS provider, verification polling, and the configuration that stitches everything together. Detects the user's DNS provider (Cloudflare, Route 53, Azure DNS, or other) and automates record creation when the provider supports it.
端到端处理Auth0自定义域名相关工作：Auth0 Management API、DNS提供商、验证轮询，以及将所有组件整合的配置。可检测用户的DNS提供商（Cloudflare、Route 53、Azure DNS或其他），并在提供商支持时自动创建记录。

Overview

概述

This skill is capability-based, not step-based. It groups the work a user might want to do into five distinct capabilities (setup, troubleshoot, manage, remove, health check), each with its own flow in a dedicated reference file. The main SKILL.md acts as a lobby: it holds the capabilities table, key concepts, prerequisites, and common mistakes that apply across all flows. When a user invokes the skill, pick the matching capability from the table, load its reference file, and follow that flow.
The capability design matches how users actually come to Auth0 custom domain work: "set one up," "mine is broken," "change something," "remove one," or "is my setup still working?" Each intent maps to a distinct flow with its own safety checks and hand-offs.
本技能基于能力而非步骤设计。它将用户可能需要执行的操作分为五个不同的能力模块（设置、故障排查、管理、移除、健康检查），每个模块在专用参考文件中都有对应的流程。主文件SKILL.md作为入口：包含能力列表、核心概念、前置条件以及适用于所有流程的常见错误。当用户调用该技能时，从列表中匹配对应的能力模块，加载其参考文件并遵循相应流程。
这种能力设计符合用户处理Auth0自定义域名的实际场景：“设置一个域名”、“我的域名出问题了”、“修改配置”、“移除域名”或“我的设置是否正常运行？”。每种意图都对应一个独立的流程，包含各自的安全检查与切换逻辑。

Interaction style

交互风格

Ask questions as plain conversational text. Never use structured UI widgets (e.g., AskUserQuestion) except for a single yes/no confirmation immediately before a destructive or irreversible action (create, PATCH, delete). For everything else:
  • Capability routing: present a numbered list and wait for the user to reply
  • Input gathering: ask one focused question at a time; wait for a response before asking the next
  • Free-form values (hostnames, domain names, etc.): just ask directly — don't wrap them in a widget that forces a click before typing
Example of the right pattern for capability routing:
text
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)
Example of the right pattern for a single input:
text
What's the hostname you want to set up? (e.g., login.example.com)
使用简洁的对话文本提问。除了在执行破坏性或不可逆操作（创建、PATCH、删除）前需要单次确认是/否外，绝不使用结构化UI组件（如AskUserQuestion）。其他场景遵循以下规则：
  • 能力路由：展示编号列表，等待用户回复
  • 信息收集：一次提出一个聚焦的问题；收到回复后再提出下一个问题
  • 自由格式值（主机名、域名等）：直接提问——不要使用需要先点击才能输入的组件
示例正确的能力路由模式：
text
您需要执行什么操作？

1. 设置自定义域名
2. 排查验证问题
3. 管理现有域名
4. 移除域名
5. 检查域名健康（只读，安全起始选项）
示例正确的单信息收集模式：
text
您想要设置的主机名是什么？（例如：login.example.com）

Error-code triage — CHECK THIS FIRST

错误代码分类——请先查看此处

If the user's message is primarily about an HTTP error code from the Management API (e.g., "I got a 403", "why is this returning 409?", a pasted error body, a log entry with a status code), answer from this table first. Do not default to general Auth0 knowledge — it leads to wrong advice on the Free-tier 403 case in particular. Only after the error-code answer, offer to route into the matching capability if the user wants to continue (e.g., "want me to walk through Set up with that fix in place?").
Status and contextCorrect diagnosis and fix
403 on 
POST /custom-domains
(Free tier)		Not a plan-tier problem. Custom domains are available on all plans including Free (confirmed in Auth0 docs: "To set up a free custom domain, Auth0 tenants must have a valid credit card on file for verification purposes and fraud prevention. The credit card will not be charged."). Fix at Dashboard → Tenant Settings → Billing by adding a card. Do NOT suggest a plan upgrade.
403 on 
POST /custom-domains
with 
type: self_managed_certs
This is a plan issue. Self-managed certs are Enterprise-only. Either downgrade to 
type: auth0_managed_certs
(works on all plans) or upgrade to Enterprise.
409 on 
POST /custom-domains
Domain already exists on this tenant or another. Run 
auth0 domains list
to check; if on another tenant the user owns, delete it there first. Do not retry a fresh create.
400 on 
PATCH /custom-domains/{id}
with 
type
in body
type
is fixed at create time and rejected by PATCH. Route to delete (capability 4) + recreate (capability 1). Warn about auth downtime during the cutover.
400 with 
operation_not_supported
on 
relying_party_identifier
Feature-flag gate on the tenant. Retry without 
relying_party_identifier
and ask Auth0 support to enable the flag.
404 on any custom-domain endpointWrong 
custom_domain_id
, or wrong tenant. Verify with 
auth0 tenants list
+ 
auth0 domains list
.
429Rate limited. Back off; the skill's verify-poll backoff pattern (5s, 10s, 20s, 30s, 60s) avoids this.
Full error-code reference with all cases and resolutions: references/api.md#error-codes.
如果用户的问题主要涉及Management API返回的HTTP错误代码（例如“我收到了403错误”、“为什么返回409？”、粘贴的错误体、包含状态码的日志条目），请首先参考此表作答。不要默认使用通用的Auth0知识——这尤其会导致针对免费层403错误的错误建议。在解答错误代码问题后，如果用户希望继续，可提供匹配的能力模块路由（例如“需要我结合修复步骤引导您完成设置流程吗？”）。
状态与上下文正确诊断与修复方案
403 错误（
POST /custom-domains
，免费层）		并非套餐层级问题。自定义域名在所有套餐（包括免费层）均可用（Auth0文档确认：“要设置免费自定义域名，Auth0租户必须提供有效的信用卡进行身份验证和防欺诈，不会产生扣费。”）。请在控制台 → 租户设置 → 账单中添加信用卡。请勿建议升级套餐。
403 错误（
POST /custom-domains
，
type: self_managed_certs
）		这属于套餐问题。自管理证书仅企业版可用。可降级为
type: auth0_managed_certs
（所有套餐均支持）或升级至企业版。
409 错误（
POST /custom-domains
）		域名已存在于当前租户或其他租户中。运行
auth0 domains list
检查；如果存在于用户拥有的其他租户中，请先在该租户删除域名。不要重试创建操作。
400 错误（
PATCH /custom-domains/{id}
，请求体包含
type
）
type
在创建时固定，PATCH请求会拒绝修改。请引导至移除（能力模块4）+ 重新创建（能力模块1）流程。提醒用户切换期间会出现认证中断。
400 错误，
relying_party_identifier
字段返回
operation_not_supported
租户未启用该功能的特性开关。请移除
relying_party_identifier
后重试，并联系Auth0支持启用该开关。
404 错误（任何自定义域名端点）
custom_domain_id
错误，或租户错误。通过
auth0 tenants list
+ 
auth0 domains list
验证。
429 错误请求频率受限。请重试；技能的验证轮询退避模式（5秒、10秒、20秒、30秒、60秒）可避免此问题。
包含所有案例与解决方案的完整错误代码参考：references/api.md#error-codes。

Capabilities

能力模块

When this skill is invoked and the user is NOT asking about an error code, ask the user which capability they want using a plain numbered list (see Interaction style above). Route to Check domain health first when the user reports a problem without a specific known cause, or when they're unsure which capability they need; it's the safe, read-only starter that will point them to the right follow-up.
#CapabilityWhat it does
1Set up a custom domainEnd-to-end: create the domain in Auth0, detect the DNS provider, write the CNAME record (automated on Cloudflare / Route 53 / Azure; guided on other providers), verify ownership, and report what to update in the user's apps. Handles first-time setup and adding to MCD. See references/capability-setup.md
2Troubleshoot verificationDomain stuck in 
pending_verification
or verification failing. Diagnostic ladder: compare DNS to expected, check for proxies / CNAME flattening / conflicting records / propagation / private-zone issues, then retry. See references/capability-troubleshoot.md
3Manage existing domainsSurgical edits on already-configured domains: set or change the default (for MCD), update TLS policy, configure the custom client IP header, set the relying party identifier for passkeys, manage per-domain metadata (up to 10 key-value pairs readable from Actions), list domains and show status. Intent-driven. Certificate type is fixed at create time; PATCH rejects 
type
changes. See references/capability-manage.md
4Remove a custom domainDelete a domain safely: warn if it's the default, surface dependent applications, delete in Auth0, clean up the CNAME in DNS. See references/capability-remove.md
5Check domain healthRead-only: list all custom domains, check DNS records match expected values, surface default-domain config, flag anything needing attention. Safe starter capability. See references/capability-health.md
Pick a capability, then follow the flow in its reference file. The Prerequisites and Key Concepts sections below apply across all capabilities.
当调用本技能且用户未询问错误代码时，使用编号列表询问用户需要的能力模块（参见上述交互风格）。当用户报告问题但未明确具体原因，或不确定需要哪个能力模块时，优先引导至检查域名健康模块；这是一个安全的只读起始模块，可指向后续正确的操作流程。
序号能力模块功能说明
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
选择一个能力模块后，遵循其参考文件中的流程。以下前置条件和核心概念适用于所有能力模块。

Key Concepts

核心概念

ConceptDescription
CNAME RecordDNS record pointing your custom domain to Auth0's edge (e.g., 
{tenant}.edge.tenants.auth0.com
). Must stay in DNS permanently for certificate renewal
Auth0-Managed CertificateAuth0 provisions and auto-renews TLS certs every ~3 months. Default and recommended. Type is fixed at create time and cannot be changed via PATCH
Self-Managed CertificateTLS terminates at a reverse proxy (Cloudflare, CloudFront, Azure Front Door, or GCP LB). Enterprise only; verification uses TXT instead of CNAME. Type is fixed at create time and cannot be changed via PATCH; to change, delete and recreate the domain
NS DetectionLooking up the root domain's nameservers to identify the DNS provider and route to the correct automation tier
Multiple Custom Domains (MCD)Enterprise feature; up to 20 domains per tenant for multi-brand or multi-region
Default Custom DomainWhen MCD is configured, the domain used when a Management API call doesn't send the 
auth0-custom-domain
header
Relying Party Identifier (RPID)Per-domain 
relying_party_identifier
that decouples the custom domain hostname from the passkey 
rpId
. Set at create or via PATCH. Lets you serve auth at 
login.example.com
while passkeys bind to 
example.com
for cross-surface reuse
TLS Policy
tls_policy
on the domain controls minimum TLS version / cipher posture for Auth0-managed certs. Default 
recommended
. Set at create or via PATCH
Custom Client IP Header
custom_client_ip_header
tells Auth0 which request header carries the real client IP when traffic passes through a reverse proxy. Valid values: 
true-client-ip
, 
cf-connecting-ip
, 
x-forwarded-for
, 
x-azure-clientip
. Set at create or via PATCH
Domain MetadataUp to 10 custom key-value pairs attached to a custom domain (keys and values ≤ 255 chars). Read from Actions via 
event.custom_domain.domain_metadata
for per-domain logic (region, brand, env tagging)
Full schema and token / 
iss
behavior live in references/advanced.md.
概念描述
CNAME记录将自定义域名指向Auth0边缘节点的DNS记录（例如
{tenant}.edge.tenants.auth0.com
）。为了证书续期，该记录必须永久保留在DNS中
Auth0托管证书Auth0负责提供并自动续期TLS证书，周期约为3个月。默认且推荐使用。证书类型在创建时固定，无法通过PATCH修改
自管理证书TLS在反向代理（Cloudflare、CloudFront、Azure Front Door或GCP LB）处终止。仅企业版可用；验证使用TXT记录而非CNAME。证书类型在创建时固定，无法通过PATCH修改；如需更改，需删除并重新创建域名
NS检测查询根域名的名称服务器以识别DNS提供商，并路由至对应的自动化层级
多自定义域名（MCD）企业版功能；每个租户最多支持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
告知Auth0当流量通过反向代理时，哪个请求头携带真实客户端IP。有效值包括：
true-client-ip
、
cf-connecting-ip
、
x-forwarded-for
、
x-azure-clientip
。可在创建时设置或通过PATCH修改
域名元数据附加到自定义域名的最多10个自定义键值对（键和值≤255字符）。可通过Actions中的
event.custom_domain.domain_metadata
读取，用于实现按域名的逻辑（区域、品牌、环境标记）
完整的Schema和令牌/
iss
行为请参见references/advanced.md。

Prerequisites

前置条件

These apply to any capability that writes to the tenant. Check domain health is read-only and can be run first to verify these.
这些适用于所有需要写入租户的能力模块。检查域名健康是只读模块，可先运行以验证这些条件。

Auth0 Management API access

Auth0 Management API访问权限

All capabilities use the Management API. Either:
  • The Auth0 CLI (
    auth0 ...
    ) authenticated to the target tenant (
    auth0 tenants use <name>
    ), or
  • A Machine-to-Machine application with the scopes in references/api.md.
Check the active tenant immediately before the first Auth0 CLI command in a capability, not at skill invocation. Do not check the tenant before the user has chosen a capability. If a capability uses only non-CLI tools (e.g., DNS lookups, Cloudflare MCP, direct Management API calls via curl), skip the tenant check entirely.
When the chosen capability does use the Auth0 CLI, run this before the first CLI command:
bash
auth0 tenants list
Look for the row marked as active (or check the 
active
field in the JSON output). Show the active tenant to the user and ask them to confirm it is the intended target. If it's wrong, stop and have the user run:
bash
auth0 tenants use <tenant-name>
Then re-confirm before proceeding. For mutating calls (create, PATCH, delete), require explicit confirmation. For read-only CLI flows, surfacing the tenant name (and naming it in the output report) is enough — still never assume the active tenant is correct based on conversational context alone.
所有能力模块均使用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命令前运行以下命令：
bash
auth0 tenants list
查找标记为活跃的行（或查看JSON输出中的
active
字段）。向用户展示当前活跃租户并确认是否为目标租户。如果不正确，请停止操作并让用户运行：
bash
auth0 tenants use <tenant-name>
然后再次确认后继续。对于变更类操作（创建、PATCH、删除），需要明确的确认。对于只读CLI流程，显示租户名称（并在输出报告中注明）即可——仍绝不要仅根据对话上下文假设当前活跃租户正确。

DNS provider access (for Set up, Troubleshoot, and Remove)

DNS提供商访问权限（适用于设置、故障排查和移除模块）

Set up a custom domain writes a CNAME. Remove a custom domain deletes one. Troubleshoot verification may suggest a fix that requires a DNS edit. What the skill needs depends on the provider tier:
  • Tier 1 Cloudflare: Cloudflare MCP connected. If not, skill prompts the user to run 
    claude mcp add --transport http cloudflare https://mcp.cloudflare.com/mcp
    and authorize in the browser.
  • Tier 2 AWS Route 53: AWS credentials configured (env vars, shared config, or SSO session). Verified with 
    aws sts get-caller-identity
    .
  • Tier 3 Azure DNS: Azure CLI signed in. Verified with 
    az account show
    .
  • Tier 4 other: no programmatic access; user manually adds the record in their provider's dashboard.
Plan requirements for automation: None of the three automated tiers require a paid plan on the DNS provider side. Cloudflare DNS record CRUD via the MCP works on the Free plan (Free zones created after Sept 2024 cap at 200 DNS records per zone; Auth0's CNAME counts as one). Route 53 is pay-per-use (~$0.50/hosted zone/month + query costs, not in AWS free tier). Azure DNS is subscription-based with no tier gating; the signed-in identity needs the DNS Zone Contributor role. Full detail per tier in the per-provider sub-files under references/providers/ (router: references/providers.md).
设置自定义域名需要写入CNAME记录。移除自定义域名需要删除CNAME记录。故障排查验证可能需要建议修改DNS记录。技能所需的访问权限取决于提供商层级：
  • 层级1 Cloudflare：已连接Cloudflare MCP。如果未连接，技能会提示用户运行
    claude mcp add --transport http cloudflare https://mcp.cloudflare.com/mcp
    并在浏览器中授权。
  • 层级2 AWS Route 53：已配置AWS凭证（环境变量、共享配置或SSO会话）。可通过
    aws sts get-caller-identity
    验证。
  • 层级3 Azure DNS：已登录Azure CLI。可通过
    az account show
    验证。
  • 层级4 其他提供商：无程序化访问权限；用户需在提供商的控制台中手动添加记录。
自动化的套餐要求：三个自动化层级均无需DNS提供商的付费套餐。通过MCP进行Cloudflare DNS记录的增删改查在免费套餐中即可使用（2024年9月后创建的免费区域限制每个区域最多200条DNS记录；Auth0的CNAME记录算一条）。Route 53按使用付费（约每个托管区域每月0.50美元+查询费用，不在AWS免费套餐范围内）。Azure DNS基于订阅，无层级限制；登录身份需要DNS区域参与者（DNS Zone Contributor）角色。各层级的详细信息请参见references/providers/下的各提供商子文件（路由文件：references/providers.md）。

Credit card on file (Free-tier tenants)

已绑定信用卡（免费层租户）

Custom domains are available on all plan tiers including Free. Free tenants need a credit card on file for identity verification (card is not charged). Without one, 
POST /custom-domains
returns 403. Fix at Dashboard → Tenant Settings → Billing (or the Teams section for Teams-managed tenants).
Surface this as the likely cause on any 403 rather than suggesting a plan upgrade.
自定义域名在所有套餐层级（包括免费层）均可用。免费层租户需要绑定信用卡以进行身份验证（不会扣费）。如果未绑定，
POST /custom-domains
会返回403错误。可在控制台 → 租户设置 → 账单（或团队管理租户的团队部分）中修复。
当出现任何403错误时，应优先提示此可能原因，而非建议升级套餐。

Common Mistakes

常见错误

Quick index; each entry links to the canonical treatment in the relevant capability file.
MistakeSee
Assuming a 403 on create means plan upgradeapi.md error codes
Removing the CNAME after verification (breaks cert renewal)capability-5 interpreting results
Using a subdomain with passkeys without setting 
relying_party_identifier
capability-3 RPID section
Trying to change certificate type via PATCHcapability-3 scope note
Enabling DNS proxy on the CNAME (Cloudflare orange cloud)capability-2 proxy check
Enabling CNAME flattening on the zonecapability-2 flattening check
Deleting and recreating to "unstick" verificationcapability-2 what not to do
Not updating SDK 
domain
/ 
issuerBaseURL
after verification		capability-1 report next steps
Calling Management API via tenant domain under MCDadvanced.md auth0-custom-domain header
快速索引；每个条目链接到对应能力模块文件中的标准处理说明。
错误参考文档
假设创建时的403错误意味着需要升级套餐api.md错误代码
验证完成后移除CNAME记录（会导致证书续期失败）能力模块5结果解读
使用子域名配置密钥但未设置
relying_party_identifier
能力模块3 RPID部分
尝试通过PATCH修改证书类型能力模块3范围说明
在CNAME记录上启用DNS代理（Cloudflare橙色云）能力模块2代理检查
在区域上启用CNAME扁平化能力模块2扁平化检查
通过删除并重新创建域名来“解决”验证卡住的问题能力模块2禁止操作
验证完成后未更新SDK的
domain
/
issuerBaseURL
能力模块1后续步骤报告
在MCD配置下通过租户域名调用Management APIadvanced.md auth0-custom-domain头

Related Skills

相关技能

  • auth0-branding: Customize Universal Login appearance (page templates require a verified custom domain)
  • auth0-organizations: Organization-specific branding for B2B multi-tenancy
  • auth0-branding：自定义通用登录界面（页面模板需要已验证的自定义域名）
  • auth0-organizations：面向B2B多租户的组织专属品牌定制

References

参考文档

  • references/capability-setup.md: Set up a custom domain
  • references/capability-troubleshoot.md: Troubleshoot verification
  • references/capability-manage.md: Manage existing domains
  • references/capability-remove.md: Remove a custom domain
  • references/capability-health.md: Check domain health
  • references/providers.md: DNS provider router — NS → provider map; links into per-provider sub-files under 
    references/providers/
    (
    cloudflare.md
    , 
    route53.md
    , 
    azure-dns.md
    , 
    manual.md
    ). Open only the sub-file matching the detected provider.
  • references/examples.md: cURL samples plus end-to-end CI/CD automation and multi-environment patterns
  • references/api.md: Endpoint reference, CLI commands, error codes, scopes
  • references/advanced.md: MCD, default-domain, 
    auth0-custom-domain
    header, self-managed certs, token 
    iss
    behavior, verification troubleshooting deep-dive
  • 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
    行为、验证故障排查深度解析

External Docs

外部文档