Configure a custom domain name for a self-hosted gateway

Availability

Important

This feature is available in the Premium and Developer tiers of API Management.

When you provision a self-hosted Azure API Management gateway, it isn't assigned a host name and must be referenced by its IP address. This article shows how to map an existing custom DNS name (also referred to as hostname) to a self-hosted gateway.

Prerequisites

  • An active Azure subscription.

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

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

  • A self-hosted gateway. For more information, see How to provision self-hosted gateway.

  • A custom domain name that's owned by you or your organization. This article doesn't provide instructions on how to procure a custom domain name.

  • A DNS record hosted on a DNS server that maps the custom domain name to the self-hosted gateway's IP address. This article doesn't provide instructions on how to host a DNS record.

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

Go to your API Management instance

  1. In the Azure portal, search for and select API Management services.

    Select API Management services

  2. On the API Management services page, select your API Management instance.

    Select your API Management instance

Add a custom domain certificate

Add a custom domain certificate (.PFX) file to your API Management instance, or reference a certificate stored in Azure Key Vault. Follow the steps in Secure backend services by using client certificate authentication in Azure API Management.

Note

We recommend using a key vault certificate for the self-hosted gateway domain.

Set a custom domain name for your self-hosted gateway

  1. In the Azure portal, select Deployment + infrastructure from the sidebar menu.
  2. Select Self-hosted gateways, then choose the self-hosted gateway you want to configure the domain name for.
  3. Under Settings, select Hostnames.
  4. Select + Add.
  5. Enter a resource name for the hostname into the Name field.
  6. Enter domain name in the Hostname field.
  7. Select a certificate from the Certificate dropdown.
  8. Select Negotiate client certificate checkbox if any of the APIs exposed via this gateway use client certificate authentication.

    Warning

    This setting is shared by all domain names configured for the gateway.

  9. Select Add to assign the custom domain name to the selected self-hosted gateway.

Note

If clients connecting to the self-hosted gateway using the custom domain expect to be presented with all intermediate certificates in the chain, you must upload individual CA certificates to your API Management Service and associate them with the self-hosted gateway. For instructions on how to achieve this, see Create custom CA for self-hosted gateway.

Related content