M365DomainMgmt: A PowerShell module for assisting domain management in Microsoft 365 (Part 2)

Part 2: Using M365DomainMgmt to add a domain…

The Microsoft 365 admin center provides administrators the ability to add domains to Microsoft 365 tenants.

The M365DomainMgmt PowerShell module provides administrators a wrapper for Microsoft Graph to walk them through the domain addition. In M365DomainMgmt: A PowerShell module for assisting domain management in Microsoft 365 (Part 1) I outlined how the module can be utilized to add the domain, provide and validate the presence of public dns records, and validate the domain in a single operation. (M365DomainMgmt: A PowerShell module for assisting domain management in Microsoft 365 (Part 1) | TIMMCMIC)

There may be scenarios where administrators wish to add the domain but proceeding with verification immediately is not possible. For example, external DNS is managed by another team within the organization, and it may take some time after adding the domain and providing the external DNS records for those records to be available.

Installation and Microsoft Graph Prerequisites

See M365DomainMgmt: A PowerShell module for assisting domain management in Microsoft 365 (Part 1) | TIMMCMIC sections “Installing the M365DomainMgmt Module” and “M365DomainMgmt and Microsoft Graph” for instructions on how to install the module and Microsoft Graph authentication prerequisites.

Starting M365DomainMgmt to Add and Verify a Domain

Example #1: Leverage interactive authentication to a global tenant

Start-M365DomainManagement -logFolderPath c:\temp -msGraphEnvironmentName "Global" -msGraphTenantID "EntraTenantIDAsGUID"

Example #2: Leveraging client secret authentication to a global tenant

Start-M365DomainManagement -logFolderPath c:\temp -msGraphEnvironmentName "Global" -msGraphTenantID "EntraTenantIDAsGUID" -msGraphClientSecret "ClientSecret" -msGraphApplicationID "EntraRegisteredAppID"

Example #3: Leverage certificate authentication to a global tenant

Start-M365DomainManagement -logFolderPath c:\temp -msGraphEnvironmentName "Global" -msGraphTenantID "EntraTenantIDAsGUID" -msGraphCertificateThumbprint "CertificateThumbprint" -msGraphApplicationID "EntraRegisteredAppID"

Example #4: Leveraging client secret authentication to a GCC High tenant

Start-M365DomainManagement -logFolderPath c:\temp -msGraphEnvironmentName "USGov" -msGraphTenantID "EntraTenantIDAsGUID" -msGraphClientSecret "ClientSecret" -msGraphApplicationID "EntraRegisteredAppID"

Example #5: Leverage interactive authentication, specify the domain name and operation to bypass interactive prompts.

Start-M365DomainManagement -logFolderPath c:\temp -msGraphEnvironmentName "Global" -msGraphTenantID "EntraTenantIDAsGUID" -domainName "domain.com" -domainOperation "NewWOConfirm"

The Domain Addition Process

The M365DomainMgmt module starts the domain addition process by validating the state and version of dependent PowerShell modules and noting their versions in the log file.

If a domain and domain operation are not specified as a part of the command execution a list of supported operations is provided and the desired operation is selected by number.

This blog post covers option 2 – New / Add Domain (No Domain Verification)

If a domain and domain operation are not specified as part of the command execution the administrator is prompted to provide the domain name interactively. Providing the domain name and pressing enter continues the commands progression.

The command progresses by performing the following operations

  • Queries the tenant to determine if the domain is present and validated.
    • If the domain is validated already the command terminates at this operation and provides administrative feedback
  • Queries the tenant to determine if the domain has not been added and adds the domain to the tenant.
    • The domains status upon successful addition is recorded to the log file and exported to the log directory for retention.

If the domain has been successfully added to the tenant the next step is providing the administrators with the DNS verification records for domain validation. Each domain added to a Microsoft 365 tenant has unique verification records. Both a TXT record and MX record are supplied for validation but only one record is required in external DNS for validation.

Pressing the enter key after recording the DNS validation records completes the operation.

Operation Reporting

The M365DomainMgmt module records all operation and their results to the log file created in the directory specified. The log file directory also contains all exports of Microsoft 365 object states to XML files. To allow the administrator a more accessible method of interpreting results, an HTML file is created that contains all pertinent information to the domain addition process.

DNS Verification Records Section

This section provides the DNS verification records for external DNS.

Domain Information Section

This section provides the domain information exported after the domain was successfully found in Microsoft 365 or successfully added to Microsoft 365.

How to proceed with domain verification and testing?

The same PowerShell module may be utilized to complete the domain verification process. Refer to M365DomainMgmt: A PowerShell module for assisting domain management in Microsoft 365 (Part 1) | TIMMCMIC which outlines option 1 to perform health checks and verification.

I need Microsoft Support

If you require Microsoft Support, you may open a case within the M365 admin center from the tenant where you are attempting to add the domain. If an error is encountered in the domain addition and verification process, a zip file of all diagnostic information is created automatically for you in the log file directory. This zip file contains the basic information that Microsoft Support may utilize to assist in diagnosing the domain addition failure as well as engage our engineering team for analysis should that become necessary.

Leave a Reply