Setting up a custom domain name for your Azure API Management instance

Configuring a custom domain name for your Azure API Management (APIM) instance is a common requirement for branding, security, and compliance purposes. Below are the steps to configure a custom domain name for your Azure API Management instance:

Prerequisites

1. Azure API Management Instance: Ensure you have an existing APIM instance.
2. Custom Domain Name: Purchase a domain name from a domain registrar (e.g., GoDaddy, Namecheap) or use an existing one.
3. SSL/TLS Certificate: Obtain an SSL/TLS certificate for your custom domain. You can use a certificate from a trusted Certificate Authority (CA) or use Azure Key Vault to manage your certificates.
4. Access to DNS Management: You need access to your DNS provider to create the necessary DNS records.

Steps to Configure a Custom Domain Name

1. Add a Custom Domain in Azure API Management

1. Log in to the Azure Portal:
   • Go to the Azure Portal.
2. Navigate to Your API Management Instance:
   • Search for and select your API Management instance.
3. Go to Custom Domains:
   • In the left-hand menu, under the Deployment + Infrastructure section, select Custom domains.
4. Add a Custom Domain:
   • Click + Add to add a new custom domain.
5. Configure the Domain:
   • Domain type: Select the type of domain you want to configure (e.g., Gateway, Portal, Management, or SCM).
   • Hostname: Enter your custom domain name (e.g., api.example.com).
   • Certificate: Upload your SSL/TLS certificate or select a certificate from Azure Key Vault.
     • If uploading, provide the certificate file and private key.
     • If using Azure Key Vault, ensure you have the correct permissions to access the certificate.
6. Save the Configuration:
   • Click Save to apply the changes.

2. Update DNS Records

1. Get the APIM Gateway IP Address:
   • In the Azure Portal, go to your API Management instance.
   • Under the Overview section, note the Gateway URL (e.g., myapim.azure-api.net).
2. Create a CNAME Record:
   • Log in to your DNS provider’s management console.
   • Create a CNAME record pointing your custom domain (e.g., api.example.com) to the APIM Gateway URL (e.g., myapim.azure-api.net).
     • Name: api (or the subdomain you want to use).
     • Value: myapim.azure-api.net.
     • TTL: Set to the default or a low value (e.g., 3600 seconds).
3. Verify DNS Propagation:
   • Use a tool like DNS Checker to verify that the CNAME record has propagated.

3. Test the Custom Domain

1. Access the API via Custom Domain:
   • Open a browser or use a tool like Postman to access your API using the custom domain (e.g., https://api.example.com).
2. Verify SSL/TLS:
   • Ensure the connection is secure and the SSL/TLS certificate is valid.

Optional: Configure Multiple Custom Domains

You can configure multiple custom domains for different endpoints (e.g., Gateway, Developer Portal, Management API). Repeat the steps above for each domain.

Example: Configuring a Custom Domain for the Gateway

1. Add a Custom Domain:
   • Domain type: Gateway.
   • Hostname: api.example.com.
   • Certificate: Upload or select from Azure Key Vault.
2. Create a CNAME Record:
   • Name: api.
   • Value: myapim.azure-api.net.
3. Test:
   • Access https://api.example.com to verify the configuration.

Troubleshooting

• DNS Propagation Delays: DNS changes can take up to 24 hours to propagate globally.
• SSL/TLS Errors: Ensure the certificate is valid and matches the domain name.
• CNAME Conflicts: Ensure there are no conflicting CNAME records in your DNS configuration.

By following these steps, you can successfully configure a custom domain name for your Azure API Management instance.