跳到主要内容

自定义域名

你的 Logto 租户自带一个默认的免费域名 {{tenant-id}}.app.logto。不过，你可以通过使用自定义域名（如 auth.example.com）来提升用户体验和品牌识别度。

你的自定义域名用于多个功能：

备注:

在服务上线后更改域名可能会带来问题，因为你的应用代码和集成可能仍然引用旧域名。为确保平滑过渡，请在生产租户创建时一开始就设置自定义域名。

在控制台配置自定义域名​

要在 Logto 控制台添加新的自定义域名，请按照以下步骤操作：

  1. 进入 控制台 > 设置 > 域名。

  2. 在“自定义域名”部分，输入你的域名并点击“添加域名”。

    添加域名

  3. 复制表格中的 CNAME 值，前往你的域名 DNS 服务商添加记录。

    自定义域名处理中

  4. 等待验证和 SSL 处理。

    1. 我们会每 10 秒自动验证一次你的记录，直到自定义域名添加成功。只需确保输入的域名或 DNS 记录准确无误。
    2. 验证通常只需几分钟，但根据 DNS 服务商不同，最长可能需要 24 小时。过程中你可以自由离开页面。

故障排查​

SSL 证书问题​

如果你在设置自定义域名时遇到 SSL 证书问题，可能与你的 DNS 配置中的 CAA 记录有关。CAA 记录指定了哪些证书颁发机构（CA）被授权为你的域名颁发证书。如果你使用了 CAA 记录，需要为 Logto 授权 "letsencrypt.org" 和 "pki.goog" 这两个 CA。

如需排查和解决与 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。

使用自定义域名​

一旦你完成设置，你的自定义域名和默认 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​

如果你的用户正在使用自定义域名，社交连接器的回调 URI 会自动更新。你需要前往社交服务商的开发者控制台，更新回调 URI。

当你的用户使用自定义域名时，社交连接器的回调 URI 会使用新域名。因此，你需要前往社交服务商的开发者控制台手动更新回调 URI。