配置自定义域名Configure a custom domain name

创建 API 管理 (APIM) 实例时,Azure 会将其分配到 azure api.net 的一个子域(例如 apim-service-name.azure-api.cn)。When you create an API Management (APIM) instance, Azure assigns it to a subdomain of azure-api.cn (for example, apim-service-name.azure-api.cn). 不过,你可以使用自己的域名(例如 contoso.com)公开你的 APIM 终结点。However, you can expose your APIM endpoints using your own domain name, such as contoso.com. 本教程演示了如何将现有的自定义 DNS 名称映射到 Azure API 管理实例公开的终结点。This tutorial shows you how to map an existing custom DNS name to endpoints exposed by an Azure API Management instance.

Warning

想要使用证书固定改进其应用程序安全性的客户必须使用自定义域名和他们管理的证书,而不是使用默认证书。Customers who wish to use certificate pinning to improve the security of their applications must use a custom domain name and certificate which they manage, not the default certificate. 改为固定默认证书的客户将硬依赖于他们不控制的证书属性,建议不要这样做。Customers that pin the default certificate instead will be taking a hard dependency on the properties of the certificate they don't control, which is not a recommended practice.

先决条件Prerequisites

若要执行本文中所述的步骤,必须具有:To perform the steps described in this article, you must have:

  • 一个有效的 Azure 订阅。An active Azure subscription.

    如果没有 Azure 订阅,可在开始前创建一个试用帐户If you don't have an Azure subscription, create a trial account before you begin.

  • 一个 APIM 实例。An APIM instance. 有关详细信息,请参阅创建 Azure API 管理实例For more information, see Create an Azure API Management instance.

  • 一个由你拥有的自定义域名。A custom domain name that is owned by you. 必须单独获取要使用的自定义域名并将其托管在 DNS 服务器上。The custom domain name you want to use, must be procured separately and hosted on a DNS server. 本主题没有说明如何托管自定义域名。This topic does not give instructions on how to host a custom domain name.

  • 必须具有有效的带有公钥和私钥 (.PFX) 的证书。You must have a valid certificate with a public and private key (.PFX). 使用者或使用者可选名称 (SAN) 必须与域名匹配(这使得 APIM 可以通过 SSL 安全地公开 URL)。Subject or subject alternative name (SAN) has to match the domain name (this enables APIM to securely expose URLs over SSL).

使用 Azure 门户设置自定义域名Use the Azure portal to set a custom domain name

  1. Azure 门户中导航到你的 APIM 实例。Navigate to your APIM instance in the Azure portal.

  2. 选择“自定义域和 SSL” 。Select Custom domains and SSL.

    可以为许多终结点分配自定义域名。There are a number of endpoints to which you can assign a custom domain name. 当前有以下终结点可用:Currently, the following endpoints are available:

    • 代理(默认值为:<apim-service-name>.azure-api.cn),Proxy (default is: <apim-service-name>.azure-api.cn),

    • 门户(默认值为:<apim-service-name>.portal.azure-api.cn),Portal (default is: <apim-service-name>.portal.azure-api.cn),

    • 管理(默认值为:<apim-service-name>.management.azure-api.cn),Management (default is: <apim-service-name>.management.azure-api.cn),

    • SCM(默认值为:<apim-service-name>.scm.azure-api.cn)。SCM (default is: <apim-service-name>.scm.azure-api.cn).

      Note

      可以更新所有终结点或者更新其中的一部分。You can update all of the endpoints or some of them. 通常情况下,客户会更新代理(此 URL 用来调用通过 API 管理公开的 API)和门户(开发人员门户 URL)。Commonly, customers update Proxy (this URL is used to call the API exposed through API Management) and Portal (the developer portal URL). 管理SCM 终结点由 APIM 客户在内部使用,因此很少会为其分配自定义域名。Management and SCM endpoints are used internally by APIM customers and thus are less frequently assigned a custom domain name.

  3. 选择要更新的终结点。Select the endpoint that you want to update.

  4. 在右侧窗口中,单击“自定义” 。In the window on the right, click Custom.

    • 在“自定义域名” 中,指定要使用的名称。In the Custom domain name, specify the name you want to use. 例如,api.contoso.comFor example, api.contoso.com. 还支持通配符域名(例如 *.domain.com)。Wildcard domain names (for example, *.domain.com) are also supported.

    • 证书中,从密钥保管库中选择证书。In the Certificate, select a certificate from Key Vault. 如果证书受密码保护,你还可以上传有效的 .PFX 文件并提供其密码You can also upload a valid .PFX file and provide its Password, if the certificate is protected with a password.

      Tip

      如果使用 Azure 密钥保管库来管理自定义域 SSL 证书,请确保该证书作为证书 而不是机密 插入到密钥保管库中。If you use Azure Key Vault to manage the custom domain SSL certificate, make sure the certificate is inserted into Key Vault as a certificate, not a secret. 如果证书设置为“自动轮换”,API 管理会自动选取最新版本。If the certificate is set to autorotate, API Management will pick up the latest version automatically.

  5. 单击“应用”。Click Apply.

    Note

    分配证书的过程可能需要 15 分钟或更久,这取决于部署规模。The process of assigning the certificate may take 15 minutes or more depending on size of deployment. 开发人员 SKU 有故障时间,基本和更高版本的 SKU 没有故障时间。Developer SKU has downtime, Basic and higher SKU's do not have downtime.

