Microsoft 365 tenant-to-tenant migration: the complete guide

Mailbox, OneDrive and SharePoint moves all map source users to target users that must already exist, and the target objects must be shaped correctly (for example, MailUsers with the source ExchangeGuid). Finish the identity design before you configure any data move.

Give every migrating user and group one row in the mapping sheet: source UPN, target UPN, source object ID and target object ID. Create the target accounts with cross-tenant synchronisation or bulk create them from a CSV. Do not create the mailbox endpoint, the SharePoint trust or the identity map until every row has a target object.

Mailbox batches can synchronise for weeks and complete at cutover; Microsoft recommends submitting them two weeks ahead. OneDrive and SharePoint moves are one-time with no delta pass, so schedule them into each wave's cutover window.

For each wave, enter three dates: the mailbox batch submission date, the batch completion time (the -CompleteAfter value) and the OneDrive and site move start time (the -PreferredMoveBeginDate value, in UTC).

Move a person's mailbox, OneDrive and chats in the same window, and keep delegates with the mailboxes they manage. Microsoft's orchestrator is designed to run a user's workloads together in dependency order.

List each user once, in one wave. Next to shared mailboxes, list every person with Full Access or Send on Behalf and put them in the same wave.

Teams structure, Groups, Planner, Forms, Power Platform and Power BI do not depend on the mail cutover. Rebuild them in the target during the waves so they are ready when users arrive.

Add a task for each, with an owner and a finish date before the first user wave that needs it. Use the runbooks linked in the coverage table above for the exact steps.

The custom domain moves once every object that uses it is migrated or ready, because it can only be verified in one tenant at a time.

Schedule the domain removal after the final mailbox batch completes, and the target verification straight after it. The full sequence is in the cutover section below.

One sheet with source UPN, target UPN and object IDs for every user and group. The mailbox endpoint, OneDrive identity map and SharePoint identity map all come from it.

If you do not have the module, install Microsoft Graph PowerShell first. Run the commands below in the source tenant, then again in the target, sign in with an admin of that tenant when the browser opens, and paste both exports into the mapping sheet side by side.

Connect-MgGraph -Scopes "User.Read.All","Group.Read.All"
Get-MgUser -All -Property Id,DisplayName,UserPrincipalName,Mail |
  Select-Object Id,DisplayName,UserPrincipalName,Mail | Export-Csv C:\T2T\users.csv -NoTypeInformation
Get-MgGroup -All | Select-Object Id,DisplayName,Mail,GroupTypes |
  Export-Csv C:\T2T\groups.csv -NoTypeInformation
Disconnect-MgGraph

Sync external members for coexistence and convert them at migration, or create internal users directly. Either way, plan MFA registration in the target and rebuild Conditional Access with target IDs.

For sync, both tenants must first set up cross-tenant access settings; the sync configuration itself is in the Entra ID runbook. To create users directly, select Add multiple users on the Active users page, as described in bulk create users from a CSV. Record the choice in the mapping sheet.

Mailboxes on any hold are blocked, Microsoft 365 Groups are not supported, and Send on Behalf, signatures and Teams meeting links do not carry over. Assigning an Exchange licence too early creates an empty mailbox.

If you have not used Exchange Online PowerShell before, install the module and connect first. Run the commands below to list mailboxes on hold and count Microsoft 365 Groups, and copy both lists into your risk register.

Get-EXOMailbox -ResultSize Unlimited -Properties LitigationHoldEnabled,InPlaceHolds |
  Where-Object { $_.LitigationHoldEnabled -or $_.InPlaceHolds } |
  Select-Object DisplayName,PrimarySmtpAddress,LitigationHoldEnabled,InPlaceHolds

(Get-UnifiedGroup -ResultSize Unlimited).Count

Users rebuild Outlook profiles and re-add mobile accounts, so budget hypercare time and bandwidth for OST downloads.

Put the steps from reset an Outlook profile into the day-one guide, test them with pilot users, and roster extra support for the morning after each wave completes.

A move fails if the user already has a OneDrive in the target, so restrict OneDrive creation there until the move completes.

By default Everyone except external users has the Create Personal Site permission. Remove that group, add only a group of people who should get a OneDrive now (for example IT staff), then select OK. Microsoft notes this does not delete OneDrives that already exist.

The move is one-time with no delta pass, and a redirect is left at the old URL until you remove it.

Enter each user's OneDrive move start time (UTC) inside their wave's cutover window, and add a clean-up task to remove redirects after the project closes.

