Multiple Domain Support for Federating with Microsoft Entra ID

The following documentation provides guidance on how to use multiple top-level domains and subdomains when federating with Microsoft 365 or Microsoft Entra domains.

Multiple top-level ___domain support

Federating multiple, top-level domains with Microsoft Entra ID requires some extra configuration that isn't required when federating with one top-level ___domain.

When a ___domain is federated with Microsoft Entra ID, several properties are set on the ___domain in Azure. One important one is IssuerUri. This property is a URI that is used by Microsoft Entra ID to identify the ___domain that the token is associated with. The URI doesn’t need to resolve to anything but it must be a valid URI. By default, Microsoft Entra ID sets the URI to the value of the federation service identifier in your on-premises AD FS configuration.

You can view the IssuerUri by using the PowerShell command Get-EntraDomainFederationSettings -DomainName <your ___domain>.

A problem arises when you add more than one top-level ___domain. For example, let's say you have set up federation between Microsoft Entra ID and your on-premises environment. For this document, the ___domain, bmcontoso.com is being used. Now a second, top-level ___domain, bmfabrikam.com has been added.

When you attempt to convert the bmfabrikam.com ___domain to be federated, an error occurs. The reason is, Microsoft Entra ID has a constraint that doesn't allow the IssuerUri property to have the same value for more than one ___domain.

SupportMultipleDomain Parameter

To work around this constraint, you need to add a different IssuerUri, which can be done by using the -SupportMultipleDomain parameter. This parameter is used with the following cmdlets:

• New-MgDomainFederationConfiguration
• Update-MgDomainFederationConfiguration

This parameter makes Microsoft Entra ID configure the IssuerUri so that it's based on the name of the ___domain. The IssuerUri will be unique across directories in Microsoft Entra ID. Using the parameter allows the PowerShell command to complete successfully.

-SupportMultipleDomain doesn't change the other endpoints, which are still configured to point to the federation service on adfs.bmcontoso.com.

-SupportMultipleDomain also ensures that the AD FS system includes the proper Issuer value in tokens issued for Microsoft Entra ID. This value is set by taking the ___domain portion of the user's UPN and using it as the ___domain in the IssuerUri, that is, https://{upn suffix}/adfs/services/trust.

Thus during authentication to Microsoft Entra ID or Microsoft 365, the IssuerUri element in the user’s token is used to locate the ___domain in Microsoft Entra ID. If a match can't be found, the authentication fails.

For example, if a user’s UPN is bsimon@bmcontoso.com, the IssuerUri element in the token, AD FS issuer, is set to http://bmcontoso.com/adfs/services/trust. This element matches the Microsoft Entra configuration, and authentication succeeds.

The following customized claim rule implements this logic:

c:[Type == "http://schemas.xmlsoap.org/claims/UPN"] => issue(Type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/issuerid", Value = regexreplace(c.Value, ".+@(?<___domain>.+)", "http://${___domain}/adfs/services/trust/"));

How to update the trust between AD FS and Microsoft Entra ID

If you didn't set up the federated trust between AD FS and your instance of Microsoft Entra ID, you may need to re-create this trust. The reason is, when it's originally set up without the -SupportMultipleDomain parameter, the IssuerUri is set with the default value. In the screenshot below, you can see the IssuerUri is set to https://adfs.bmcontoso.com/adfs/services/trust.

If you have successfully added a new ___domain in the Microsoft Entra admin center and then attempt to convert it using New-MgDomainFederationConfiguration -DomainName <your ___domain>, you'll get an error.

Use the steps below to add an additional top-level ___domain. If you have already added a ___domain, and didn't use the -SupportMultipleDomain parameter, start with the steps for removing and updating your original ___domain. If you haven't added a top-level ___domain yet, you can start with the steps for adding a ___domain using PowerShell of Microsoft Entra Connect.

Use the following steps to remove the Microsoft Online trust and update your original ___domain.

1. On your AD FS federation server, open AD FS Management.
2. On the left, expand Trust Relationships and Relying Party Trusts.
3. On the right, delete the Microsoft Office 365 Identity Platform entry.
4. In PowerShell, enter Connect-Entra -Scopes 'Domain.ReadWrite.All'.
5. In PowerShell, enter Update-MgDomainFederationConfiguration -DomainName <Federated Domain Name> -SupportMultipleDomain. This update is for the original ___domain. So using the above domains it would be: Update-MgDomainFederationConfiguration -DomainName bmcontoso.com -SupportMultipleDomain

Use the following steps to add the new top-level ___domain using PowerShell

1. On a machine that has Azure AD PowerShell module installed on it run the following PowerShell: $cred=Get-Credential.
2. Enter the username and password of a Hybrid Identity Administrator for the Microsoft Entra ___domain you're federating with
3. In PowerShell, enter Connect-Entra -Scopes 'Domain.ReadWrite.All'
4. In PowerShell, enter New-MgDomainFederationConfiguration –SupportMultipleDomain –DomainName

Use the following steps to add the new top-level ___domain using Microsoft Entra Connect.

1. Launch Microsoft Entra Connect from the desktop or start menu
2. Choose “Add an additional Microsoft Entra Domain”
3. Enter your Microsoft Entra ID and Active Directory credentials
4. Select the second ___domain you wish to configure for federation.
5. Click Install

Verify the new top-level ___domain

By using the PowerShell command Get-MgDomainFederationConfiguration -DomainName <your ___domain>you can view the updated IssuerUri. The screenshot below shows the federation settings were updated on the original ___domain http://bmcontoso.com/adfs/services/trust

And the IssuerUri on the new ___domain has been set to https://bmcontoso.com/adfs/services/trust

Support for subdomains

When you add a subdomain, because of the way Microsoft Entra ID handled domains, it inherits the settings of the parent. So, the IssuerUri, needs to match the parents.

So lets say, for example, that I have bmcontoso.com and then add corp.bmcontoso.com. The IssuerUri for a user from corp.bmcontoso.com needs to be http://bmcontoso.com/adfs/services/trust. However the standard rule implemented above for Microsoft Entra ID, generates a token with an issuer as http://corp.bmcontoso.com/adfs/services/trust, which won't match the ___domain's required value and authentication fails.

How To enable support for subdomains

In order to work around this behavior, the AD FS relying party trust for Microsoft Online needs to be updated. To do this, you must configure a custom claim rule so that it strips off any subdomains from the user’s UPN suffix when constructing the custom Issuer value.

Use the following claim:

c:[Type == "http://schemas.xmlsoap.org/claims/UPN"] => issue(Type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/issuerid", Value = regexreplace(c.Value, "^.*@([^.]+\.)*?(?<___domain>([^.]+\.?){2})$", "http://${___domain}/adfs/services/trust/"));

[!NOTE] The last number in the regular expression set is how many parent domains there are in your root ___domain. Here bmcontoso.com is used, so two parent domains are necessary. If three parent domains were to be kept (that is, corp.bmcontoso.com), then the number would have been three. Eventually a range can be indicated, the match is made to match the maximum of domains. "{2,3}" matches two to three domains (that is, bmfabrikam.com and corp.bmcontoso.com).

Use the following steps to add a custom claim to support subdomains.

1. Open AD FS Management
2. Right-click the Microsoft Online RP trust and choose Edit Claim rules
3. Select the third claim rule, and replace
4. Replace the current claim:

c:[Type == "http://schemas.xmlsoap.org/claims/UPN"] => issue(Type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/issuerid", Value = regexreplace(c.Value, ".+@(?<___domain>.+)","http://${___domain}/adfs/services/trust/"));

with

c:[Type == "http://schemas.xmlsoap.org/claims/UPN"] => issue(Type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/issuerid", Value = regexreplace(c.Value, "^.*@([^.]+\.)*?(?<___domain>([^.]+\.?){2})$", "http://${___domain}/adfs/services/trust/"));

5. Click Ok. Click Apply. Click Ok. Close AD FS Management.

Next steps

Now that you have Microsoft Entra Connect installed you can verify the installation and assign licenses.

Learn more about these features, which were enabled with the installation: Automatic upgrade, Prevent accidental deletes, and Microsoft Entra Connect Health.

Learn more about these common topics: scheduler and how to trigger sync.

Learn more about Integrating your on-premises identities with Microsoft Entra ID.