Configure a custom domain name for your Azure API Management instance

When you create an Azure API Management service instance in the Azure cloud, Azure assigns it a azure-api.net subdomain (for example, apim-service-name.azure-api.net). You can also expose your API Management endpoints using your own custom domain name, such as contoso.com. This article shows you how to map an existing custom DNS name to endpoints exposed by an API Management instance.

Important

API Management only accepts requests with host header values matching:

  • The Gateway's default domain name
  • Any of the Gateway's configured custom domain names

Prerequisites

  • 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 article does not provide instructions on how to procure a custom domain name.

  • Optionally, a valid certificate with a public and private key (.PFX). The subject or subject alternative name (SAN) has to match the domain name (this enables API Management instance to securely expose URLs over TLS).

    See Domain certificate options.

  • DNS records hosted on a DNS server to map the custom domain name to the default domain name of your API Management instance. This topic does not provide instructions on how to host the DNS records.

    For more information about required records, see DNS configuration, later in this article.

Endpoints for custom domains

There are several API Management endpoints to which you can assign a custom domain name. Currently, the following endpoints are available:

Endpoint Default
Gateway Default is: <apim-service-name>.azure-api.net. Gateway is the only endpoint available for configuration in the Consumption tier.

The default Gateway endpoint configuration remains available after a custom Gateway domain is added.
Developer portal Default is: <apim-service-name>.developer.azure-api.net
Management Default is: <apim-service-name>.management.azure-api.net
Configuration API (v2) Default is: <apim-service-name>.configuration.azure-api.net
SCM Default is: <apim-service-name>.scm.azure-api.net

Considerations

  • You can update any of the endpoints supported in your service tier. Typically, customers update Gateway (this URL is used to call the APIs exposed through API Management) and Developer portal (the developer portal URL).
  • The default Gateway endpoint remains available after you configure a custom Gateway domain name and cannot be deleted. For other API Management endpoints (such as Developer portal) that you configure with a custom domain name, the default endpoint is no longer available.
  • Only API Management instance owners can use Management and SCM endpoints internally. These endpoints are less frequently assigned a custom domain name.
  • The Premium and Developer tiers support setting multiple hostnames for the Gateway endpoint.
  • Wildcard domain names, like *.contoso.com, are supported in all tiers except the Consumption tier. A specific subdomain certificate (for example, api.contoso.com) would take precedence over a wildcard certificate (*.contoso.com) for requests to api.contoso.com.

Domain certificate options

API Management supports custom TLS certificates or certificates imported from Azure Key Vault. You can also enable a free, managed certificate.

Warning

If you require certificate pinning, please use a custom domain name and either a custom or Key Vault certificate, not the default certificate or the free, managed certificate. We don't recommend taking a hard dependency on a certificate that you don't manage.

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.

Set a custom domain name - portal

Choose the steps according to the domain certificate you want to use.

  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. Configure gateway domain with custom certificate
  10. Select Add, or select Update for an existing endpoint.
  11. Select Save.

DNS configuration

  • Configure a CNAME record for your custom domain.
  • When using API Management's free, managed certificate, also configure a TXT record to establish your ownership of the domain.

Note

The free certificate is issued by DigiCert. For some domains, you must explicitly allow DigiCert as a certificate issuer by creating a CAA domain record with the value: 0 issue digicert.com.

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, <apim-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.

Note

Some domain registrars only allow you to map subdomains when using a CNAME record, such as www.contoso.com, and not root names, such as contoso.com. For more information on CNAME records, see the documentation provided by your registrar or IETF Domain Names - Implementation and Specification.

Caution

When you use the free, managed certificate and configure a CNAME record with your DNS provider, make sure that it resolves to the default API Management service hostname (<apim-service-name>.azure-api.net). Currently, API Management doesn't automatically renew the certificate if the CNAME record doesn't resolve to the default API Management hostname. For example, if you're using the free, managed certificate and you use Cloudflare as your DNS provider, make sure that DNS proxy isn't enabled on the CNAME record.

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.net).

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.net.

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).

Next steps

Upgrade and scale your service