Edit

Tutorial: Map an existing custom DNS name to Azure App Service

  • Article
  • 8 minutes to read

Azure App Service provides a highly scalable, self-patching web hosting service. This tutorial shows you how to map an existing custom Domain Name System (DNS) name to App Service. To migrate a live site and its DNS domain name to App Service with no downtime, see Migrate an active DNS name to Azure.

In this tutorial, you learn how to:

  • Map a subdomain by using a CNAME record.
  • Map a root domain by using an A record.
  • Map a wildcard domain by using a CNAME record.
  • Redirect the default URL to a custom directory.

1. Prepare your environment

  • Create an App Service app, or use an app that you created for another tutorial. The web app's App Service plan must be a paid tier and not Free (F1). See Scale up an app to update the tier.
  • Make sure you can edit the DNS records for your custom domain. To edit DNS records, you need access to the DNS registry for your domain provider, such as GoDaddy. For example, to add DNS entries for contoso.com and www.contoso.com, you must be able to configure the DNS settings for the contoso.com root domain. Your custom domains must be in a public DNS zone; private DNS zone is only supported on Internal Load Balancer (ILB) App Service Environment (ASE).
  • If you don't have a custom domain yet, you can purchase an App Service domain.

2. Get a domain verification ID

Sign in to Azure

Open the Azure portal, and sign in with your Azure account.

Select the app in the Azure portal

  1. Search for and select App Services.

    Screenshot that shows selecting App Services.

  2. On the App Services page, select the name of your Azure app.

    Screenshot showing portal navigation to an Azure app.

    You see the management page of the App Service app.

    To add a custom domain to your app, you need to verify your ownership of the domain by adding a verification ID as a TXT record with your domain provider.

  3. In the left pane of your app page, select Custom domains.

  4. Copy the ID in the Custom Domain Verification ID box in the Custom Domains page for the next step.

    Screenshot that shows the ID in the Custom Domain Verification ID box.

    Warning

    Adding domain verification IDs to your custom domain can prevent dangling DNS entries and help to avoid subdomain takeovers. For custom domains you previously configured without this verification ID, you should protect them from the same risk by adding the verification ID to your DNS record. For more information on this common high-severity threat, see Subdomain takeover.

  1. (A record only) To map an A record, you need the app's external IP address. In the Custom domains page, copy the value of IP address.

    Screenshot that shows portal navigation to an Azure app.

3. Create the DNS records

  1. Sign in to the website of your domain provider.

    You can use Azure DNS to manage DNS records for your domain and configure a custom DNS name for Azure App Service. For more information, see Tutorial: Host your domain in Azure DNS.

  2. Find the page for managing DNS records.

    Every domain provider has its own DNS records interface, so consult the provider's documentation. Look for areas of the site labeled Domain Name, DNS, or Name Server Management.

    Often, you can find the DNS records page by viewing your account information and then looking for a link such as My domains. Go to that page, and then look for a link that's named something like Zone file, DNS Records, or Advanced configuration.

    The following screenshot is an example of a DNS records page:

    Screenshot that shows an example DNS records page.

  3. Select Add or the appropriate widget to create a record.

  4. Select the type of record to create and follow the instructions. You can use either a CNAME record or an A record to map a custom DNS name to App Service.

DNS record types

Scenario Example Recommended DNS record
Root domain contoso.com A record. Don't use the CNAME record for the root record (for information, see RFC 1912 Section 2.4).
Subdomain www.contoso.com, my.contoso.com CNAME record. You can map a subdomain to the app's IP address directly with an A record, but it's possible for the IP address to change. The CNAME maps to the app's default hostname instead, which is less susceptible to change.
Wildcard *.contoso.com CNAME record.

  • For a root domain like contoso.com, create two records according to the following table:

    Record type Host Value Comments
    A @ IP address from Copy the app's IP address The domain mapping itself (@ typically represents the root domain).
    TXT asuid The verification ID you got earlier For root domain, App Service accesses asuid TXT record to verify your ownership of the custom domain

    Screenshot that shows a DNS records page.

  • To map a subdomain like www.contoso.com with an A record instead of a recommended CNAME record, your A record and TXT record should look like the following table instead:

    Record type Host Value Comments
    A <subdomain> (for example, www) IP address from Copy the app's IP address
    TXT asuid.<subdomain> (for example, asuid.www) The verification ID you got earlier

    Screenshot that shows a DNS records subdomain page.

Note

For certain providers, such as GoDaddy, changes to DNS records don't become effective until you select a separate Save Changes link.

4. Enable the mapping in your app

After you create DNS records, you enable the mapping in your app.

  1. In the left pane of the app page in the Azure portal, select Custom domains.

    Screenshot that shows the Custom domains menu.

  2. Select Add custom domain.

    Screenshot that shows the Add host name item.

  3. Type the fully qualified domain name that you configured the A record for, such as contoso.com.

  4. Select Validate. The Add custom domain page is shown.

  5. Make sure that Hostname record type is set to A record (example.com). Select Add custom domain.

    Screenshot that shows adding a DNS name to the app.

    It might take some time for the new custom domain to be reflected in the app's Custom Domains page. Refresh the browser to update the data.

    Screenshot that shows adding an A record.

    Note

    A warning label for your custom domain means that it's not yet bound to a TLS/SSL certificate. Any HTTPS request from a browser to your custom domain will receive an error or warning, depending on the browser. To add a TLS binding, see Secure a custom DNS name with a TLS/SSL binding in Azure App Service.

    If you missed a step or made a typo somewhere earlier, a verification error appears at the bottom of the page.

    Screenshot showing a verification error.

5. Test in a browser

Browse to the DNS names that you configured earlier.

Screenshot that shows navigation to an Azure app.

If you receive an HTTP 404 (Not Found) error when you browse to the URL of your custom domain, the two most common causes are:

  • The custom domain configured is missing an A record or a CNAME record. You may have deleted the DNS record after you've enabled the mapping in your app. Check if the DNS records are properly configured using an online DNS lookup tool.
  • The browser client has cached the old IP address of your domain. Clear the cache, and test DNS resolution again. On a Windows machine, you clear the cache with ipconfig /flushdns.

(Optional) Automate with scripts

You can automate management of custom domains with scripts by using the Azure CLI or Azure PowerShell.

The following command adds a configured custom DNS name to an App Service app.

az webapp config hostname add \
    --webapp-name <app-name> \
    --resource-group <resource_group_name> \
    --hostname <fully_qualified_domain_name>

For more information, see Map a custom domain to a web app.

Next steps

Secure a custom DNS name with a TLS/SSL binding in Azure App Service