APIM 代理服务器在 TLS 握手中如何通过 SSL 证书进行响应How APIM Proxy Server responds with SSL certificates in the TLS handshake

调用时使用 SNI 标头的客户端Clients calling with SNI header

如果客户为代理配置了一个或多个自定义域,则 APIM 可以响应来自自定义域(例如 contoso.com)以及默认域(例如 apim-service-name.azure-api.cn)的 HTTPS 请求。If the customer has one or multiple custom domains configured for Proxy, APIM can respond to HTTPS requests from the custom domain(s) (for example, contoso.com) as well as default domain (for example, apim-service-name.azure-api.cn). APIM 根据服务器名称指示 (SNI) 标头中的信息使用合适的服务器证书进行响应。Based on the information in the Server Name Indication (SNI) header, APIM responds with appropriate server certificate.

调用时不使用 SNI 标头的客户端Clients calling without SNI header

如果客户使用不发送 SNI 标头的客户端,则 APIM 会根据以下逻辑创建响应:If the customer is using a client, which does not send the SNI header, APIM creates responses based on the following logic:

  • 如果服务仅为代理配置了一个自定义域,则默认证书是已颁发给代理自定义域的证书。If the service has just one custom domain configured for Proxy, the Default Certificate is the certificate that was issued to the Proxy custom domain.
  • 如果服务为代理配置了多个域(只有高级层才支持),则客户可以指定哪个证书应当作为默认证书。If the service has configured multiple custom domains for Proxy (only supported in the Premium tier), the customer can designate which certificate should be the default certificate. 若要设置默认证书,defaultSslBinding 属性应当设置为 true ("defaultSslBinding":"true")。To set the default certificate, the defaultSslBinding property should be set to true ("defaultSslBinding":"true"). 如果客户未设置该属性,则默认证书是颁发给 *.azure api.net 上托管的默认代理域的证书。If the customer does not set the property, the default certificate is the certificate issued to default Proxy domain hosted at *.azure-api.net.

对包含大型有效负载的 PUT/POST 请求的支持Support for PUT/POST request with large payload

当在 HTTPS 中使用客户端证书时,APIM 代理服务器支持包含大型有效负载的请求(例如,有效负载 > 40 KB)。APIM Proxy server supports request with large payload when using client-side certificates in HTTPS (for example, payload > 40 KB). 若要防止服务器的请求被冻结,客户可以在代理主机名上设置属性 "negotiateClientCertificate": "true"To prevent the server's request from freezing, customers can set the property "negotiateClientCertificate": "true" on the Proxy hostname. 如果该属性设置为 true,则在进行 SSL/TLS 连接时将在交换任何 HTTP 请求之前请求证书。If the property is set to true, the client certificate is requested at SSL/TLS connection time, before any HTTP request exchange. 由于该设置是在代理主机名级别应用的,因此,所有连接请求都会请求客户端证书。Since the setting applies at the Proxy Hostname level, all connection requests ask for the client certificate. 客户可以为代理配置最多 20 个自定义域(只有高级层才支持)并避开此限制。Customers can configure up to 20 custom domains for Proxy (only supported in the Premium tier) and work around this limitation.

后续步骤Next steps

升级和缩放你的服务Upgrade and scale your service