Target Microsoft 365 groups for group-connected sites must be created with ProvisionSiteOnDemand so no site exists, and target sites must not exist.

See install Microsoft Graph PowerShell (the Beta module is a separate install). Create each group with the command below, matching the source group's visibility, and note the returned Id for the identity map. The full procedure is in the SharePoint runbook.

Install-Module Microsoft.Graph.Beta -Repository PSGallery -Force
Connect-MgGraph -Scopes "Group.ReadWrite.All"
New-MgBetaGroup -GroupTypes Unified -MailNickname "FinanceTeam" -DisplayName "Finance Team" `
  -ResourceBehaviorOptions "ProvisionSiteOnDemand" -MailEnabled:$False -SecurityEnabled

2010 and 2013 workflows, apps, Power Apps and flows, cross-site web parts and label protection do not move.

Ask each site owner which of these their site uses, and add each one as a rebuild task with an owner.

Decide per team whether to rebuild and start fresh, use a third-party tool for channel conversations, or keep the source searchable for records.

Copy the list of teams from the source Microsoft Teams admin center (admin.teams.microsoft.com) > Teams > Manage teams into the inventory, add a column for the decision, and ask each owner to confirm it.

Rebuild teams, channels, owners and apps in the target, and have organisers recreate recurring meetings if you are not migrating them.

Select Add, enter the team name and description, choose private or public, then select the new team in the list to open its profile page and add channels and owners. Tell organisers in the wave communications which meetings they need to recreate.

Recreate each group with the same owners and members. Export important Planner plans to Excel as a record, then rebuild them or use a migration tool. See Groups and Planner migration.

In each source plan choose Export plan to Excel from the ... menu in the plan header and save the file with the project records. In the target admin center, add each group from the Active teams & groups page, then add its owners and members from your mapping sheet.

Export each important form's responses to Excel before the owner's source account goes, then duplicate or recreate the form in the target and update links, QR codes and flows. See Microsoft Forms migration.

Open the form, select View responses, then use the menu next to Open results in Excel to download a copy, and store it with the project records.

List every app, flow, connector and environment with its owner. Personal flows outside solutions are the easiest to miss.

Record each environment's name and type from the Environments page. For each environment, list its apps and flows with their owners; the Power Platform runbook covers the inventory in detail.

Microsoft recommends migrating a copy of production as a sandbox and testing it before you migrate production.

The copy overwrites an existing sandbox environment in the same tenant and region, so create or choose that sandbox first. Select Copy on the top menu bar, choose the copy level (Everything or Customizations and schemas only), select the sandbox as the target, select Copy and then Confirm. Microsoft warns that everything in the target sandbox is deleted and replaced.

Record each workspace, its members, data sources, gateways and refresh schedules, and where reports are embedded in Teams or SharePoint.

Sign in as a Fabric or Power BI administrator. Copy the workspace list from the admin portal into your inventory, then record each gateway and connection from the gateways page. The Power BI runbook lists everything to capture.

Republish content into target workspaces, reconfigure gateways and credentials, then reshare and update embedded links.

Open each .pbix file, select Publish on the Home ribbon and choose the target workspace. In the target service, set data source credentials and refresh schedules in each semantic model's settings, then reshare and replace embedded links in Teams and SharePoint.

Compliance, configuration, app and Autopilot profiles must be ready in the target before the first device enrols, along with Conditional Access that expects those devices.

Recreate each policy and profile from your source inventory in the target Intune admin center, and assign them to target groups. The device runbook lists each item and the order to build it in.

Back up BitLocker recovery keys, decide how user profiles and local data are handled, and schedule device work around each wave's cutover.

Export the source keys with the command below while the device records still exist, and save the file somewhere secure. Add each device to the same wave as its user.

Connect-MgGraph -Scopes "BitlockerKey.Read.All"
Get-MgInformationProtectionBitlockerRecoveryKey -All |
  ForEach-Object {
    $k = Get-MgInformationProtectionBitlockerRecoveryKey -BitlockerRecoveryKeyId $_.Id -Property key
    [pscustomobject]@{ DeviceId = $_.DeviceId; KeyId = $_.Id; Key = $k.Key }
  } | Export-Csv C:\secure\bitlocker-keys.csv -NoTypeInformation

Lower TTLs on MX, Autodiscover and SPF records ahead of time, freeze changes, and confirm the last mailbox batches are synced with completion scheduled for the window.

Edit each record's TTL as described in lower DNS TTL before a migration, at least one old TTL period before the window. Then check the batches in the target.

Get-MigrationBatch | Format-Table Identity,Status,TotalCount,SyncedCount,FailedCount,CompleteAfter

Complete mailbox batches and confirm the OneDrive and site moves scheduled for the window have succeeded.

For each batch without a scheduled completion, select it and choose Complete migration batch, or run Complete-MigrationBatch (see create and complete a migration batch). Then check file moves with the second command from a SharePoint Online Management Shell session connected to the source.

Complete-MigrationBatch -Identity "Wave1"

Get-SPOCrossTenantUserContentMoveState -PartnerCrossTenantHostURL https://fabrikam-my.sharepoint.com/

Change UPNs, primary SMTP and proxy addresses on users, groups, contacts and resources to the source onmicrosoft.com domain, then remove the domain from the source tenant. Use PowerShell for large tenants: the domain cannot be removed while anything still uses it.

Sign in with an admin account that is not on the domain. Use the commands below to find what still uses it, change each object as described in remove a domain from Microsoft 365, then select the domain on the Domains page and choose Remove domain.

Connect-ExchangeOnline
Get-Recipient -ResultSize Unlimited | Where-Object { $_.EmailAddresses -match "@contoso.com" } |
  Select-Object Name,RecipientTypeDetails,PrimarySmtpAddress

Connect-MgGraph -Scopes "User.Read.All"
Get-MgUser -All -Filter "endswith(userPrincipalName,'@contoso.com')" -ConsistencyLevel eventual -CountVariable c |
  Select-Object UserPrincipalName

Add and verify the domain in the target, then set it as the UPN and primary SMTP address for migrated users and groups.

Follow add a domain to Microsoft 365 and choose I'll add the DNS records myself so you control the MX change. Then update each migrated user, for example:

Connect-MgGraph -Scopes "User.ReadWrite.All"
Update-MgUser -UserId ana@fabrikam.onmicrosoft.com -UserPrincipalName ana@contoso.com

Connect-ExchangeOnline
Set-Mailbox -Identity ana@contoso.com -EmailAddresses @{add="SMTP:ana@contoso.com"}

Point MX, Autodiscover and SPF at the target.

Copy each value exactly as the target admin center shows it. Use change MX records for the MX change and set up an SPF record so you keep a single SPF record.

Resolve-DnsName contoso.com -Type MX
Resolve-DnsName autodiscover.contoso.com -Type CNAME
Resolve-DnsName contoso.com -Type TXT

Enable DKIM in the target and publish its selectors, and check DMARC.

Publish the two CNAME records the DKIM page shows for the domain, then turn on signing, as described in set up DKIM. Check the existing _dmarc record with set up DMARC.

Resolve-DnsName selector1._domainkey.contoso.com -Type CNAME
Resolve-DnsName _dmarc.contoso.com -Type TXT

Send internal and external test mail, run message traces, sign in as pilot users and make the go / no-go call against agreed criteria.

Select Start a trace for each test message. Record the results on the Go / no-go checklist.

Staff a support desk for Outlook profiles, OneDrive sync, MFA registration and missing permissions, and log every issue.

Give the desk the Outlook profile reset steps and the day-one guide, and log each call with the user, the symptom and the fix.

License migrated mailboxes inside the 30-day grace period, restamp Send on Behalf and other delegate permissions, and reapply holds and labels.

Assign licences as described in assign licences in Microsoft 365. Restamp Send on Behalf from the export you took before the move, for example:

Set-Mailbox sharedfinance@contoso.com -GrantSendOnBehalfTo @{add = "ana@contoso.com"}
Set-Mailbox ana@contoso.com -LitigationHoldEnabled $true

Remove migration batches and endpoints, organisation relationships, the migration app and secret, SharePoint trust (before source licences expire) and redirect sites once nobody relies on them.

Run the clean-up commands in each runbook: mailbox clean-up and OneDrive and SharePoint trust removal. Then select the migration app under App registrations and select Delete.

Get-MigrationBatch | Remove-MigrationBatch -Confirm:$false
Remove-MigrationEndpoint -Identity "T2T-Contoso"
Get-OrganizationRelationship | Format-Table Name,DomainNames,MailboxMoveEnabled

Agree how long the source stays for records and fallback. Remember the source mailbox is deleted after a cross-tenant move, so export anything the source organisation must retain before the move, not after.

If a mailbox must be retained, export it to PST before its batch completes. Record the agreed retention period and the closure date in the checklist.

Run a post-implementation review and hand runbooks and known issues to operations.

Attach the hypercare issue log and the final runbooks, and list any open issues with an owner.