app-service-web-tutorial-custom-domain.md

title	description	keywords	ms.assetid	ms.topic	ms.date	ms.custom	ms.author	author
Map existing custom DNS name	Learn how to add an existing custom DNS domain name (vanity domain) to a web app, mobile app back end, or API app in Azure App Service.	app service, azure app service, domain mapping, domain name, existing domain, hostname, vanity domain	dc446e0e-0958-48ea-8d99-441d2b947a7c	how-to	08/27/2024	mvc	msangapu	msangapu-msft

Map an existing custom DNS name to Azure App Service

[!INCLUDE regionalization-note]

Azure App Service provides a highly scalable, self-patching web hosting service. This guide 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 App Service.

The DNS record type you need to add with your domain provider depends on the domain you want to add to App Service.

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.

Note

For an end-to-end tutorial that shows you how to configure a www subdomain and a managed certificate, see Tutorial: Secure your Azure App Service app with a custom domain and a managed certificate.

Prerequisites

• 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, not the Free (F1) tier. 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 zones are not supported.
• If you don't have a custom domain yet, you can purchase an App Service domain instead.

Configure a custom domain

1. In the Azure portal, navigate to your app's management page.

2. In the left menu for your app, select Custom domains.

3. Select Add custom domain.

   :::image type="content" source="./media/app-service-web-tutorial-custom-domain/add-custom-domain.png" alt-text="A screenshot showing how to open the Add custom domain dialog." border="true":::

4. For Domain provider, select All other domain services to configure a third-party domain.

   [!NOTE] To configure an App Service domain, see Buy a custom domain name for Azure App Service.

5. For TLS/SSL certificate, select App Service Managed Certificate if your app is in the Basic tier or higher. If you want to remain in the Shared tier, or if you want to use your own certificate, select Add certificate later.

6. For TLS/SSL type, select the binding type you want.

   [!INCLUDE Certificate binding types]

7. For Domain, specify a fully qualified domain name you want based on the domain you own. The Hostname record type box defaults to the recommended DNS record to use, depending on whether the domain is a root domain (like contoso.com), a subdomain (like www.contoso.com), or a wildcard domain (like *.contoso.com).

8. Don't select Validate yet.

9. For each custom domain in App Service, you need two DNS records with your domain provider. The Domain validation section shows you two DNS records that you must add with your domain provider. You can use the copy buttons to copy the value or values that you need in the next section.

   The following screenshot shows the default selections for a www.contoso.com domain. It shows a CNAME record and a TXT record to add.

   :::image type="content" source="./media/app-service-web-tutorial-custom-domain/configure-custom-domain.png" alt-text="A screenshot showing how to configure a new custom domain, along with a managed certificate." border="true":::

   [!WARNING] While it's not absolutely required to add the TXT record, it's highly recommended for security. The TXT record is a domain verification ID that helps avoid subdomain takeovers from other App Service apps. For custom domains you previously configured without this verification ID, you should protect them from the same risk by adding the verification ID (the TXT record) to your DNS configuration. For more information on this common high-severity threat, see Subdomain takeover.

Create the DNS records

[!INCLUDE Access DNS records with domain provider]

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. When your function app is hosted in a Consumption plan, only the CNAME option is supported.

Root domain (for example, contoso.com)

Create two records, as described in the following table:

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

Subdomain (for example, www.contoso.com)

With an A record

Create two records, as described in the following table:

Record type	Host	Value	Comments
A	<subdomain> (for example, www)	IP address shown in the Add custom domain dialog.	The domain mapping itself.
TXT	asuid.<subdomain> (for example, asuid.www)	The domain verification ID shown in the Add custom domain dialog.	App Service accesses the asuid.<subdomain> TXT record to verify your ownership of the custom domain.

With a CNAME record

Create two records, as described in the following table:

Record type	Host	Value	Comments
CNAME	<subdomain> (for example, www)	<app-name>.azurewebsites.net. (See the note at the start of this article.)	The domain mapping itself.
TXT	asuid.<subdomain> (for example, asuid.www)	The domain verification ID shown in the Add custom domain dialog.	App Service accesses the asuid.<subdomain> TXT record to verify your ownership of the custom domain.

Wildcard (CNAME)

For a wildcard name, like * in *.contoso.com, create two records, as described in the following table:

Record type	Host	Value	Comments
CNAME	*	<app-name>.azurewebsites.net. (See the note at the start of this article.)	The domain mapping itself.
TXT	asuid	The domain verification ID shown in the Add custom domain dialog.	App Service accesses the asuid TXT record to verify your ownership of the custom domain.

---

Validate domain ownership and complete the mapping

1. Back in the Add custom domain dialog in the Azure portal, select Validate.

   :::image type="content" source="./media/app-service-web-tutorial-custom-domain/configure-custom-domain-validate.png" alt-text="A screenshot showing how to validate your DNS record settings in the Add a custom domain dialog." border="true":::

2. If the Domain validation section shows green check marks next to both domain records, you've configured them correctly. Select Add. If you see any errors or warnings, resolve them in the DNS record settings on your domain provider's website.

   :::image type="content" source="./media/app-service-web-tutorial-custom-domain/configure-custom-domain-add.png" alt-text="A screenshot showing the Add button activated after validation." border="true":::

   [!NOTE] If you configured the TXT record but not the A or CNAME record, App Service treats the change as a domain migration scenario and allows the validation to succeed, but you won't see green check marks next to the records.

3. You should see the custom domain added to the list. You might also see a red X and the text No binding.

   If you selected App Service Managed Certificate earlier, wait a few minutes for App Service to create the managed certificate for your custom domain. When the process is complete, the red X becomes a green check mark and you see the word Secured. If you selected Add certificate later, the red X will remain until you add a private certificate for the domain and configure the binding.

   :::image type="content" source="./media/app-service-web-tutorial-custom-domain/add-custom-domain-complete.png" alt-text="A screenshot showing the custom domains page with the new secured custom domain." border="true":::

   [!NOTE] Unless you configure a certificate binding for your custom domain, any HTTPS request from a browser to the domain will receive an error or warning, depending on the browser.

Test the DNS resolution

Browse to the DNS names that you configured.

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

• The browser client has cached the old IP address of your domain. Clear the cache and test the DNS resolution again. On a Windows machine, you can clear the cache with ipconfig /flushdns.
• You configured an IP-based certificate binding, and the app's IP address has changed because of it. Remap the A record in your DNS entries to the new IP address.

If you receive a Page not secure warning or error, it's because your domain doesn't have a certificate binding yet. Add a private certificate for the domain and configure the binding.

(Optional) Automate with scripts

[!INCLUDE automate-with-scripts]

Next steps

[!div class="nextstepaction"] Purchase an App Service domain

[!div class="nextstepaction"] Secure a custom DNS name with a TLS/SSL binding in Azure App Service