跳到主要内容

自定义域名

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

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

  • 登录和注册页面的 URL
  • Passkey 关联 URL（在用户关联 Passkey 后更改域名可能会阻止他们的认证）。
  • 社交连接器或企业单点登录 (SSO) 连接器的回调 URI。
  • 将 Logto 与应用程序集成的 SDK 端点。
备注

在发布服务后更改域名可能会导致问题，因为你的应用程序代码和集成可能仍然引用旧域名。为了确保平稳过渡，在创建生产租户时就设置自定义域名。

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

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

  1. 导航到 Console > Settings > Domains。

  2. 在“Custom Domain”部分，输入你的域名并点击“add domain”。

    添加域名

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

    自定义域名处理中

  4. 等待验证和 SSL 过程。

    1. 我们将每 10 秒自动验证你的记录，直到添加自定义域名。只需确保输入的域名或 DNS 记录准确无误。
    2. 验证通常需要几分钟，但根据 DNS 提供商的不同，可能需要长达 24 小时。在此过程中，你可以随时离开。

故障排除​

SSL 证书问题

如果在设置自定义域名时遇到 SSL 证书问题，可能与 DNS 配置中的 CAA 记录有关。CAA 记录指定了哪些证书颁发机构 (CAs) 被授权为你的域名颁发证书。

要排查和解决与 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 文档 以获取更多信息。

要解决此问题，你需要释放区域保留。请按照上述链接中的说明在 Cloudflare 中释放区域保留。

使用自定义域名​

一旦你配置了设置，你的租户将同时可用自定义域名和默认的 Logto 域名。然而，需要进行某些配置以激活你的自定义域名。

备注

在本文中，我们假设你的自定义域名是 auth.example.com。

自定义域名已添加

更新应用程序的 SDK 端点​

通过修改端点的域名来更改 Logto SDK 的初始化代码。

const client = new LogtoClient({
  ...,// 其他选项
  endpoint: 'https://auth.example.com',
});

修改其他应用程序的认证端点​

如果你有未使用 Logto SDK 的应用程序，则需要更新其认证端点。

你可以在以下知名 URL 找到认证端点：

https://auth.example.com/oidc/.well-known/openid-configuration

更新社交连接器的回调 URI​

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

当你的用户使用自定义域名时，社交连接器的回调 URI 将使用新域名。因此，你需要导航到社交提供商的开发者控制台手动更新回调 URI。