1. 使用指南
  2. /

  3. 品牌化

  4. /
  5. 自定义域名

自定义域名

更新时间: 2025-02-18 09:00:47
编辑

有关支持「自定义域名」功能权益的 Authing 用户池版本信息，请查看 官网「价格」页 (opens new window)。如你的版本不支持此权益，且想试用，可开通体验期。有关体验期介绍及开通方式，请查看 体验期。

为什么要使用自定义域名？

在你的 Authing 用户池中，应用面板会拥有一个默认的域名 default.authing.cn。完成自定义域名的配置后，你的用户可以访问 login.your_domain.cn，从而始终在域名内完成登录。自定义域可以提升你的品牌知名度，并让用户始终在你的域名下使用提供的应用服务。

使用 Authing 提供的自定义域名功能​

路径：品牌化->自定义域名​

对于本功能，有几点重要的说明：​

  • 版本权益：Authing 当前支持在 B2B（高级版及以上）、B2E（高级版及以上）用户池场景下，为你的应用面板配置自定义域名。如果你是新注册用户，体验期内也可以自由使用本功能。更详细的版本权益说明，请查看 官网「价格」页 (opens new window)。
  • 在配置完你的自定义域名之后，Authing 为你提供的默认域名将仍旧生效，在访问原域名时，也将跳转到你配置的自定义域名下完成登录​。
  • 完成自定义域名配置的当下，如果有用户正在使用原域名进行登录，其登录状态不会受到影响；其重新登录时将会在自定义域名下完成登录​。
  • 使用嵌入式登录（Authing Guard）/ Authing SDK 实现登录时，也支持使用 Authing 提供的默认域名或配置自定义域名。

配置你的自定义域名

在 Authing 实现自定义域名的配置流程只需要三步：

第一步：输入合法的域名

你的自定义域名必须符合域名的标准规范，详情请参考 RFC 的域名标准规范 (opens new window)。

  1. 准备域名。
    如果你还没有自己的域名，可以前往域名注册商平台（如阿里云、腾讯云、华为云等）选购自己的域名。

  2. 备案。
    根据 工信部《互联网信息服务管理办法》（国务院 292 号令） (opens new window)，网站在未完成备案之前，不能指向大陆境内服务器开通访问。如果你的网站托管在中国大陆节点服务器，就必须申请互联网内容提供商 (ICP) 备案。若网站服务器为非中国大陆节点，则不用申请备案。出于合规性考虑，在 Authing 使用的自定义域名都需要首先完成备案才能使用。

  3. 输入域名。
    确保域名格式正确、合法且生效后，将你的域名填入输入框，点击 下一步。

第二步：在你的域名服务器中添加新的 CNAME

  1. 在填入有效的域名信息后，Authing 会生成对应的 TXT 和 CNAME 信息。你需要前往 DNS 服务提供商添加 TXT 和 CNAME 记录，将本页面的相关信息复制粘贴到你的 DNS 服务器，将域名指向 Authing 对应应用的域名。

示例：阿里云控制台 DNS 配置页 - CNAME 记录​

在不同的 DNS 服务器中添加 TXT 和 CNAME 记录的步骤略有差异，你可以参考：在阿里云创建一条新的 CNAME 指向 Authing。

  1. 确保当前信息在你的域名服务器中配置完成并生效后，返回 Authing 自定义域名->DNS配置，点击 连通测试。

通常来讲在 DNS 服务器中添加完成一条有效的 CNAME 信息后，需要过几分钟才会生效，因此如果你的连通测试没有通过，请稍作等待后重试。

  1. 连通测试完成后，点击 下一步。

第三步：填入有效的 SSL 证书信息​

出于安全性考虑，Authing 当前仅支持 https 协议下的域名。为了确保域名能够正常访问，你需要在域名服务器中找到你的 SSL 证书并下载。

由于不同服务商提供的证书信息种类繁多，你需要在其中找到以下两项信息：​

  • 签名证书​
  • 签名私钥​
  1. 上传签名证书​。
    证书通常是以 .crt 或 .pem 为扩展名的文件。使用文本编辑器打开证书文件可以看到内容 BEGIN CERTIFICATE 开头，END CERTIFICATE 结尾。​
    确认证书内容格式后，直接将证书内容复制粘贴到签名证书输入框。​
    签名证书的格式为：
