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

發行項
2025/04/30

适用于：所有 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`
管理	默认值为：`<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 证书或证书。还可以启用免费的托管证书。

警告

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

自定义
密钥保管库

建议使用 Azure 密钥保管库管理证书，并将这些证书设置为 autorenew。

如果使用 Azure 密钥保管库来管理自定义域 TLS 证书，请确保该证书“作为证书”而不是“机密”插入密钥保管库。

警告

在 API 管理中使用密钥保管库证书时，请注意不要删除证书、密钥保管库或用于访问密钥保管库的托管标识。

若要提取 TLS/SSL 证书，API 管理必须对包含该证书的 Azure Key Vault 具有“列表”和“获取机密”权限。

使用 Azure 门户导入证书时，将自动完成所有必要的配置步骤。
使用命令行工具或管理 API 时，必须通过两个步骤手动授予这些权限：
1. 在 API 管理实例的“托管标识”上，启用系统分配的或用户分配的托管标识。请注意该页上的主体 ID。
2. 向托管标识分配访问密钥保管库的权限。使用以下部分中的步骤。
配置对密钥保管库的访问权限
1. 在门户中导航到你的密钥保管库。
2. 在左侧菜单中，选择“访问配置”，并记下配置的权限模型。
3. 根据权限模型，为 API 管理托管标识配置密钥保管库访问策略或 Azure RBAC 访问。
  
  添加密钥保管库访问策略：
  1. 在左侧菜单中，选择“访问策略”。
  2. 在“访问策略”页上，选择“+ 创建”。
  3. 在“权限”选项卡上的“机密权限”下，选中“获取”和“列出”，然后选择“下一步”。
  4. 在“主体”选项卡上，选择主体，搜索托管标识的资源名称，然后选择“下一步”。如果你使用系统分配的标识，则主体为你的 API 管理实例的名称。
  5. 再次选择“下一步”。在“查看 + 创建”选项卡上，选择“创建”。
  若要配置 Azure RBAC 访问，请执行以下操作：
  1. 在左侧菜单中，选择“访问控制(IAM)”。
  2. 在“访问控制(IAM)”页上，选择“添加角色分配”。
  3. 在“角色”选项卡上，选择“密钥保管库机密用户”。
  4. 在“成员”选项卡上，选择“托管标识”>“+ 选择成员”。
  5. 在“选择托管标识”页上，选择系统分配的托管标识或与 API 管理实例关联的用户分配的托管标识，然后选择“选择”。
  6. 选择审核 + 分配。
若要配置 Azure RBAC 访问，请执行以下操作：
1. 在左侧菜单中，选择“访问控制(IAM)”。
2. 在“访问控制(IAM)”页上，选择“添加角色分配”。
3. 在“角色”选项卡上，选择“密钥保管库证书用户”。
4. 在成员选项卡上，选择托管标识>+ 选择成员。
5. 在“选择托管标识”页上，选择系统分配的托管标识或与 API 管理实例关联的用户分配的托管标识，然后选择“选择”。
6. 选择审核 + 分配。

如果证书设置为 autorenew 并且 API 管理层（除“开发人员”层以外的所有层）附带 SLA，API 管理将自动选取最新版本，而不会给服务造成任何中断。

有关详细信息，请参阅在 Azure API 管理中使用托管标识。

配置自定义域名（门户）

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

自定义
密钥保管库

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

在 Azure 门户中导航到自己的 API 管理实例。
在左侧导航栏中选择“自定义域”。
选择+添加，或选择要更新的现有终结点。
在右侧窗口中，选择自定义域终结点的类型。
在“主机名”字段中，指定要使用的名称。例如，api.contoso.com。
在“证书”下，选择“密钥保管库”然后“选择”。
1. 从下拉列表中选择“订阅”。
2. 从下拉列表中选择“密钥保管库”。
3. 加载证书后，从下拉列表中选择“证书”。单击“选择”。
4. 在“客户端标识”中，选择在实例中启用的系统分配的标识或用户分配的托管标识以访问密钥保管库。
配置网关终结点时，请根据需要选择或取消选择其他选项，包括“协商客户端证书”或“默认 SSL 绑定”。
选择“添加”或为现有终结点选择“更新”。
选择“保存”。

注意

分配证书的过程可能需要 15 分钟或更久，这取决于部署规模。开发者套餐有停机时间，而基本套餐及以上级别则没有。

DNS 配置

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

注意

免费证书是由 DigiCert 颁发的。对于某些域，必须通过创建值为的 0 issue digicert.com显式允许 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，则将在交换任何 HTTP 请求之前于 SSL/TLS 连接时请求客户端证书。由于该设置应用于“网关主机名”级别，因此所有连接请求都会要求客户端证书。可以避开此限制并为网关配置最多 20 个自定义域（仅在高级层才受支持）。

升级和扩展你的服务

共用方式為