自定义域名
在服务上线后更改域名可能会带来麻烦，因为你的应用代码和集成可能仍然引用旧域名。为确保平滑迁移，我们建议在创建生产租户时就设置自定义域名。
你的 Logto 租户自带一个默认的免费域名 {{tenant-id}}.app.logto。不过，你可以通过使用自定义域名（如 auth.example.com）来提升用户体验和品牌识别度。
你的自定义域名将用于多个功能：
- 登录和注册页面 的 URL
- 社交连接器 或 企业单点登录 (SSO) 连接器 的回调 URI
- Passkey 及 Passkey 登录 相关 URL（在用户已绑定 Passkey 后更改域名，可能会导致 MFA 和使用该凭证登录受阻）
- 将 Logto 集成到你的应用时的 SDK 端点
- 用于第三方平台（如微信、Apple 或其他要求你在域名下放置静态文件的服务）的域名所有权验证文件
多个自定义域名
Logto 现已支持为单个租户配置多个自定义域名，让你的登录页面可以通过多个品牌域名访问。
按套餐限制：
- 开发租户：可免费添加最多 2 个自定义域名（用于测试）
- 免费套餐：可免费添加 1 个自定义域名
- 专业套餐：包含 1 个自定义域名，可通过附加包最多添加至 10 个
- 企业套餐：如需超过 10 个自定义域名或有特殊需求，请联系我们
详细信息请参见 Logto 价格表。
使用多个自定义域名，你可以：
- 针对不同地区、本地化、应用、组织或顶级域名使用不同域名
- 在登录前后保持一致的品牌体验，增强信任感
- 通过 自定义界面 提供区域或品牌专属的认证 (Authentication) 体验
在控制台配置自定义域名
要在 Logto 控制台添加新的自定义域名，请按以下步骤操作：
-
进入 控制台 > 设置 > 域名。
-
在“添加自定义域名”区域，输入你的子域名（如
auth.example.com、auth.us.example.com），点击“添加域名”。
-
复制表格中的 CNAME 值
domains.logto.app，前往你的域名 DNS 服务商添加记录。
-
等待验证和 SSL 处理。
- 我们会每 10 秒自动验证一次记录，直到自定义域名添加成功。只需确保输入的域名或 DNS 记录准确无误。
- 验证通常只需几分钟，但也可能因 DNS 服务商不同而长达 24 小时。你可以在此期间自由浏览其他页面。
如需添加多个自定义域名，只需为每个域名重复上述步骤即可。
域名验证文件
部分第三方平台要求你在域名下托管一个小型文本或 JSON 文件，以证明域名所有权，才能使用其 OAuth、SSO 或其他集成。由于 Logto 自定义域名指向 Logto Cloud，你无法将文件上传到自己的源站。Logto 可以为你托管这些文件。
自定义域名激活后，打开 控制台 > 设置 > 域名 中的域名卡片，在 域名验证文件 区域添加、更新或移除文件。
支持的路径
- 带扩展名的根目录文件名，如
/MP_verify_xxx.txt或/apple-developer-domain-association.txt /.well-known/下的路径，如/.well-known/apple-developer-domain-association.txt
路径段仅允许字母、数字、点、连字符和下划线。不支持 /.well-known/ 之外的多级路径。
限制
- 每个自定义域名最多支持 10 个验证文件
- 每个文件内容最大 16,384 字符
- 内容类型：纯文本（
text/plain）或 JSON（application/json）
保存后，Logto 会在自定义域名下对 GET 和 HEAD 请求精确匹配并返回文件内容，例如：
https://auth.example.com/MP_verify_xxx.txt
https://auth.example.com/.well-known/apple-developer-domain-association.txt
Logto 现有路由始终优先生效。仅当没有其他 Logto 处理器匹配路径时，才会返回验证文件。
故障排查
SSL 证书问题
如果你在设置自定义域名时遇到 SSL 证书问题，可能与你 DNS 配置中的 CAA 记录有关。CAA 记录指定了哪些证书颁发机构（CA）被授权为你的域名颁发证书。如果你使用了 CAA 记录，需要为 Logto 授权 "letsencrypt.org" 和 "pki.goog"。
如需排查和解决与 CAA 记录相关的 SSL 证书问题，请参考 Cloudflare 的 CAA 记录文档。
“The hostname is associated with a held zone” 错误
如果你在添加自定义域名时遇到 "The hostname is associated with a held zone, please contact the owner to have the hold removed" 错误，说明该域名已在 Cloudflare 区域中，并被设置为“Zone Hold”状态。详见 Cloudflare 文档。
要解决此问题，你需要释放 zone hold。请按照上述链接中的说明在 Cloudflare 中释放 zone hold。
Cloudflare 托管域名连接超时（错误码 522）
如果你的域名托管在 Cloudflare，请关闭 CNAME 记录的 Cloudflare 代理。
设置自定义域名后出现 “Redirect URI does not match” 错误
如果在添加自定义域名后出现 “redirect URI does not match” 错误，你需要将 SDK 配置更新为使用自定义域名作为端点。
关于“主域名”：
Logto 没有单独的“主域名”设置。添加自定义域名后，你的自定义域名和默认 {tenant-id}.logto.app 域名都有效。你在 SDK 的 endpoint 参数中配置的域名决定了认证 (Authentication) 流程使用哪个域名。
解决方法：
将 SDK 初始化中的 endpoint 参数更新为你的自定义域名：
const client = new LogtoClient({
endpoint: 'https://auth.example.com', // 使用你的自定义域名
appId: 'your-app-id',
// ... 其他选项
});
同时确认在 控制台 → 应用 注册的重定向 URI 与你正在使用的域名一致。
注意： Logto 会自动为你的自定义域名申请和管理 SSL 证书，无需你自行配置证书。
使用自定义域名
配置好相关设置后，你的自定义域名和默认 Logto 域名都可用于你的租户。但要激活自定义域名，还需进行一些配置。
本文假设你的自定义域名为 auth.example.com。
为应用更新 SDK 端点
修改 Logto SDK 的初始化代码，将端点的域名替换为你的自定义域名。
const client = new LogtoClient({
...,// 其他选项
endpoint: 'https://auth.example.com',
});
在 控制台 > 应用 的应用详情页，滚动到“端点与凭证”区域。切换域名下拉框，查看并复制对应端点以更新你的应用设置。
为其他应用修改认证 (Authentication) 端点
如果你的应用未使用 Logto SDK，则需要手动更新其认证 (Authentication) 端点。
你可以在如下 well-known URL 获取认证 (Authentication) 端点：
https://auth.example.com/oidc/.well-known/openid-configuration
更新社交连接器重定向 URI
社交连接器 使用 OIDC/OAuth 协议。当用户通过自定义域名登录时，重定向 URI 会自动使用该自定义域名。你需要在社交平台开发者控制台更新重定向 URI。
操作步骤：
- 进入 控制台 > 连接器 > 社交连接器，选择你的连接器。
- 复制连接器详情中显示的重定向 URI。Logto 会列出你已配置的所有自定义域名的可用重定向 URI。
- 将该重定向 URI 添加到社交平台开发者控制台（如 Google、GitHub、Facebook）。
如有多个自定义域名：
- 为每个自定义域名都添加对应的重定向 URI，确保无论用户访问哪个域名都能正常社交登录。
- 默认 Logto 域名（
*.logto.app）依然有效。仅当你希望支持默认域名登录时才需添加。 - 对于 GitHub 连接器，请使用 GitHub Apps 而非 GitHub 控制台配置的 OAuth apps，因为 GitHub Apps 支持多个重定向 URI，OAuth apps 仅支持单一重定向 URI。
更新基于 OIDC 的企业单点登录 (SSO) 连接器重定向 URI
基于 OIDC 的企业连接器 与社交连接器用法一致。
操作步骤：
- 进入 控制台 > 企业单点登录 (SSO)，选择你的 OIDC 连接器。
- 复制连接器详情中的重定向 URI。Logto 会列出你已配置的所有自定义域名的可用重定向 URI。
- 在你的身份提供商 (IdP) 设置中更新重定向 URI。
如有多个自定义域名： 请将所有对应的重定向 URI 添加到 IdP，确保企业单点登录 (SSO) 能在所有域名下正常工作。
更新基于 SAML 的企业单点登录 (SSO) 连接器 ACS URL
基于 SAML 的企业连接器 使用 Assertion Consumer Service (ACS) URL 替代重定向 URI。
操作步骤：
- 进入 控制台 > 企业单点登录 (SSO)，选择你的 SAML 连接器。
- 在“在 IdP 中配置”区域，切换域名下拉框以选择你的自定义域名。
- 复制你想支持的域名的 ACS URL。
- 将这些 ACS URL 添加到 SAML 身份提供商配置中。
重要提示： 你选择的域名决定了用户在 SSO 认证 (Authentication) 后被重定向的位置。请根据你的应用期望接收 SAML 响应的域名进行配置。
用于 MFA 和登录的 Passkey
多因素认证 (MFA) 的 Passkey 和 Passkey 登录 绑定于注册时的域名。用户必须通过同一域名登录才能使用其 Passkey。
当前限制：Logto 暂不支持跨域名 Passkey 验证。如果用户在 auth.us.example.com 注册了 Passkey，则必须通过 auth.us.example.com 登录才能使用该 Passkey 进行 MFA 验证或 Passkey 登录。在一个域名注册的 Passkey 无法用于其他自定义域名的登录。