Configure a custom domain name

When you create an Azure API Management service instance, Azure assigns it a subdomain of azure-api.net (for example, apim-service-name.azure-api.net). However, you can expose your API Management endpoints using your own custom domain name, such as contoso.com. This tutorial shows you how to map an existing custom DNS name to endpoints exposed by an 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:

  • An active Azure subscription.

    If you don't have an Azure subscription, create a free account before you begin.

  • An API Management instance. For more information, see Create an Azure API Management instance.

  • A custom domain name that is owned by you or your organization. This topic does not provide instructions on how to procure a custom domain name.

  • A CNAME record hosted on a DNS server that maps the custom domain name to the default domain name of your API Management instance. This topic does not provide instructions on how to host a CNAME record.

  • You must have a valid certificate with a public and private key (.PFX). Subject or subject alternative name (SAN) has to match the domain name (this enables API Management instance to securely expose URLs over SSL).

Use the Azure portal to set a custom domain name

  1. Navigate to your API Management instance in the Azure portal.

  2. Select Custom domains.

    There are a number of endpoints to which you can assign a custom domain name. Currently, the following endpoints are available:

    • Gateway (default is: <apim-service-name>.azure-api.net),
    • Portal (default is: <apim-service-name>.portal.azure-api.net),
    • Management (default is: <apim-service-name>.management.azure-api.net),
    • SCM (default is: <apim-service-name>.scm.azure-api.net).

    Note

    Only the Gateway endpoint in available for configuration in the Consumption tier. You can update all of the endpoints or some of them. Commonly, customers update Gateway (this URL is used to call the API exposed through API Management) and Portal (the developer portal URL). Management and SCM endpoints are used internally by the API Management instance owners only and thus are less frequently assigned a custom domain name. The Premium tier supports setting multiple host names for the Gateway endpoint.

  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. For example, api.contoso.com.
    • In the Certificate, select a certificate from Key Vault. You can also upload a valid .PFX file and provide its Password, if the certificate is protected with a password.

    Note

    Wildcard domain names, e.g. *.contoso.com are supported in all tiers except the Consumption tier.

    Tip

    We recommend using Azure Key Vault for managing certificates and setting them to autorotate. 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.

    To fetch an SSL certificate, API Management must have the list an get secrets permissions on the Azure Key Vault containing the certificate. When using Azure portal all the necessary configuration steps will be completed automatically. When using command line tools or management API, these permissions must be granted manually. This is done in two steps. First, use Managed identities page on your API Management instance to make sure that Managed Identity is enabled and make a note of the principal id shown on that page. Second, give permission list and get secrets permissions to this principal id on the Azure Key Vault containing the certificate.

    If the certificate is set to autorotate, API Management will pick up the latest version automatically without any downtime to the service (if your API Management tier has SLA - i. e. in all tiers except the Developer tier).

  5. Click Apply.

    Note

    The process of assigning the certificate may take 15 minutes or more depending on size of deployment. Developer SKU has downtime, Basic and higher SKUs do not have downtime.

How APIM Proxy Server responds with SSL certificates in the TLS handshake

Clients calling with SNI header

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.net). Based on the information in the Server Name Indication (SNI) header, APIM responds with appropriate server certificate.

Clients calling without SNI header

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. To set the default certificate, the defaultSslBinding property should be set to true ("defaultSslBinding":"true"). If the customer does not set the property, the default certificate is the certificate issued to default Proxy domain hosted at *.azure-api.net.

Support for PUT/POST request with large payload

APIM Proxy server supports request with large payload when using client-side certificates in HTTPS (for example, payload > 40 KB). To prevent the server's request from freezing, customers can set the property "negotiateClientCertificate": "true" on the Proxy hostname. 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. Customers can configure up to 20 custom domains for Proxy (only supported in the Premium tier) and work around this limitation.

DNS configuration

When configuring DNS for your custom domain name, you have two options:

  • Configure a CNAME-record that points to the endpoint of your configured custom domain name.
  • Configure an A-record that points to your API Management gateway IP address.

Note

Although the API Managment instance IP address is static, it may change in a few scenarios. Because of this it's recommended to use CNAME when configuring custom domain. Take that into consideration when choosing DNS configuration method. Read more in the API Mananagement FAQ.

Next steps

Upgrade and scale your service