Add a domain to a client tenancy with Windows PowerShell for Delegated Access Permission (DAP) partners
This article applies to both Microsoft 365 Enterprise and Office 365 Enterprise.
You can create and associate new domains with your customer's tenancy with PowerShell for Microsoft 365 faster than using the Microsoft 365 admin center.
Delegated Access Permission (DAP) partners are Syndication and Cloud Solution Providers (CSP) Partners. They're frequently network or telecom providers to other companies. They bundle Microsoft 365 subscriptions into their service offerings to their customers. When they sell a Microsoft 365 subscription, they're automatically granted Administer On Behalf Of (AOBO) permissions to the customer tenancies so they can administer and report on the customer tenancies.
What do you need to know before you begin?
The procedures in this article require you to connect to Connect to Microsoft 365 with PowerShell.
You also need your partner tenant administrator credentials.
You also need the following information:
You need the fully qualified domain name (FQDN) that your customer wants.
You need the customer's TenantId.
The FQDN must be registered with an Internet domain name service (DNS) registrar, such as GoDaddy. For more information on how to publicly register a domain name, see How to buy a domain name.
You need to know how to add a TXT record to the registered DNS zone for your DNS registrar. For more information on how to add a TXT record, see Add DNS records to connect your domain. If those procedures don't work for you, you'll need to find the procedures for your DNS registrar.
Create domains
Your customers will likely ask you to create additional domains to associate with their tenancy because they don't want the default <domain>.onmicrosoft.com domain to be the primary one that represents their corporate identities to the world. This procedure walks you through creating a new domain associated with your customer's tenancy.
Note
To perform some of these operations, the partner administrator account you sign in with must be set to Full administration for the Assign administrative access to companies you support setting found in the details of the admin account in the Microsoft 365 admin center. For more information on managing partner administrator roles, see Partners: Offer delegated administration.
Create the domain in Microsoft Entra ID
This command creates the domain in Microsoft Entra ID but doesn't associate it with the publicly registered domain. That comes when you prove that you own the publicly registered domain to Microsoft 365 for enterprises.
Note
The Azure Active Directory module is being replaced by the Microsoft Graph PowerShell SDK. You can use the Microsoft Graph PowerShell SDK to access all Microsoft Graph APIs. For more information, see Get started with the Microsoft Graph PowerShell SDK.
First, use a Microsoft Entra DC admin or Cloud Application Admin account to connect to your Microsoft 365 tenant.
Assigning and removing licenses for a user requires the Domain.ReadWrite.All permission scope or one of the other permissions listed in the 'Assign license' Graph API reference page.
Note
Azure AD and MSOnline PowerShell modules are deprecated as of March 30, 2024. To learn more, read the deprecation update. After this date, support for these modules are limited to migration assistance to Microsoft Graph PowerShell SDK and security fixes. The deprecated modules will continue to function through March, 30 2025.
We recommend migrating to Microsoft Graph PowerShell to interact with Microsoft Entra ID (formerly Azure AD). For common migration questions, refer to the Migration FAQ. Note: Versions 1.0.x of MSOnline may experience disruption after June 30, 2024.
Connect-MgGraph -Scopes "Domain.ReadWrite.All"
Run the following command to create a new domain:
New-MgDomain -Id <customer TenantId> -DomainNameReferences <FQDN of new domain>
Get the data for the DNS TXT verification record
Microsoft 365 generates the specific data that you need to place into the DNS TXT verification record. To get the data, run this command.
Import-Module Microsoft.Graph.Identity.DirectoryManagement
(Get-MgDomainVerificationDnsRecord -DomainId <domain ID, i.e. contoso.com> | Where-Object {$_.RecordType -eq "Txt"}).AdditionalProperties.text
This command gives you output like:
MS=ms########
Note
You will need this text to create the TXT record in the publicly registered DNS zone. Be sure to copy and save it.
Add a TXT record to the publically registered DNS zone
Before Microsoft 365 will start accepting traffic that is directed to the publicly registered domain name, you must prove that you own and have administrator permissions to the domain. You prove you own the domain by creating a TXT record in the domain. A TXT record doesn't do anything in your domain, and it can be deleted after your ownership of the domain is established. To create the TXT records, follow the procedures at Add DNS records to connect your domain. If those procedures don't work for you, you need to find the procedures for your DNS registrar.
Confirm the successful creation of the TXT record via nslookup. Follow this syntax.
nslookup -type=TXT <FQDN of registered domain>
This command gives you output like:
Non-authoritative answer:
FQDN of the registered domain
text=MS=ms########
Validate domain ownership in Microsoft 365
In this last step, you validate to Microsoft 365 that you own the publically registered domain. After this step, Microsoft 365 will begin accepting traffic routed to the new domain name. To complete the domain creation and registration process, run this command.
Confirm-MgDomain -DomainId <FQDN of new domain> -InputObject @{TenantId=<customer TenantId>}
This command doesn't return any output, so to confirm that the command worked, run this command.
Get-MgDomain -DomainId <FQDN of new domain>
This will return something like this:
Id AuthenticationType AvailabilityStatus IsAdminManaged IsDefault IsInitial IsRoot IsVerified Manufact
urer
-- ------------------ ------------------ -------------- --------- --------- ------ ---------- --------
contoso.com Managed True True True True True