custom-domain.md

title	titleSuffix	description	services	author	manager	ms.service	ms.workload	ms.topic	ms.date	ms.author	ms.subservice	zone_pivot_groups
Enable Azure AD B2C custom domains	Azure AD B2C	Learn how to enable custom domains in your redirect URLs for Azure Active Directory B2C.	active-directory-b2c	msmimart	celestedg	active-directory	identity	how-to	08/16/2021	mimart	B2C	b2c-policy-type

Enable custom domains for Azure Active Directory B2C

[!INCLUDE active-directory-b2c-choose-user-flow-or-custom-policy]

[!INCLUDE b2c-public-preview-feature]

This article describes how to enable custom domains in your redirect URLs for Azure Active Directory B2C (Azure AD B2C). Using a custom domain with your application provides a more seamless user experience. From the user's perspective, they remain in your domain during the sign-in process rather than redirecting to the Azure AD B2C default domain <tenant-name>.b2clogin.com.

Custom domain overview

You can enable custom domains for Azure AD B2C by using Azure Front Door. Azure Front Door is a global entry point that uses the Microsoft global edge network to create fast, secure, and widely scalable web applications. You can render Azure AD B2C content behind Azure Front Door, and then configure an option in Azure Front Door to deliver the content via a custom domain in your application's URL.

The following diagram illustrates Azure Front Door integration:

1. From an application, a user selects the sign-in button, which takes them to the Azure AD B2C sign-in page. This page specifies a custom domain name.
2. The web browser resolves the custom domain name to the Azure Front Door IP address. During DNS resolution, a canonical name (CNAME) record with a custom domain name points to your Front Door default front-end host (for example, contoso.azurefd.net).
3. The traffic addressed to the custom domain (for example, login.contoso.com) is routed to the specified Front Door default front-end host (contoso.azurefd.net).
4. Azure Front Door invokes Azure AD B2C content using the Azure AD B2C <tenant-name>.b2clogin.com default domain. The request to the Azure AD B2C endpoint includes the original custom domain name.
5. Azure AD B2C responds to the request by displaying the relevant content and the original custom domain.

Important

The connection from the browser to Azure Front Door should always use IPv4 instead of IPv6.

When using custom domains, consider the following:

• You can set up multiple custom domains. For the maximum number of supported custom domains, see Azure AD service limits and restrictions for Azure AD B2C and Azure subscription and service limits, quotas, and constraints for Azure Front Door.
• Azure Front Door is a separate Azure service, so extra charges will be incurred. For more information, see Front Door pricing.
• To use Azure Front Door Web Application Firewall, you need to confirm your firewall configuration and rules work correctly with your Azure AD B2C user flows.
• After you configure custom domains, users will still be able to access the Azure AD B2C default domain name <tenant-name>.b2clogin.com (unless you're using a custom policy and you block access.
• If you have multiple applications, migrate them all to the custom domain because the browser stores the Azure AD B2C session under the domain name currently being used.

Prerequisites

[!INCLUDE active-directory-b2c-customization-prerequisites]

Step 1. Add a custom domain name to your Azure AD B2C tenant

Every new Azure AD B2C tenant comes with an initial domain name, <domainname>.onmicrosoft.com. You can't change or delete the initial domain name, but you can add a custom domain.

Follow these steps to add a custom domain to your Azure AD B2C tenant:

1. Add your custom domain name to Azure AD.

   [!IMPORTANT] For these steps, be sure to sign in to your Azure AD B2C tenant and select the Azure Active Directory service.

2. Add your DNS information to the domain registrar. After you add your custom domain name to Azure AD, create a DNS TXT, or MX record for your domain. Creating this DNS record for your domain verifies ownership of your domain name.

   The following examples demonstrate TXT records for login.contoso.com and account.contoso.com:

   Name (hostname)	Type	Data
   login	TXT	MS=ms12345678
   account	TXT	MS=ms87654321

   The TXT record must be associated with the subdomain, or hostname of the domain. For example, the login part of the contoso.com domain. If the hostname is empty or @, Azure AD will not be able to verify the custom domain you added. In the following examples, both records are configured incorrectly.

   Name (hostname)	Type	Data
   	TXT	MS=ms12345678
   @	TXT	MS=ms12345678

   [!TIP] You can manage your custom domain with any publicly available DNS service, such as GoDaddy. If you don't have a DNS server, you can use Azure DNS zone, or App Service domains.

3. Verify your custom domain name. Verify each subdomain, or hostname you plan to use. For example, to be able to sign-in with login.contoso.com and account.contoso.com, you need to verify both subdomains and not the top-level domain contoso.com.

   After the domain is verified, delete the DNS TXT record you created.

Step 2. Create a new Azure Front Door instance

Follow these steps to create a Front Door for your Azure AD B2C tenant. For more information, see creating a Front Door for your application.

1. Sign in to the Azure portal.

2. Select Directory + subscription and choose the directory that contains the Azure subscription you’d like to use for Azure Front Door. The directory should not be the directory containing your Azure AD B2C tenant.

3. From the home page or the Azure menu, select Create a resource. Select Networking > See All > Front Door.

4. In the Basics tab of Create a Front Door page, enter or select the following information, and then select Next: Configuration.

   Setting	Value
   Subscription	Select your Azure subscription.
   Resource group	Select an existing resource group, or select Create new to create a new one.
   Resource group location	Select the location of the resource group. For example, Central US.

2.1 Add frontend host

The frontend host is the domain name used by your application. When you create a Front Door, the default frontend host is a subdomain of azurefd.net.

Azure Front Door provides the option of associating a custom domain with the frontend host. With this option, you associate the Azure AD B2C user interface with a custom domain in your URL instead of a Front Door owned domain name. For example, https://login.contoso.com.

To add a frontend host, follow these steps:

1. In Frontends/domains, select + to open Add a frontend host.

2. For Host name, enter a globally unique hostname. The host name is not your custom domain. This example uses contoso-frontend. Select Add.

   

2.2 Add backend and backend pool

A backend refers to your Azure AD B2C tenant name, tenant-name.b2clogin.com. To add a backend pool, follow these steps:

1. Still in Create a Front Door, in Backend pools, select + to open Add a backend pool.

2. Enter a Name. For example, myBackendPool. Select Add a backend.

   The following screenshot demonstrates how to create a backend pool:

   

3. In the Add a backend blade, select the following information, and then select Add.

   Setting	Value
   Backend host type	Select Custom host.
   Backend host name	Select the name of your Azure AD B2C, <tenant-name>.b2clogin.com. For example, contoso.b2clogin.com.
   Backend host header	Select the same value you selected for Backend host name.

   *Leave all other fields default.

   The following screenshot demonstrates how to create a custom host backend that is associated with an Azure AD B2C tenant:

   

4. To complete the configuration of the backend pool, on the Add a backend pool blade, select Add.

5. After you add the backend to the backend pool, disable the Health probes.

   

2.3 Add a routing rule

Finally, add a routing rule. The routing rule maps your frontend host to the backend pool. The rule forwards a request for the frontend host to the Azure AD B2C backend. To add a routing rule, follow these steps:

1. In Add a rule, for Name, enter LocationRule. Accept all the default values, then select Add to add the routing rule.

2. Select Review + Create, and then Create.

   

Step 3. Set up your custom domain on Azure Front Door

In this step, you add the custom domain you registered in Step 1 to your Front Door.

3.1 Create a CNAME DNS record

Before you can use a custom domain with your Front Door, you must first create a canonical name (CNAME) record with your domain provider to point to your Front Door's default frontend host (say contoso.azurefd.net).

A CNAME record is a type of DNS record that maps a source domain name to a destination domain name (alias). For Azure Front Door, the source domain name is your custom domain name, and the destination domain name is your Front Door default hostname you configure in step 2.1.

After Front Door verifies the CNAME record that you created, traffic addressed to the source custom domain (such as login.contoso.com) is routed to the specified destination Front Door default frontend host, such as contoso.azurefd.net. For more information, see add a custom domain to your Front Door.

To create a CNAME record for your custom domain:

1. Sign in to the web site of the domain provider for your custom domain.

2. Find the page for managing DNS records by consulting the provider's documentation or searching for areas of the web site labeled Domain Name, DNS, or Name Server Management.

3. Create a CNAME record entry for your custom domain and complete the fields as shown in the following table (field names may vary):

   Source	Type	Destination
   <login.contoso.com>	CNAME	contoso.azurefd.net

   • Source: Enter your custom domain name (for example, login.contoso.com).

   • Type: Enter CNAME.

   • Destination: Enter your default Front Door frontend host you create in step 2.1. It must be in the following format:<hostname>.azurefd.net. For example, contoso.azurefd.net.

4. Save your changes.

3.2 Associate the custom domain with your Front Door

After you've registered your custom domain, you can then add it to your Front Door.

1. On the Front Door designer page, under the Frontends/domains, select + to add a custom domain.

   

2. For Frontend host, the frontend host to use as the destination domain of your CNAME record is pre-filled and is derived from your Front Door: <default hostname>.azurefd.net. It cannot be changed.

3. For Custom hostname, enter your custom domain, including the subdomain, to use as the source domain of your CNAME record. For example, login.contoso.com.

   

   Azure verifies that the CNAME record exists for the custom domain name you entered. If the CNAME is correct, your custom domain will be validated.

4. After the custom domain name is verified, under the Custom domain name HTTPS, select Enabled.

   

5. For the Certificate management type, select Front Door management, or Use my own certificate. If you choose the Front Door managed option, wait until the certificate is fully provisioned.

6. Select Add.

3.3 Update the routing rule

1. In the Routing rules, select the routing rule you created in step 2.3.

   

2. Under the Frontends/domains, select your custom domain name.

   

3. Select Update.

4. From the main window, select Save.

Step 4. Configure CORS

If you customize the Azure AD B2C user interface with an HTML template, you need to Configure CORS with your custom domain.

Configure Azure Blob storage for Cross-Origin Resource Sharing with the following steps:

1. In the Azure portal, navigate to your storage account.
2. In the menu, select CORS.
3. For Allowed origins, enter https://your-domain-name. Replace your-domain-name with your domain name. For example, https://login.contoso.com. Use all lowercase letters when entering your tenant name.
4. For Allowed Methods, select both GET and OPTIONS.
5. For Allowed Headers, enter an asterisk (*).
6. For Exposed Headers, enter an asterisk (*).
7. For Max age, enter 200.
8. Select Save.

Test your custom domain

1. Sign in to the Azure portal.

2. Select the Directory + subscription filter in the top menu, and then select the directory that contains your Azure AD B2C tenant.

3. In the Azure portal, search for and select Azure AD B2C.

4. Under Policies, select User flows (policies).

5. Select a user flow, and then select Run user flow.

6. For Application, select the web application named webapp1 that you previously registered. The Reply URL should show https://jwt.ms.

7. Copy the URL under Run user flow endpoint.

   

8. To simulate a sign-in with your custom domain, open a web browser and use the URL you copied. Replace the Azure AD B2C domain (<tenant-name>.b2clogin.com) with your custom domain.

   For example, instead of:

   https://contoso.b2clogin.com/contoso.onmicrosoft.com/oauth2/v2.0/authorize?p=B2C_1_susi&client_id=63ba0d17-c4ba-47fd-89e9-31b3c2734339&nonce=defaultNonce&redirect_uri=https%3A%2F%2Fjwt.ms&scope=openid&response_type=id_token&prompt=login

   use:

   https://login.contoso.com/contoso.onmicrosoft.com/oauth2/v2.0/authorize?p=B2C_1_susi&client_id=63ba0d17-c4ba-47fd-89e9-31b3c2734339&nonce=defaultNonce&redirect_uri=https%3A%2F%2Fjwt.ms&scope=openid&response_type=id_token&prompt=login    

9. Verify that the Azure AD B2C is loaded correctly. Then, sign-in with a local account.

10. Repeat the test with the rest of your policies.

Configure your identity provider

When a user chooses to sign in with a social identity provider, Azure AD B2C initiates an authorization request and takes the user to the selected identity provider to complete the sign-in process. The authorization request specifies the redirect_uri with the Azure AD B2C default domain name:

https://<tenant-name>.b2clogin.com/<tenant-name>/oauth2/authresp

If you configured your policy to allow sign-in with an external identity provider, update the OAuth redirect URIs with the custom domain. Most identity providers allow you to register multiple redirect URIs. We recommend adding redirect URIs instead of replacing them so you can test your custom policy without affecting applications that use the Azure AD B2C default domain name.

In the following redirect URI:

https://<custom-domain-name>/<tenant-name>/oauth2/authresp

• Replace <custom-domain-name> with your custom domain name.
• Replace <tenant-name> with the name of your tenant, or your tenant ID.

The following example shows a valid OAuth redirect URI:

https://login.contoso.com/contoso.onmicrosoft.com/oauth2/authresp

If you choose to use the tenant ID, a valid OAuth redirect URI would look like the following sample:

https://login.contoso.com/11111111-1111-1111-1111-111111111111/oauth2/authresp

The SAML identity providers metadata would look like the following sample:

https://<custom-domain-name>.b2clogin.com/<tenant-name>/<your-policy>/samlp/metadata?idptp=<your-technical-profile>

Configure your application

After you configure and test the custom domain, you can update your applications to load the URL that specifies your custom domain as the hostname instead of the Azure AD B2C domain.

The custom domain integration applies to authentication endpoints that use Azure AD B2C policies (user flows or custom policies) to authenticate users. These endpoints may look like the following sample:

• https://<custom-domain>/<tenant-name>/<policy-name>/v2.0/.well-known/openid-configuration

• https://<custom-domain>/<tenant-name>/<policy-name>/oauth2/v2.0/authorize

• https://<custom-domain>/<tenant-name>/<policy-name>/oauth2/v2.0/token

Replace:

• custom-domain with your custom domain
• tenant-name with your tenant name or tenant ID
• policy-name with your policy name. Learn more about Azure AD B2C policies.

The SAML service provider metadata may look like the following sample:

https://custom-domain-name/tenant-name/policy-name/Samlp/metadata

(Optional) Use tenant ID

You can replace your B2C tenant name in the URL with your tenant ID GUID so as to remove all references to “b2c” in the URL. You can find your tenant ID GUID in the B2C Overview page in Azure portal. For example, change https://account.contosobank.co.uk/contosobank.onmicrosoft.com/ to https://account.contosobank.co.uk/<tenant ID GUID>/

If you choose to use tenant ID instead of tenant name, be sure to update the identity provider OAuth redirect URIs accordingly. For more information, see Configure your identity provider.

Token issuance

The token issuer name (iss) claim changes based on the custom domain being used. For example:

https://<domain-name>/11111111-1111-1111-1111-111111111111/v2.0/

::: zone pivot="b2c-custom-policy"

Block access to the default domain name

After you add the custom domain and configure your application, users will still be able to access the <tenant-name>.b2clogin.com domain. To prevent access, you can configure the policy to check the authorization request "host name" against an allowed list of domains. The host name is the domain name that appears in the URL. The host name is available through {Context:HostName} claim resolvers. Then you can present a custom error message.

1. Get the example of a conditional access policy that checks the host name from GitHub.
2. In each file, replace the string yourtenant with the name of your Azure AD B2C tenant. For example, if the name of your B2C tenant is contosob2c, all instances of yourtenant.onmicrosoft.com become contosob2c.onmicrosoft.com.
3. Upload the policy files in the following order: B2C_1A_TrustFrameworkExtensions_HostName.xml and then B2C_1A_signup_signin_HostName.xml.

::: zone-end

Troubleshooting

Azure AD B2C returns a page not found error

• Symptom - After you configure a custom domain, when you try to sign in with the custom domain, you get an HTTP 404 error message.
• Possible causes - This issue could be related to the DNS configuration or the Azure Front Door backend configuration.
• Resolution:
  1. Make sure the custom domain is registered and successfully verified in your Azure AD B2C tenant.
  2. Make sure the custom domain is configured properly. The CNAME record for your custom domain must point to your Azure Front Door default frontend host (for example, contoso.azurefd.net).
  3. Make sure the Azure Front Door backend pool configuration points to the tenant where you set up the custom domain name, and where your user flow or custom policies are stored.

Azure AD B2C returns the resource you are looking for has been removed, had its name changed, or is temporarily unavailable.

• Symptom - After you configure a custom domain, when you try to sign in with the custom domain, you get the resource you are looking for has been removed, had its name changed, or is temporarily unavailable error message.
• Possible causes - This issue could be related to the Azure AD custom domain verification.
• Resolution: Make sure the custom domain is registered and successfully verified in your Azure AD B2C tenant.

Identify provider returns an error

• Symptom - After you configure a custom domain, you're able to sign in with local accounts. But when you sign in with credentials from external social or enterprise identity providers, the identity provider presents an error message.
• Possible causes - When Azure AD B2C takes the user to sign in with a federated identity provider, it specifies the redirect URI. The redirect URI is the endpoint to where the identity provider returns the token. The redirect URI is the same domain your application uses with the authorization request. If the redirect URI is not yet registered in the identity provider, it may not trust the new redirect URI, which results in an error message.
• Resolution - Follow the steps in Configure your identity provider to add the new redirect URI.

Frequently asked questions

Can I use Azure Front Door advanced configuration, such as Web application firewall Rules?

While Azure Front Door advanced configuration settings are not officially supported, you can use them at your own risk.

When I use Run Now to try to run my policy, why I can't see the custom domain?

Copy the URL, change the domain name manually, and then paste it back to your browser.

Which IP address is presented to Azure AD B2C? The user's IP address, or the Azure Front Door IP address?

Azure Front Door passes the user's original IP address. It's the IP address that you'll see in the audit reporting or your custom policy.

Can I use a third-party web application firewall (WAF) with B2C?

To use your own web application firewall in front of Azure Front Door, you need to configure and validate that everything works correctly with your Azure AD B2C user flows, or custom polies.

Next steps

Learn about OAuth authorization requests.