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.

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.

  • Make sure you can edit DNS records for your custom domain. If you don't have a custom domain yet, you can purchase an App Service domain.

    Note

    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.

2. Prepare the app

To map a custom DNS name to a web app, the web app's App Service plan must be a paid tier (not Free (F1)).

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.

Check the pricing tier

  1. In the left pane of the app page, scroll to the Settings section and select Scale up (App Service plan).

    Screenshot that shows the Scale up (App Service plan) menu.

  2. The app's current tier is highlighted by a blue border. Check to make sure that the app isn't in the F1 tier. Custom DNS isn't supported in the F1 tier.

    Screenshot that shows Recommended pricing tiers.

  3. If the App Service plan isn't in the F1 tier, close the Scale up page and skip to 3. Get a domain verification ID.

Scale up the App Service plan

  1. Select any of the non-free tiers (D1, B1, B2, B3, or any tier in the Production category). For additional options, select See additional options.

  2. Select Apply.

    Screenshot that shows checking the pricing tier.

    When you see the following notification, the scale operation is complete.

    Screenshot that shows the scale operation confirmation.

3. Get a domain verification ID

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.

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

  2. 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.

4. Create the DNS records

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

    Note

    If you like, 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.

    Note

    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.

    Note

    Which record to choose

    • To map the root domain (for example, contoso.com), use an A record. Don't use the CNAME record for the root record (for information, see RFC 1912 Section 2.4).
    • To map a subdomain (for example, www.contoso.com), use a 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.
    • To map a wildcard domain (for example, *.contoso.com), use a CNAME record.

For a subdomain like www in www.contoso.com, create two records according to the following table:

Record type Host Value Comments
CNAME <subdomain> (for example, www) <app-name>.azurewebsites.net The domain mapping itself.
TXT asuid.<subdomain> (for example, asuid.www) The verification ID you got earlier App Service accesses the asuid.<subdomain> TXT record to verify your ownership of the custom domain.

Screenshot that shows the portal navigation to an Azure app.

Note

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

5. 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.

  1. Type the fully qualified domain name that you added a CNAME record for, such as www.contoso.com.

  2. Select Validate. The Add custom domain page appears.

  3. Make sure that Hostname record type is set to CNAME (www.example.com or any subdomain). Select Add custom domain.

    Screenshot that shows the Add custom domain button.

    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 the CNAME 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 that shows a verification error.

6. 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.

Migrate an active domain

To migrate a live site and its DNS domain name to App Service with no downtime, see Migrate an active DNS name to Azure App Service.

Redirect to a custom directory

Note

By default, App Service directs web requests to the root directory of your app code. But certain web frameworks don't start in the root directory. For example, Laravel starts in the public subdirectory. To continue the contoso.com DNS example, such an app is accessible at http://contoso.com/public, but you typically want to direct http://contoso.com to the public directory instead.

While this is a common scenario, it doesn't actually involve custom DNS mapping, but is about customizing the virtual directory within your app.

  1. Select Application settings in the left pane of your web app page.

  2. At the bottom of the page, the root virtual directory / points to site\wwwroot by default, which is the root directory of your app code. Change it to point to the site\wwwroot\public instead, for example, and save your changes.

    Screenshot that shows customizing a virtual directory.

  3. After the operation finishes, verify by navigating to your app's root path in the browser (for example, http://contoso.com or http://<app-name>.azurewebsites.net).

Automate with scripts

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

Azure CLI

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.

Azure PowerShell

Note

This article uses the Azure Az PowerShell module, which is the recommended PowerShell module for interacting with Azure. To get started with the Az PowerShell module, see Install Azure PowerShell. To learn how to migrate to the Az PowerShell module, see Migrate Azure PowerShell from AzureRM to Az.

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

Set-AzWebApp `
    -Name <app-name> `
    -ResourceGroupName <resource_group_name> ` 
    -HostNames @("<fully_qualified_domain_name>","<app-name>.azurewebsites.net")

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

Next steps

Continue to the next tutorial to learn how to bind a custom TLS/SSL certificate to a web app.

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