Map a custom domain to Azure App Service

This article explains how to map a custom domain name (like www.contoso.com) to your Azure App Service. This allows users to access your web app using a domain name they are familiar with, rather than the default .azurewebsites.net domain.

Prerequisites

• An Azure subscription.
• An Azure App Service that is already deployed.
• A custom domain name registered with a domain registrar.
• Access to your domain's DNS records configuration.

Steps to Map a Custom Domain

1. Add the Custom Domain in Azure App Service

Navigate to your App Service resource in the Azure portal. In the left-hand menu, under Settings, select Custom domains.

Click on Add custom domain.

2. Validate Domain Ownership

Azure needs to verify that you own the custom domain you are trying to add. This is typically done using DNS records.

• Hostname Record (CNAME or A record): You will need to create a DNS record with your domain registrar that points your custom domain to your App Service. Azure will provide the specific values you need.
  • For www subdomains (e.g., www.contoso.com): Create a CNAME record pointing from www to your App Service's default hostname (e.g., yourapp.azurewebsites.net).
  • For root domains (e.g., contoso.com): You'll typically use an A record pointing to your App Service's external IP address, and a TXT record for verification. Azure will provide both the IP address and the TXT record value.
• Domain Verification ID: Azure also requires a specific TXT record (often called asuid.yourdomain.com) to verify ownership. The value will be your App Service's "Custom Domain Verification ID" found in the portal.

Example DNS Configuration (for www.contoso.com):

;; Record Type: CNAME
;; Host/Name: www
;; Value/Target: yourapp.azurewebsites.net

;; Record Type: TXT
;; Host/Name: asuid.www
;; Value/Target: YOUR_CUSTOM_DOMAIN_VERIFICATION_ID
            

Note: DNS propagation can take some time. If validation fails initially, wait a few minutes and try again. You can use online DNS lookup tools to check if your records have propagated.

3. Complete the Custom Domain Mapping

Once your DNS records have propagated and Azure can verify ownership, return to the Add custom domain panel in the Azure portal. Enter your full custom domain name (e.g., www.contoso.com) and click Validate.

If validation is successful, you will see green checkmarks next to the DNS record requirements. Click Add custom domain to finalize the mapping.

Binding SSL Certificates

After mapping your custom domain, it's crucial to secure it with an SSL/TLS certificate to enable HTTPS. This is a separate step:

1. In the Custom domains blade, find your newly added custom domain.
2. Click Add binding next to your custom domain.
3. Choose your SSL certificate (either uploaded, purchased from Azure, or imported from Key Vault) and the SSL type (SNI SSL or IP SSL). SNI SSL is generally recommended and supported by most modern browsers.
4. Click Add Binding.

Tip: For free SSL certificates, consider using the App Service Managed Certificates feature, which automatically provisions and renews certificates for your custom domains.

Troubleshooting

• DNS Propagation Delays: Allow ample time for DNS changes to propagate globally.
• Incorrect DNS Records: Double-check the hostnames, record types, and values entered in your DNS configuration. Ensure there are no typos.
• App Service Plan Tier: Ensure your App Service plan is running on a tier that supports custom domains (e.g., Basic, Standard, Premium, Isolated). The Free and Shared tiers do not support custom domains.
• Verification ID Mismatch: The TXT record value (Custom Domain Verification ID) must exactly match what's shown in the Azure portal.

By following these steps, you can successfully map a custom domain to your Azure App Service, providing a professional and branded experience for your users.