Configure a custom domain name for your Azure API Management instance

If you already have a private certificate from a third-party provider, you can upload it to your API Management instance. It must meet the following requirements. (If you enable the free certificate managed by API Management, it already meets these requirements.)

• Exported as a PFX file, encrypted using triple DES, and optionally password protected.
• Contains private key at least 2048 bits long
• Contains all intermediate certificates and the root certificate in the certificate chain.

We recommend using Azure Key Vault to manage your certificates and setting them to autorenew.

If you use Azure Key Vault to manage a custom domain TLS certificate, make sure the certificate is inserted into Key Vault as a certificate, not a secret.

To fetch a TLS/SSL certificate, API Management must have the list and get secrets permissions on the Azure Key Vault containing the certificate.

• When you use the Azure portal to import the certificate, all the necessary configuration steps are completed automatically.

• When you use command-line tools or management API, these permissions must be granted manually, in two steps:

  1. On the Managed identities page of your API Management instance, enable a system-assigned or user-assigned managed identity. Note the principal ID on that page.
  2. Assign permissions to the managed identity to access the key vault. Use steps in the following section.

  Configure access to key vault

  1. In the portal, go to your key vault.
  2. In the left menu, select Settings > Access configuration. Note the Permission model that's configured.
  3. Depending on the permission model, configure either a key vault access policy or Azure RBAC access for an API Management managed identity.

  To add a key vault access policy:

  1. In the left menu, select Access policies.
  2. On the Access policies page, select + Create.
  3. On the Permissions tab, under Secret permissions, select Get and List, and then select Next.
  4. On the Principal tab, search for the resource name of your managed identity, then select Next. If you're using a system-assigned identity, the principal is the name of your API Management instance.
  5. Select Next again. On the Review + create tab, select Create.

  To configure Azure RBAC access:

  1. In the left menu, select Access control (IAM).
  2. On the Access control (IAM) page, select Add role assignment.
  3. On the Role tab, select Key Vault Certificate User.
  4. On the Members tab, select Managed identity > + Select members.
  5. In the Select managed identities window, select the system-assigned managed identity or a user-assigned managed identity that's associated with your API Management instance, and then click Select.
  6. Select Review + assign.

If the certificate is set to autorenew and your API Management tier has an SLA (that is, in all tiers except the Developer tier), API Management will pick up the latest version automatically, without downtime to the service.

For more information, see Use managed identities in Azure API Management.

1. Navigate to your API Management instance in the Azure portal.
2. In the left navigation, select Custom domains.
3. Select +Add, or select an existing endpoint that you want to update.
4. In the window on the right, select the Type of endpoint for the custom domain.
5. In the Hostname field, specify the name you want to use. For example, api.contoso.com.
6. Under Certificate, select Custom
7. Select Certificate file to select and upload a certificate.
8. Upload a valid .PFX file and provide its Password, if the certificate is protected with a password.
9. When configuring a Gateway endpoint, select or deselect other options as necessary, including Negotiate client certificate or Default SSL binding.
10. Select Add, or select Update for an existing endpoint.
11. Select Save.

1. Navigate to your API Management instance in the Azure portal.
2. In the left navigation, select Custom domains.
3. Select +Add, or select an existing endpoint that you want to update.
4. In the window on the right, select the Type of endpoint for the custom domain.
5. In the Hostname field, specify the name you want to use. For example, api.contoso.com.
6. Under Certificate, select Key Vault and then Select.
   1. Select the Subscription from the dropdown list.
   2. Select the Key vault from the dropdown list.
   3. Once the certificates have loaded, select the Certificate from the dropdown list. Click Select.
   4. In Client identity, select a system-assigned identity or a user-assigned managed identity enabled in the instance to access the key vault.
7. When configuring a Gateway endpoint, select or deselect other options as necessary, including Negotiate client certificate or Default SSL binding.
8. Select Add, or select Update for an existing endpoint.
9. Select Save.

CNAME record

Configure a CNAME record that points from your custom domain name (for example, api.contoso.com) to your API Management service hostname (for example, yourapim-service-name.azure-api.net). A CNAME record is more stable than an A record in case the IP address changes. For more information, see IP addresses of Azure API Management and the API Management FAQ.

CNAME record

Configure a CNAME record that points from your custom domain name (for example, api.contoso.com) to your API Management service hostname (for example, yourapim-service-name.azure-api.net). A CNAME record is more stable than an A record in case the IP address changes. For more information, see IP addresses of Azure API Management and the API Management FAQ.

TXT record

When enabling the free, managed certificate for API Management, also configure a TXT record in your DNS zone to establish your ownership of the domain name.

• The name of the record is your custom domain name prefixed by apimuid. Example: apimuid.api.contoso.com.
• The value is a domain ownership identifier provided by your API Management instance.

When you use the portal to configure the free, managed certificate for your custom domain, the name and value of the necessary TXT record are automatically displayed.

You can also get a domain ownership identifier by calling the Get Domain Ownership Identifier REST API.

How API Management proxy server responds with SSL certificates in the TLS handshake

When configuring a custom domain for the Gateway endpoint, you can set additional properties that determine how API Management responds with a server certificate, depending on the client request.

Clients calling with Server Name Indication (SNI) header

If you have one or multiple custom domains configured for the Gateway endpoint, API Management can respond to HTTPS requests from either:

• Custom domain (for example, contoso.com)
• Default domain (for example, apim-service-name.azure-api.cn).

Based on the information in the SNI header, API Management responds with the appropriate server certificate.

Clients calling without SNI header

If you are using a client that does not send the SNI header, API Management creates responses based on the following logic:

• If the service has just one custom domain configured for Gateway, the default certificate is the certificate issued to the Gateway's custom domain.

• If the service has configured multiple custom domains for Gateway (supported in the Developer and Premium tier), you can designate the default certificate by setting the defaultSslBinding property to true ("defaultSslBinding":"true"). In the portal, select the Default SSL binding checkbox.

  If you do not set the property, the default certificate is the certificate issued to the default Gateway domain hosted at *.azure-api.cn.

Support for PUT/POST request with large payload

API Management proxy server supports requests with large payloads (>40 KB) when using client-side certificates in HTTPS. To prevent the server's request from freezing, you can set the negotiateClientCertificate property to true ("negotiateClientCertificate": "true") on the Gateway hostname. In the portal, select the Negotiate client certificate checkbox.

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 Gateway hostname level, all connection requests ask for the client certificate. You can work around this limitation and configure up to 20 custom domains for Gateway (only supported in the Premium tier).

Troubleshooting: Hostname certificate rotation from Azure Key Vault failed

Because of a configuration change or connectivity problem, your API Management instance might be unable to fetch a hostname certificate from Azure Key Vault after a certificate is updated or rotated there. When this happens, your API Management instance continues to use a cached certificate until it receives an updated certificate. If the cached certificate expires, runtime traffic to the gateway will be blocked. Any upstream service such as Application Gateway that uses the hostname certificate configuration could also block runtime traffic to the gateway when an expired cached certificate is used.

To mitigate this problem, confirm that the key vault exists, and the certificate is stored in the key vault. If your API Management instance is deployed in a virtual network, confirm outbound connectivity to the AzureKeyVault service tag. Check whether the managed identity used to access the key vault exists. Confirm the managed identity's permissions to access the key vault. Review Set up a custom domain name - Key Vault, earlier in this article, for detailed configuration steps. After the configuration is restored, the hostname certificate will refresh in API Management within 4 hours.

Related content

Upgrade and scale your service