auth0-custom-domains

Auth0 自定义域

端到端完成 Auth0 自定义域工作：涵盖 Auth0 Management API、DNS 提供商、验证轮询，以及串联所有环节的配置。自动识别用户的 DNS 提供商（Cloudflare、Route 53、Azure DNS 或其他），并在提供商支持时自动创建记录。

概览

此技能基于能力，而非步骤。它将用户可能想要完成的工作划分为五项不同的能力（设置、故障排查、管理、移除、健康检查），每项能力都有自己的流程，存放在专门的参考文件中。主 SKILL.md 充当入口：其中包含能力表、关键概念、前置条件，以及适用于所有流程的常见错误。用户调用此技能时，请从表中选择匹配的能力，加载对应的参考文件，并遵循其中的流程。

能力设计与用户实际使用 Auth0 自定义域的方式相符：“设置一个”“我的域出问题了”“更改某项内容”“移除一个”或“检查我的设置是否仍在运行”。每种意图都对应一条独立流程，并包含自己的安全检查和交接环节。

交互方式

使用日常对话文本提问。除非是在执行破坏性或不可逆操作（创建、PATCH、删除）前进行单次是/否确认，否则绝不使用结构化 UI 组件（例如 AskUserQuestion）。其他情况请遵循以下要求：

• 能力路由：提供编号列表，然后等待用户回复
• 收集输入：每次提出一个聚焦的问题；等待用户回复后再问下一个
• 自由格式值（主机名、域名等）：直接提问，不要使用会强制用户先点击才能输入的组件

能力路由的正确示例：

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 情况给出错误建议。回答错误代码问题后，只有在用户希望继续时，才提出引导其使用匹配的功能（例如：“要我在应用此修复后带你完成 Set up 吗？”）。

状态和上下文	正确的诊断和修复方法
Free 层级下对 POST /custom-domains 返回 403	不是套餐层级问题。 **所有套餐（包括 Free）**均提供自定义域名（Auth0 文档已确认：“要设置免费的自定义域名，Auth0 租户必须提供有效的信用卡以供验证并防止欺诈。信用卡不会被扣款。”）。前往 Dashboard → Tenant Settings → Billing 添加信用卡即可修复。不要建议升级套餐。
对 POST /custom-domains 发送 type: self_managed_certs 时返回 403	这确实是套餐问题。自管理证书仅限 Enterprise 套餐。可以将类型降级为 type: auth0_managed_certs（所有套餐均可使用），或升级到 Enterprise。
对 POST /custom-domains 返回 409	此域名已存在于此租户或其他租户中。运行 auth0 domains list 检查；如果域名存在于用户拥有的其他租户中，请先在那里删除。不要重试创建新域名。
对 PATCH /custom-domains/{id} 的请求正文中包含 type 时返回 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 扁平化 / 冲突记录 / DNS 传播 / 私有区域问题，然后重试。参见 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 边缘节点的 DNS 记录（例如，{tenant}.edge.tenants.auth0.com）。必须永久保留在 DNS 中，以便续订证书
Auth0 管理的证书	Auth0 每隔约 3 个月签发并自动续订 TLS 证书。此选项为默认且推荐的选项。证书类型在创建时固定，无法通过 PATCH 更改
自行管理的证书	TLS 在反向代理（Cloudflare、CloudFront、Azure Front Door 或 GCP LB）处终止。仅限 Enterprise；验证使用 TXT，而非 CNAME。证书类型在创建时固定，无法通过 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 用于告知 Auth0 流量经过反向代理时，哪个请求标头携带真实客户端 IP。有效值：true-client-ip、cf-connecting-ip、x-forwarded-for、x-azure-clientip。可在创建时或通过 PATCH 设置
域元数据	附加到自定义域名的最多 10 组自定义键值对（键和值均不超过 255 个字符）。可通过 event.custom_domain.domain_metadata 从 Actions 中读取，用于按域名执行逻辑（区域、品牌、环境标记）

完整架构以及令牌／iss 行为请参阅 references/advanced.md。

前提条件

这些条件适用于任何会写入租户的功能。检查域名健康状态为只读操作，可先运行以验证这些条件。

Auth0 Management API 访问权限

所有功能均使用 Management API。可使用以下任一方式：

• 已通过身份验证并连接到目标租户的 Auth0 CLI（auth0 ...）（auth0 tenants use <name>）；或
• 在 references/api.md 中列出的权限范围内，使用机器对机器应用程序。

在某项功能中运行第一条 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 记录。移除自定义域名会删除这条记录。排查验证问题时，可能会建议进行需要编辑 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 其他：无程序化访问权限；用户需在提供商的控制面板中手动添加记录。

自动化的套餐要求：这三个自动化级别都不要求 DNS 提供商提供付费套餐。Cloudflare MCP 支持在 Free 套餐上执行 DNS 记录的增删改查（2024 年 9 月之后创建的 Free 区域每个区域最多有 200 条 DNS 记录；Auth0 的 CNAME 计为一条）。Route 53 按使用量付费（每个托管区域每月约 $0.50，另加查询费用，不属于 AWS 免费套餐）。Azure DNS 基于订阅，不设套餐级别限制；已登录的身份需要 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（会导致证书续订失败）	功能 5：解读结果
使用子域名和通行密钥，却未设置 relying_party_identifier	功能 3：RPID 部分
尝试通过 PATCH 更改证书类型	功能 3：范围说明
为 CNAME 启用 DNS 代理（Cloudflare 橙色云朵）	功能 2：代理检查
为区域启用 CNAME 扁平化	功能 2：扁平化检查
删除并重新创建以“解除”验证卡住的问题	功能 2：不应采取的做法
验证后未更新 SDK 的 domain / issuerBaseURL	功能 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 服务