跳到主要内容

自定义域名

备注:

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

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

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

多个自定义域名​

Logto 现在支持为单个租户配置多个自定义域名，让你的登录页面可以通过多个品牌域名访问。

按套餐限制：

  • 开发租户：可免费添加最多 2 个自定义域名（用于测试）
  • 免费套餐：可免费添加 1 个自定义域名
  • 专业套餐：包含 1 个自定义域名，可通过附加包最多添加至 10 个自定义域名
  • 企业套餐：如需超过 10 个自定义域名或有定制需求，请联系我们

详细信息请参见 Logto 价格表。

使用多个自定义域名，你可以：

  • 为不同地区、本地化、应用、组织 (Organizations) 或顶级域名使用不同域名
  • 在登录前后保持一致的品牌体验，增强信任感
  • 通过 自定义界面 提供区域或品牌专属的认证 (Authentication) 体验

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

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

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

  2. 在“添加自定义域名”区域，输入你的子域名（如 auth.example.com、auth.us.example.com），点击“添加域名”。

    添加域名

  3. 复制表格中的 CNAME 值 domains.logto.app，前往你的域名 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 文档。

要解决此问题，你需要释放该区域的 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。

步骤：

  1. 进入 控制台 > 连接器 > 社交连接器，选择你的连接器。
  2. 复制连接器详情中显示的重定向 URI。Logto 会列出你配置的所有自定义域名下可用的重定向 URI。
  3. 将该重定向 URI 添加到社交平台的开发者控制台（如 Google、GitHub、Facebook）。

如有多个自定义域名：

  • 为每个自定义域名都添加对应的重定向 URI，确保无论用户访问哪个域名都能正常社交登录。
  • 默认 Logto 域名（*.logto.app）依然有效。仅当你希望支持默认域名登录时才需添加。
  • 对于 GitHub 连接器，请使用 GitHub Apps，而不是在 GitHub 控制台配置的 OAuth apps，因为 GitHub Apps 支持多个重定向 URI，OAuth apps 仅支持单一重定向 URI。

更新基于 OIDC 的企业单点登录 (SSO) 连接器重定向 URI​

基于 OIDC 的企业连接器 与社交连接器用法一致。

步骤：

  1. 进入 控制台 > 企业单点登录 (SSO)，选择你的 OIDC 连接器。
  2. 复制连接器详情中的重定向 URI。Logto 会列出你配置的所有自定义域名下可用的重定向 URI。
  3. 在你的身份提供商 (IdP) 设置中更新重定向 URI。

如有多个自定义域名： 在 IdP 中添加所有对应的重定向 URI，确保企业单点登录 (SSO) 能在所有域名下正常工作。

更新基于 SAML 的企业单点登录 (SSO) 连接器 ACS URL​

基于 SAML 的企业连接器 使用 Assertion Consumer Service (ACS) URL，而不是重定向 URI。

步骤：

  1. 进入 控制台 > 企业单点登录 (SSO)，选择你的 SAML 连接器。
  2. 在 “在 IdP 中配置” 区域，通过域名下拉框切换你的自定义域名。
  3. 复制你要支持的域名下的 ACS URL。
  4. 将这些 ACS URL 添加到你的 SAML 身份提供商配置中。

重要提示： 你选择的域名决定了用户在 SSO 认证 (Authentication) 后被重定向到哪里。请根据你的应用期望接收 SAML 响应的域名进行配置。

MFA 的 Passkey​

多因素认证 (MFA) 的 Passkey 绑定在注册时所用的域名上。用户必须通过同一域名登录才能使用其 Passkey。

当前限制：Logto 暂不支持跨域 Passkey 验证。如果用户在 auth.us.example.com 注册了 Passkey，则必须通过 auth.us.example.com 登录才能使用该 Passkey 进行认证 (Authentication)。在一个域名注册的 Passkey 无法用于其他自定义域名的登录。