Forum Discussion

FcoManigrasso's avatar
FcoManigrasso
Iron Contributor
May 18, 2022

Cross Tenant Mailbox Migration: Step by Step Guide

This post will describe step by step cross tenant mailbox migration in an easy way. Please follow each point in order to avoid any issue. Check common errors and fixes in the following link: Cross-tenant mailbox migration: Common issues. - Microsoft Tech Community

 

You can also find the Microsoft official documentation here: Cross-tenant mailbox migration - Microsoft 365 Enterprise | Microsoft Docs

 

1- Get both tenants ID's, ( something like: d72f6b6a-ed9c-4bb3-8ae2-03f1f66d1b7f ). You can get it from: portal.azure.com - Identity - Tenant Properties

 

2- Get the source mailboxes list with all the required attributes in order to create the MailUsers in the target tenant. You can run the following command:

 

Get-Mailbox -ResultSize Unlimited | select ExchangeGUID,ArchiveGUID,LegacyExchangeDN,UserPrincipalName,PrimarySMTPAddress,DisplayName | Export-Csv -NoTypeInformation "C:\<WhereYouWouldLikeToExport.csv>"

 

3- Create a Mail Enabled Security Group in the source tenant with all the mailboxes that we want to migrate.

 

4- Create the Mail Users in the destination tenant with the attributes from the source tenant. The external email address should be that one from the source tenant and the primary SMTP address should be the desired target domain.
(NOTE: Don’t assign an Exchange license before configuring correctly all attributes).

(NOTE2: If the source user has more X500 addresses you'll need to add all them to the target mail user).

 

Example: 

 

Set-MailUser "John Doe" -ExchangeGuid efa11ed1-a387-4302-8641-5a162c3d412e -ArchiveGuid c17f0225-f0c9-48be-b475-fdb300f874ae -EmailAddresses "SMTP:john@contoso.onmicrosoft.com","smtp:john@fabrikam.onmicrosoft.com","x500:/o=ExchangeLabs/ou=Exchange Administrative Group (FYDIBOHF23SPDLT)/cn=Recipients/cn=4a3925ffc74446e581b51994a6e59eb0-john"

 

5- In order to proceed with the tenants Azure relationship and migration endpoint configuration you'll need to download the configuration scripts provided by Microsoft, ( available in the upper link ). Save the scripts in a desired location.

. Open the Exchange Management Shell and connect to EXO from the target tenant.

. Go to the path were the scripts are located, ( cd "C:\<WhereTheScriptsAre>" )

. Execute the target tenant configuration script with all the required information. 

 

Example:

 

.\SetupCrossTenantRelationshipForTargetTenant.ps1 -ResourceTenantDomain contoso.onmicrosoft.com -ResourceTenantAdminEmail admin@contoso.onmicrosoft.com -TargetTenantDomain fabrikam.com -ResourceTenantId d72f8b6a-ed9c-4bb3-6ae2-03f1f77d1b7f -SubscriptionId 6f93f73f-3b5b-4bfe-9a25-ce87406356bf -ResourceGroup "RG_MailMigraiton_TST" -KeyVaultName "Cross-TenantMovesVault" -CertificateName "crt-mailmigration" -CertificateSubject "CN=tst.contoso.com" -AzureAppPermissions Exchange, MSGraph

 

(NOTES: You'll need one Azure Subscription ID. If you're owner of the mentioned subscription, the script will create all the other required features, so, you can name the Resource Group and the KeyVault as you like).

. Once the Resource Group, KeyVault and Certificate are configured, the script will pause.

. Copy the first link, ( only the first one ), from the script output and paste it in a private browsing window. Login as the target tenant admin and accept the message.

 

. After that, go back to the script and press Enter. Another login window will pop up, please login with the source tenant admin account.

. Once the script finishes, you'll see this message:

 

 

6- Login in the source tenant as Global Administrator and check the email. The invitation should be received and you need to accept it.

 

7- Open the Exchange Management Shell and connect to EXO from the source tenant.

. Go to the path were the scripts are located, ( cd "C:\<WhereTheScriptsAre>" )

. Execute the source tenant configuration script with all the required information.

EXAMPLE:

.\SetupCrossTenantRelationshipForResourceTenant.ps1 -SourceMailboxMovePublishedScopes "Mailboxes Migration Group" -ResourceTenantDomain contoso.onmicrosoft.com -TargetTenantDomain fabrikam.com -ApplicationId c2b7bfba-9083-405e-b242-fc306250ba41 -TargetTenantId f0dff375-0ead-45af-85fd-dc7cd6871e46

(NOTE: You can get the Application ID from the invitation email received by the source tenant admin or from the source Azure Portal - Enterprise Apps ).

. Once the script finishes, you'll see this message:

 

8- Assign a Office365 license to the MailUsers. ( May you want to doublecheck that the correct attributes are configured before this step ).

 

9- Create the migration batch from the target tenant. You can create it using PS or the ECP:

 

New-MigrationBatch -Name T2TmigrationTest -SourceEndpoint tst_contoso_4547 -CSVData ([System.IO.File]::ReadAllBytes('users.csv')) -Autostart -TargetDeliveryDomain fabrikam.com -AutoComplete

 

10- Once the migration finishes, check that the mailboxes are reachable and all is working as expected.

 

11- Set the “onmicrosoft.com” domain to all the users in the source tenant in order to remove the source domain from there.

 

12- Add and verify the source domain in the target tenant and assign it to the migrated mailboxes as primary SMTP.

  • awaaziz's avatar
    awaaziz
    Copper Contributor
    Hello,

    I have a question about these scenario if it is supported or not :

    Source : Hybrid Exchange.
    Target : Users synced from ADDS and we don't have an exchange organisation. Users have an Exchange Online mailbox.

    As i know we cant create a user mailbox object if we dont have an exchange server ?

    How can address these issue

    Thanks for your reply
    • FcoManigrasso's avatar
      FcoManigrasso
      Iron Contributor

      Hi awaaziz,

      First of all, let me shared with you the new stpes for a cross tenant mailbox migration, as this article isn't up to date, sorry: Cross-tenant mailbox migration - Microsoft 365 Enterprise | Microsoft Learn

       

      Second, If I understood correctly your scenario, ( target users already have a mailbox in EXO ), this process will not support it. ( Existing mailboxes have their own ExchangeGuid, ArchiveGuid... And you need to set those attributes previously on new created mailusers ). Delete the mailboxes and strat from scratch will also not be a solution, ( unless we're talking about a few mailboxes with no much content... Then that could be backed up ). 

      Possible solutions could be create new mail users on target side, migrate from the source to them, and after that move the mailbox content to the original mailboxes, ( a nightmare and only feasible if we're talking about a few mailboxes again ). 

      Also PST export/import... But again, for a few mailboxes and taking in mind the security risks following that procedure.

      Maybe if you could provide me more info, ( number of users, mailboxes sizes, etc... ), I might have some other idea.

       

      • awaaziz's avatar
        awaaziz
        Copper Contributor
        My scenario as i explain is in the target i have just an ADDS and i use Azure AD Connect to sync accounts. So i cant create a mail user object in my On-Premises environnement and synced after.
        The new mail users will be created in the cloud and for me the user must use the synced account

Resources