Manage custom ___domain names in your Microsoft Entra ID

Overview

A ___domain name is an important part of the identifier for resources in many Microsoft Entra deployments. It's part of a user name or email address for a user, part of the address for a group, and is sometimes part of the app ID URI for an application. A resource in Microsoft Entra ID can include a ___domain name that's owned by the Microsoft Entra organization (sometimes called a tenant) that contains the resource. The Domain Name Administrator role is the least privileged role required to manage domains in Microsoft Entra ID.

Set the primary ___domain name for your Microsoft Entra organization

When your organization is created, the initial ___domain name, such as "contoso.onmicrosoft.com," is also the primary ___domain name. The primary ___domain is the default ___domain name for a new user when you create a new user. Setting a primary ___domain name streamlines the process for an administrator to create new users in the portal. To change the primary ___domain name:

1. Sign in to the Microsoft Entra admin center as at least a Domain Name Administrator.

2. Browse to Entra ID > Domain names

3. Select Custom ___domain names.

   

4. Select the name of the ___domain that you want to be the primary ___domain.

5. Select the Make primary command. Confirm your choice when prompted.

   

You can change the primary ___domain name for your organization to be any verified custom ___domain that isn't federated. Changing the primary ___domain for your organization doesn't change the user name for any existing users.

Add custom ___domain names to your Microsoft Entra organization

You can add up to 5000 managed ___domain names. If you're configuring all your domains for federation with on-premises Active Directory, you can add up to 2,500 ___domain names in each organization.

Add subdomains of a custom ___domain

If you want to add a subdomain name such as ‘europe.contoso.com’ to your organization, you should first add and verify the root ___domain, such as contoso.com. Microsoft Entra ID automatically verifies the subdomain. To see that the subdomain you added is verified, refresh the ___domain list in the browser.

If you have already added a contoso.com ___domain to one Microsoft Entra organization, you can also verify the subdomain europe.contoso.com in a different Microsoft Entra organization. When adding the subdomain, you're prompted to add a TXT record in the Domain Name Server (DNS) hosting provider.

What to do if you change the DNS registrar for your custom ___domain name

If you change the DNS registrars, there are no other configuration tasks in Microsoft Entra ID. You can continue using the ___domain name with Microsoft Entra ID without interruption. If you use your custom ___domain name with Microsoft 365, Intune, or other services that rely on custom ___domain names in Microsoft Entra ID, see the documentation for those services.

Delete a custom ___domain name

You can delete a custom ___domain name from your Microsoft Entra ID if your organization no longer uses that ___domain name, or if you need to use that ___domain name with another Microsoft Entra organization.

To delete a custom ___domain name, you must first ensure that no resources in your organization rely on the ___domain name. You can't delete a ___domain name from your organization if:

• Any user has a user name, email address, or proxy address that includes the ___domain name.
• Any group has an email address or proxy address that includes the ___domain name.
• Any application in your Microsoft Entra ID has an app ID URI that includes the ___domain name.

You must change or delete any such resource in your Microsoft Entra organization before you can delete the custom ___domain name.

ForceDelete option

You can ForceDelete a ___domain name in the Azure portal or using Microsoft Graph API. These options use an asynchronous operation and update all references from the custom ___domain name like “user@contoso.com” to the initial default ___domain name such as "user@contoso.onmicrosoft.com."

To call ForceDelete in the Azure portal, you must ensure that there are fewer than 1,000 references to the ___domain name, and any references where Exchange is the provisioning service must be updated or removed in the Exchange Admin Center (EAC). This includes Exchange Mail-Enabled Security Groups and distributed lists. For more information, see Removing mail-enabled security groups. Also, the ForceDelete operation doesn't succeed if either of the following is true:

• You purchased a ___domain via Microsoft 365 ___domain subscription services
• You're a partner administering on behalf of another customer organization

The following actions are performed as part of the ForceDelete operation:

• Renames the UPN, EmailAddress, and ProxyAddress of users with references to the custom ___domain name to the initial default ___domain name.
• Renames the EmailAddress of groups with references to the custom ___domain name to the initial default ___domain name.
• Renames the identifierUris of applications with references to the custom ___domain name to the initial default ___domain name.
• Disables user accounts impacted by the ForceDelete option in the Microsoft Entra admin center and optionally when using the Graph API.

An error is returned when:

• The number of objects to be renamed is greater than 1000
• One of the applications to be renamed is a multitenant app

Best practices for ___domain hygiene

Use a reputable registrar that provides ample notifications for ___domain name changes, registration expiry, a grace period for expired domains, and maintains high security standards for controlling who has access to your ___domain name configuration and TXT records. Keep your ___domain names current with your registrar, and verify TXT records for accuracy.

• If you purposefully are expiring your ___domain name or turning over ownership to someone else (separately from your Microsoft Entra tenant), you should delete it from your Microsoft Entra tenant before expiring or transferring.
• If you do allow your ___domain name to expire, if you're able to reactivate it/regain control of it, carefully review all TXT records with the registrar to ensure no tampering of your ___domain name took place.
• If you can't reactivate or regain control of your ___domain name immediately, you should delete it from your Microsoft Entra tenant. Don't read/re-verify until you're able to resolve ownership of the ___domain name and verify the full TXT record for correctness.

Frequently asked questions

Q: Why is the ___domain deletion failing with an error that states that I have Exchange mastered groups on this ___domain name?
A: Today, certain groups like Mail-Enabled Security groups and distributed lists are provisioned by Exchange and need to be manually cleaned up in Exchange Admin Center. There might be lingering ProxyAddresses, which rely on the custom ___domain name and will need to be updated manually to another ___domain name.

Q: I am logged in as admin@contoso.com but I cannot delete the ___domain name “contoso.com”?
A: You can't reference the custom ___domain name you're trying to delete in your user account name. Ensure that your account with at least the Domain Name Administrator role is using the initial default ___domain name (.onmicrosoft.com) such as admin@contoso.onmicrosoft.com. Sign in with a different account that has at least the Domain Name Administrator role, such as admin@contoso.onmicrosoft.com or another custom ___domain name like “fabrikam.com” where the account is admin@fabrikam.com.

Q: I clicked the Delete ___domain button and see In Progress status for the Delete operation. How long does it take? What happens if it fails?
A: The delete ___domain operation is an asynchronous background task that renames all references to the ___domain name. It might take up to 24 hours to complete. If ___domain deletion fails, ensure that you don’t have:

• Apps configured on the ___domain name with the appIdentifierURI
• Any mail-enabled group referencing the custom ___domain name
• More than 1000 references to the ___domain name
• The ___domain to be removed is set as the primary ___domain of your organization

Also note that the ForceDelete option won't work if the ___domain uses Federated authentication type. In that case the users/groups on the ___domain must be renamed or removed using the on-premises Active Directory before reattempting the ___domain removal. If you find that any of the conditions haven’t been met, manually clean up the references, and try to delete the ___domain again.

Use PowerShell or the Microsoft Graph API to manage ___domain names

Most management tasks for ___domain names in Microsoft Entra ID can also be completed using Microsoft PowerShell, or programmatically using the Microsoft Graph API.

• Using PowerShell to manage ___domain names in Microsoft Entra ID
• Domain resource type

Next steps

• Add custom ___domain names
• Remove Exchange mail-enabled security groups in Exchange Admin Center on a custom ___domain name in Microsoft Entra ID
• ForceDelete a custom ___domain name with Microsoft Graph API