Tutorial: Map an existing custom DNS name to Azure App Service
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:
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 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
www.contoso.com, you must be able to configure the DNS settings for the
- 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
Search for and select App Services.
On the App Services page, select the name of your 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.
In the left pane of your app page, select Custom domains.
Copy the ID in the Custom Domain Verification ID box in the Custom Domains page for the next step.
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.
(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.
3. Create the DNS records
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.
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:
Select Add or the appropriate widget to create a record.
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.|
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).
The verification ID you got earlier For root domain, App Service accesses
asuidTXT record to verify your ownership of the custom domain
To map a subdomain like
www.contoso.comwith 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
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.
In the left pane of the app page in the Azure portal, select Custom domains.
Select Add custom domain.
Type the fully qualified domain name that you configured the A record for, such as
Select Validate. The Add custom domain page is shown.
Make sure that Hostname record type is set to A record (example.com). Select Add custom domain.
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.
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.
5. Test in a browser
Browse to the DNS names that you configured earlier.
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
(Optional) Automate with scripts
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.