为 Azure API 管理实例配置自定义域名

适用于:所有 API 管理层级

在 Azure 云中创建 Azure API 管理服务实例时,Azure 将为它分配一个 azure-api.cn 子域(例如 apim-service-name.azure-api.cn)。 你还可以使用自己的自定义域名(例如 contoso.com)公开 API 管理终结点。 本文演示了如何将现有的自定义 DNS 名称映射到 API 管理实例公开的终结点。

重要

API 管理仅接受主机头值与以下项匹配的请求:

  • 网关的默认域名
  • 网关的任何已配置自定义域名

先决条件

  • API 管理实例。 有关详细信息,请参阅创建 Azure API 管理实例

  • 由你或你的组织拥有的自定义域名。 本文不提供有关如何购买自定义域名的说明。

  • 可选的,一个包含公钥和私钥的有效证书 (.PFX)。 使用者或使用者可选名称 (SAN) 必须与域名匹配(这使得 API 管理实例可以通过 TLS 安全地公开 URL)。

    查看域证书选项

  • 托管在 DNS 服务器上的 DNS 记录,该记录将自定义域名映射到 API 管理实例的默认域名。 本主题不提供有关如何托管 DNS 记录的说明。

    有关所需记录的详细信息,请参阅本文后面的 DNS 配置

自定义域的终结点

可以向多个 API 管理终结点分配自定义域名。 当前有以下终结点可用:

端点 默认
网关 默认值为:<apim-service-name>.azure-api.cn。 网关是唯一可用于“消耗”层中的配置的终结点。

添加自定义网关域后,默认网关终结点配置仍可用。
开发人员门户 默认值为:<apim-service-name>.developer.azure-api.cn
Management 默认值为:<apim-service-name>.management.azure-api.cn
配置 API (v2) 默认值为:<apim-service-name>.configuration.azure-api.cn
SCM 默认值为:<apim-service-name>.scm.azure-api.cn

注意事项

  • 可以更新服务层中支持的任何终结点。 通常,客户会更新“网关”(此 URL 用于调用通过 API 管理公开的 API)和“开发人员门户”(开发人员门户 URL)。
  • 配置自定义网关域名后,仍然可使用默认网关终结点,并且无法删除它。 对于使用自定义域名配置的其他 API 管理终结点(如开发者门户),默认终结点不再可用。
  • 只有 API 管理实例所有者能够在内部使用“管理”和“SCM”终结点 。 很少会为这些终结点分配自定义域名。
  • “高级”和“开发人员”层支持为“网关”终结点设置多个主机名。
  • 除“消耗”层之外的所有层都支持类似于 *.contoso.com 的通配符域名。 例如,对于至 api.contoso.com 的请求,特定子域证书(例如,api.contoso.com)优先于通配符证书 (*.contoso.com)。

域证书选项

API 管理支持从 Azure 密钥保管库导入的自定义 TLS 证书或证书。 还可以启用免费的托管证书。

警告

如果需要证书固定,请使用自定义域名和自定义或密钥保管库证书,而不是默认证书或免费托管证书。 建议不要硬依赖于一个你不管理的证书。

如果已有第三方提供商提供的私有证书,则可以上传它到 API 管理实例。 必须满足以下要求。 (如果启用由 API 管理托管的免费证书,则该证书已经满足这些要求。)

  • 导出为 PFX 文件,使用三重 DES 加密并且还可以选择用密码进行保护。
  • 包含长度至少为 2048 位的私钥
  • 包含证书链中的所有中间证书和根证书。

配置自定义域名(门户)

根据想要使用的域证书选择步骤。

  1. Azure 门户中导航到自己的 API 管理实例。
  2. 在左侧导航栏中选择“自定义域”。
  3. 选择“+添加”,或选择要更新的现有终结点
  4. 在右侧窗口中,选择用于自定义域的终结点的“类型”。
  5. 在“主机名”字段中,指定要使用的名称。 例如,api.contoso.com
  6. 在“证书”下,选择“自定义”
  7. 选择“证书文件”以选择并上传证书。
  8. 上传有效的 .PFX 文件并提供其密码(如果该证书受密码保护)。
  9. 配置网关终结点时,请根据需要选择或取消选择其他选项,包括“协商客户端证书”或“默认 SSL 绑定”。 使用自定义证书配置网关域
  10. 选择“添加”或为现有终结点选择“更新”。
  11. 选择“保存” 。

