跳到主要内容

自定义域名

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

你的自定义域名会用于以下几个功能：

备注:

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

在 Console 中配置自定义域名​

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

  1. 进入 Console > 设置 > 域名。

  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 的文档。

“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。