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.

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.

First, use a Microsoft Entra DC admin, Cloud Application Admin, or Global 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.

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########

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

See also

Help for partners