注意

分配证书的过程可能需要 15 分钟或更久,这取决于部署规模。 开发人员层有故障时间,而基本层和更高层则不会。


DNS 配置

  • 为自定义域配置 CNAME 记录。
  • 使用 API 管理的免费托管证书时,还会配置 TXT 记录以建立域的所有权。

注意

免费证书是由 DigiCert 颁发的。 对于某些域,必须通过创建值为 0 issue digicert.comCAA 域记录显式允许 DigiCert 作为证书颁发者。

CNAME 记录

配置从自定义域名(例如,api.contoso.com)指向 API 管理服务主机名(例如 <apim-service-name>.azure-api.cn)的 CNAME 记录。 如果 IP 地址发生更改,CNAME 记录比 A 记录更稳定。 有关详细信息,请参阅 Azure API 管理的 IP 地址 API 管理常见问题解答

注意

某些域注册机构只允许在使用 CNAME 记录(例如 www.contoso.com),而非根名称(例如 contoso.com)时映射子域。 有关 CNAME 记录的详细信息,请参阅注册机构提供的文档或 IETF 域名 - 实现和规范

TXT 记录

为 API 管理启用免费的托管证书时,还会在 DNS 区域中配置 TXT 记录以建立域名的所有权。

  • 记录的名称是前缀为 apimuid 的自定义域名。 示例:apimuid.api.contoso.com
  • 该值是 API 管理实例提供的域所有权标识符。

使用门户配置自定义域的免费托管证书时,会自动显示必需 TXT 记录的名称和值。

还可以通过调用获取域所有权标识符 REST API 来获取域所有权标识符。

API 管理代理服务器如何在 TLS 握手中使用 SSL 证书做出响应

为网关终结点配置自定义域时,可以设置其他属性,这些属性决定 API 管理如何服务器证书做出响应,具体取决于客户端请求。

调用时使用服务器名称指示 (SNI) 标头的客户端

如果为网关终结点配置了一个或多个自定义域,则 API 管理可以响应来自以下两者的 HTTPS 请求:

  • 自定义域(例如 contoso.com
  • 默认域(例如 apim-service-name.azure-api.cn)。

根据 SNI 标头中的信息,API 管理会使用相应的服务器证书进行响应。

调用时不使用 SNI 标头的客户端

如果使用不发送 SNI 标头的客户端,则 API 管理会根据以下逻辑创建响应:

  • 如果服务仅为网关配置了一个自定义域 - 则默认证书是颁发给网关自定义域的证书。

  • 如果服务为网关配置了多个自定义域(在“开发人员层”和“高级层”中受支持)- 则可以通过将 defaultSslBinding 属性设置 true ("defaultSslBinding":"true") 来指定默认证书。 在门户中,选择“默认 SSL 绑定”复选框。

    如果未设置该属性,则默认证书是颁发给在 *.azure-api.cn 上托管的默认网关域的证书。

对包含大型有效负载的 PUT/POST 请求的支持

当在 HTTPS 中使用客户端证书时,API 管理代理服务器支持包含大型有效负载 (> 40 KB) 的请求。 为了防止服务器的请求被冻结,可以在网关主机名上将 negotiateClientCertificate 属性设置为 true("negotiateClientCertificate": "true")。 在门户中,选择“协商客户端证书”复选框。

如果该属性设置为 true,则在进行 SSL/TLS 连接时将在交换任何 HTTP 请求之前请求证书。 由于该设置应用于“网关主机名”级别,因此所有连接请求都会要求客户端证书。 可以避开此限制并为网关配置最多 20 个自定义域(仅在高级层才受支持)。

后续步骤

升级和缩放你的服务