We use cookies to improve your experience on our websites and for advertising. Privacy Statement Accept all Manage cookies Docs Documentation Learn Q&A Code Samples Shows Events Search Sign in Azure Product documentation Architecture Learn Azure Develop Resources Portal Free account Azure App Service Web Apps Save Feedback Edit Share Search App Service Documentation Overview Quickstarts ASP.NET Node.js PHP Java Python Ruby Static HTML site ARM template Custom container Multi-container app App on Azure Arc (preview) Tutorials Map custom domain Secure domain with TLS/SSL App with DB Custom containers Secretless back end connectivity Authenticate users Secure app accesses storage, and Microsoft Graph Isolate network traffic Host a RESTful API Add CDN Send email/tweet Troubleshoot errors GitHub Actions Samples Concepts How-To guides Reference Resources Download PDF Retiring Tutorial: Map an existing custom DNS name to Azure App Service 11/02/2021 9 minutes to read +17 Is this page helpful? In this article 1. Prepare your environment 2. Prepare the app 3. Get a domain verification ID 4. Create the DNS records 5. Enable the mapping in your app 6. Test in a browser Migrate an active domain Redirect to a custom directory Automate with scripts Next steps 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 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. Check the pricing tier In the left pane of the app page, scroll to the Settings section and select Scale up (App Service plan). 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. 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 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. Select Apply. When you see the following notification, the scale operation is complete. 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. 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. 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. (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. 4. Create the DNS records 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. 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: Select Add or the appropriate widget to create a record. 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. CNAME A Wildcard (CNAME) For a subdomain like www in www.contoso.com, create two records according to the following table: TABLE 1 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. 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 In the left pane of the app page in the Azure portal, select Custom domains. Select Add custom domain. CNAME A Wildcard (CNAME) Type the fully qualified domain name that you added a CNAME record for, such as www.contoso.com. Select Validate. The Add custom domain page appears. Make sure that Hostname record type is set to CNAME (www.example.com or any subdomain). 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. 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. 6. 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 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. Select Application settings in the left pane of your web app page. 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. 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. Azure CLI Copy 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. PowerShell Copy 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 Feedback Submit and view feedback for This product This page View all page feedback English (United States) Theme Manage cookies Previous Version Docs Blog Contribute Privacy & Cookies Terms of Use Trademarks © Microsoft 2021