----- BEGIN CERTIFICATE-----
签名证书正文
----- END CERTIFICATE-----
  1. 上传签名私钥​。
    私钥通常是以 .key 或 .pem 等为扩展名的文件。使用文本编辑器打开证书文件可以看到内容 BEGIN PRIVATE KEY 开头，END PRIVATE KEY 结尾。​​
    确认证书内容格式后，直接将证书内容复制粘贴至签名私钥输入框。​​
    证书私钥的格式为：
-----BEGIN RSA PRIVATE KEY-----
签名证书私钥正文
----- END RSA PRIVATE KEY-----
  1. 以上两部分信息完成配置后，点击 连通测试，我们会验证你所配置的证书是否对应你在第一步配置的域名，并且校验此证书是否仍在有效期内。​ ​
  2. 连通测试通过后，点击 完成。你的自定义域名当即生效！

这里以阿里云为例，说明如何下载、使用 SSL 证书。

相关功能配置​

在开始使用自定义域名之前，你需要对现有的功能配置进行一些修改，以确保你所配置的自定义域名对现有的功能均生效。​ ​

使用统一域名的用户池

在不使用统一域名的用户池中，自定义域名配置完成后，将仅对应用面板（即单点登录 SSO）的认证地址生效：

而在使用统一域名的用户池中，自定义域名配置完成后，由于用户池中的所有应用（包括应用面板、集成应用以及所有的自建应用）均使用统一的、用户池级别的域名。因此自定义域名配置完成后，将对该用户池中的所有应用生效。

如果不能明确是否该使用统一域名的用户池，请前往 了解何时应该使用统一域名的用户池。

涉及到应用域名的邮件模板​

当你开始使用自定义域名后，预置的邮件模板中涉及到应用域名的部分都会更新为自定义域名。涉及到的发送邮件相关的场景包括：​

  • 欢迎邮件​
  • 首次邮箱登录验证​
  • 控制台发起验证​
  • 密码到期提醒​
  • 管理员重置密码提醒​
  • 账户密码修改提醒​
  • 向内部管理员发送登录地址​
  • 向租户管理员发送登录地址​

自定义短信模板

遗憾的是，由于法律规定，第三方短信服务商在允许使用短信模板时，需要首先将你的自定义域名在平台进行备案，因此我们暂不支持你在使用自定义短信服务的同时使用自定义域名，这样的配置会导致短信无法正常发送。

如果你使用的是 Authing 内置的短信服务，则不需要有这个顾虑，可以正常使用。 ​

第三方身份源登录（社会化身份源、企业身份源）​

如果你在使用 Authing 的第三方身份源（社会化身份源/企业身份源），为了保证这些身份源在自定义域名下仍旧能够正常使用，你需要更新你的应用代码中包含的登录地址。​ ​

Authing API 调用​

​ 所有请求（即获取令牌，并实际调用 API）必须使用相同的域。通过自定义域获得的令牌必须在相同的域名下使用。​

如果使用自定义域的身份验证流来请求访问令牌以访问管理 API，那么也必须使用自定义域调用管理 API 端点。

POST https://mycustomdomain.cn/oidc/token
... // other parameters 
...
audience:https://YOUR_APP.authing.cn/api/v3/

你的访问令牌请求应该类似于：

GET https://mycustomdomain.com/api/v3/clients
Headers:
Authorization: Bearer <access_token>

SAML 相关功能配置

对于已经在控制台完成 SAML 配置并将 SAML 应用添加到应用面板的集成应用，如果已经配置了自定义域名，要使其生效，则需要重新 下载 SAML 元数据文档（新配置的自定义域名将直接更新为 entityID 的值），用以替换阿里云上配置的元数据。

​

下载 SAML 元数据文档​ - 控制台

​

替换 SAML 元数据文档​ - 阿里云工作台

私有化部署

当前我们还不支持在私有化场景下实现自定义域名。如果有特殊需求，请联系你的服务支持团队。

常见操作

更新 SSL 证书

每一份 SSL 证书都有自己的过期时间。如发现 SSL 证书即将过期，你可以点击 编辑 进行修改。更新证书信息之后需要重新进行连通测试，生效后你的自定义域名即可继续正常使用。

更换自定义域名

如果你需要更换自定义域名，那么需要删除掉现有的域名重新开始配置。如果当前的自定义域名处于生效状态，那么你在删除这个自定义域名后，目前正在这个域名下访问的用户将不能继续使用你的应用服务，而需关闭此页面后重新登录。

停止使用自定义域名

如要恢复使用默认域名，需要删除当前已经完成配置的域名。如果当前的自定义域名处于生效状态，那么你在删除这个自定义域名时，目前正在这个域名下访问的用户将不会受到影响，刷新界面之后需要重新登录。