{"id":381,"date":"2022-04-02T12:33:59","date_gmt":"2022-04-01T23:33:59","guid":{"rendered":"https:\/\/www.howdoiuseacomputer.com\/?p=381"},"modified":"2022-10-04T11:00:36","modified_gmt":"2022-10-03T22:00:36","slug":"microsoft-365-cross-tenant-migration","status":"publish","type":"post","link":"https:\/\/www.howdoiuseacomputer.com\/index.php\/2022\/04\/02\/microsoft-365-cross-tenant-migration\/","title":{"rendered":"Microsoft 365 cross-tenant migration"},"content":{"rendered":"\n

Hello! Long time no\u2026 🍻😊🍻<\/p>\n\n\n\n

I thought I would share<\/strong> some PowerShell I used during a recent cross-tenant migration. Firstly, the Microsoft documentation is really good and got the journey off to a good start:<\/p>\n\n\n\n

https:\/\/docs.microsoft.com\/en-us\/microsoft-365\/enterprise\/cross-tenant-mailbox-migration?view=o365-worldwide<\/a><\/p>\n\n\n\n

PLEASE NOTE:<\/strong> Following is some fairly raw PowerShell. You can’t just press Go! You’ll need to understand and update the bits required and run accordingly! Hopefully everything that requires updating is in bold-italics<\/em><\/strong>. If not please punish me via comment! =)<\/p>\n\n\n\n

That said… let’s continue 😃:<\/p>\n\n\n\n

Firstly, let’s create a mail-enabled security group <\/strong>in the source<\/em> tenant Exchange Admin console, ‘zzMigUsers@sourcedomain<\/strong><\/em>.com’ should do the trick! ..then add the users (mailboxes) you will migrate (the migration endpoint is scoped to a group, anyone not in the group will fail to migrate). <\/p>\n\n\n\n

Now load PowerShell ISE <\/strong>and paste all of the below code bits in, then save it for later. First, we need our commands to be able to switch quickly between tenants (disconnect before connecting each time):<\/p>\n\n\n\n

# Source tenant\nConnect-ExchangeOnline -UserPrincipalName migadmin@sourcedomain.com<\/em><\/strong>\n# Target tenant\nConnect-ExchangeOnline -UserPrincipalName migadmin@targetdomain.com<\/em><\/strong>\n# Disconnect from tenant\nDisconnect-ExchangeOnline -Confirm:$false\n<\/code><\/pre>\n\n\n\n
# connect to target tenant here\n# Enable customization if tenant is dehydrated\n  $dehy = Get-OrganizationConfig | fl isdehydrated\n  if ($dehy -eq $true) {Enable-OrganizationCustomization}\n\n# Create Migration Endpoint in target tenant\n$AppId = \"paste the app id here<\/strong><\/em>\"\n$Credential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $AppId, (ConvertTo-SecureString -String \"paste the app secret here<\/strong><\/em>\" -AsPlainText -Force)\nNew-MigrationEndpoint -RemoteServer outlook.office.com -RemoteTenant \"sourcedomain<\/strong><\/em>.onmicrosoft.com\" -Credentials $Credential -ExchangeRemoteMove:$true -Name \"SourceDomain<\/strong><\/em>MigEndpoint\" -ApplicationId $AppId\n\n# Create Org Relationship in target tenant\n$sourceTenantId=\"paste source tenant id here<\/strong><\/em>\"\n$orgrels=Get-OrganizationRelationship\n$existingOrgRel = $orgrels | ?{$_.DomainNames -like $sourceTenantId}\nIf ($null -ne $existingOrgRel)\n{\n    Set-OrganizationRelationship $existingOrgRel.Name -Enabled:$true -MailboxMoveEnabled:$true -MailboxMoveCapability Inbound\n}\nIf ($null -eq $existingOrgRel)\n{\n    New-OrganizationRelationship \"SourceDomain<\/strong><\/em>OrgRel\" -Enabled:$true -MailboxMoveEnabled:$true -MailboxMoveCapability Inbound -DomainNames $sourceTenantId\n}<\/code><\/pre>\n\n\n\n
Let’s use our disconnect \/ connect<\/strong> commands above to disconnect from the target <\/em>tenant and connect to the source <\/em>tenant to set up the other side: <\/p>\n\n\n\n
# connect to source tenant here\n\n# Configure OrgRel in source tenant\n$targetTenantId=\"insert the target tenant ID here<\/em><\/strong>\"\n$appId=\"insert the app id here<\/em><\/strong>\"\n$scope=\"zzMigUsers@sourcedomain<\/strong><\/em>.com\"\n$orgrels=Get-OrganizationRelationship\n$existingOrgRel = $orgrels | ?{$_.DomainNames -like $targetTenantId}\nIf ($null -ne $existingOrgRel)\n{\n    Set-OrganizationRelationship $existingOrgRel.Name -Enabled:$true -MailboxMoveEnabled:$true -MailboxMoveCapability RemoteOutbound -OAuthApplicationId $appId -MailboxMovePublishedScopes $scope\n}\nIf ($null -eq $existingOrgRel)\n{\n    New-OrganizationRelationship \"targetdomain<\/em><\/strong>OrgRel\" -Enabled:$true -MailboxMoveEnabled:$true -MailboxMoveCapability RemoteOutbound -DomainNames $targetTenantId -OAuthApplicationId $appId -MailboxMovePublishedScopes $scope\n}<\/code><\/pre>\n\n\n\n
Hopefully you got to this point without issue <\/strong>– if not let me know in the comments section and I’ll try to help!  Next, we should be getting a successful test of what we have set up.  Run this command since you are still connected to the source tenant – you should see the expected values returned:<\/p>\n\n\n\n
# Confirm OrgRel in Source tenant\nGet-OrganizationRelationship | fl name, DomainNames, MailboxMoveEnabled, MailboxMoveCapability<\/code><\/pre>\n\n\n\n
Now, disconnect and connect <\/strong>to the target<\/em> tenant again, and run this:<\/p>\n\n\n\n
# Confirm OrgRel and MigEndpoint in Target tenant\nGet-MigrationEndpoint\nGet-OrganizationRelationship | fl name, DomainNames, MailboxMoveEnabled, MailboxMoveCapability\nTest-MigrationServerAvailability -Endpoint \"SourceDomain<\/em><\/strong>MigEndpoint\"<\/code><\/pre>\n\n\n\n
Awesome, green lights!? <\/strong> The tenants are configured.  Now disconnect \/ connect to the source <\/em>tenant, we’ll need to get the following details out into a CSV file so we can create the MailUser objects in the target tenant (yes I know we could have done that earlier =)).  Limit this if required based on the group we created earlier, scoped to your migration users.  <\/p>\n\n\n\n
# get source mailbox details\nGet-Mailbox | select DisplayName, UserPrincipalName, PrimarySMTPAddress, ExchangeGUID, ArchiveGUID, LegacyExchangeDN | Export-Csv C:\\temp\\sourceusers.csv -NoTypeInformation\n<\/code><\/pre>\n\n\n\n
Disconnect \/ connect to the target <\/em>tenant again.  We want to test one user first, so I used these commands (replace bold italic with values for one user from the CSV output):<\/p>\n\n\n\n
# create MailUsers in target tenant - ONE AT A TIME HERE OR BELOW FOR BATCHES\n$originalalias = 'sales<\/em><\/strong>'\n$newalias = 'sourcedomain<\/strong><\/em>.sales'\n$userdisplayname = 'sourcedomain <\/em><\/strong>Sales Department'\n$exchguid = '80ddefd4-26cb-7621-c497-g6c044b04dd9<\/strong><\/em>'\n$archguid = '70edegc5-36f8-8639-b287-f6g035408ec2<\/strong><\/em>'\n$x500address = 'x500:\/o=ExchangeLabs\/ou=Exchange Administrative Group (FYDIBOHF23SPDLT)\/cn=Recipients\/cn=ce04185c5ff841f885d660e46e6c8bc5-sourcedomain SAL<\/em><\/strong>'\n$usersourceaddress = $originalalias + \"@sourcedomain<\/em><\/strong>.onmicrosoft.com\"\n$usertargetaddress = $newalias + \"@targetdomain<\/em><\/strong>.com\"\n$usertargettenantaddress = $newalias + \"@targetdomain<\/em><\/strong>.onmicrosoft.com\"\nNew-MailUser -Name $newalias -DisplayName $userdisplayname -ExternalEmailAddress $usersourceaddress -MicrosoftOnlineServicesID $usertargetaddress -Password (ConvertTo-SecureString -String 'Hellosourcedomain2099<\/em><\/strong>' -AsPlainText -Force)\nSet-MailUser $usertargetaddress -ExchangeGuid $exchguid -ArchiveGuid $archguid -PrimarySmtpAddress $usertargetaddress\nSet-MailUser $usertargetaddress -EmailAddresses @{Add=\"$x500address\",\"$usertargettenantaddress\"}\nSet-MailUser $usertargetaddress -EmailAddresses @{Remove=\"smtp:$usersourceaddress\"}<\/code><\/pre>\n\n\n\n
Then we can migrate the user:<\/p>\n\n\n\n
New-MigrationBatch -Name testbatch -SourceEndpoint 'sourcedomain<\/em><\/strong>MigEndpoint' -UserIds $usertargetaddress -Autostart -TargetDeliveryDomain 'targetdomain<\/em><\/strong>.onmicrosoft.com'<\/code><\/pre>\n\n\n\n
NOTE:<\/strong>  Recently I found this command was not working and I had to use a one-liner copy of the batch1-users.csv mentioned below.  After the test user is successfully migrated, reference your original file with all the mailboxes in it.  Just in case you get this issue in your scenario 😃   <\/p>\n\n\n\n
Okay!  When this is working<\/strong> and we are confident all is well, copy the sourceusers.csv to a new file named batch1-detail.csv. Open the file and add three columns before DisplayName as below. ‘originalalias’ (the bit before the UPN), ‘newalias’ (set as needed for the target tenant) and ‘newupn’ (new UPN in the target tenant):<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
Assuming the file is called batch1-detail.csv<\/strong>, create another CSV called batch1-users.csv<\/strong>.  This is the input for the migration batch command (very simple and worked well for me), just copy the target UPNs from batch1-detail.csv<\/strong> into the EmailAddress column and populate the other columns as below:<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
Now you can use this code to create the MailUser objects with the batch1-detail.csv file:<\/p>\n\n\n\n
# TO DO BATCHES\n# UPDATE THESE CORRECTLY - set variables and import csv\n$csv = Import-Csv C:\\temp\\sourcedomain<\/strong><\/em>\\batch1-detail.csv<\/em><\/strong>\n\nforeach ( $line in $csv ) {\n\n$originalalias = $line.OriginalAlias\n$newalias = $line.NewAlias\n$newupn = $line.NewUPN\n$userdisplayname = $line.DisplayName\n$exchguid = $line.ExchangeGuid\n$archguid = $line.ArchiveGuid\n$x500address = \"X500:\" + $line.LegacyExchangeDN\n$usersourceaddress = $originalalias + \"@sourcedomain<\/em><\/strong>.onmicrosoft.com\"\n$usertargetaddress = $newupn\n$usertargettenantaddress = $newalias + \"@targetdomain<\/em><\/strong>.onmicrosoft.com\"\n\nWrite-Host\nWrite-Host -ForegroundColor Green \"Processing $usertargetaddress...\"\nWrite-Host\n\nNew-MailUser -Name $newalias -DisplayName $userdisplayname -PrimarySmtpAddress $usertargetaddress -ExternalEmailAddress $usersourceaddress -MicrosoftOnlineServicesID $usertargetaddress -Password (ConvertTo-SecureString -String 'Hellosourcedomain2099<\/em><\/strong>' -AsPlainText -Force)\nSet-MailUser $usertargetaddress -ExchangeGuid $exchguid -ArchiveGuid $archguid -PrimarySmtpAddress $usertargetaddress\nSet-MailUser $usertargetaddress -EmailAddresses @{Add=\"$x500address\",\"$usertargettenantaddress\"}\nSet-MailUser $usertargetaddress -EmailAddresses @{Remove=\"smtp:$usersourceaddress\"}\nGet-MailUser $usertargetaddress | fl DisplayName,PrimarySMTPAddress,ExchangeGuid,ArchiveGuid\n}<\/code><\/pre>\n\n\n\n
Now we’ve created the MailUser objects for our batch, we can migrate them using the second file:<\/p>\n\n\n\n
# create migrationbatch using csv\n$batchfile = 'C:\\temp\\sourcedomain\\batch1-users.csv<\/em><\/strong>'\n\nNew-MigrationBatch -Name $batchname -SourceEndpoint 'sourcedomain<\/em><\/strong>MigEndpoint' -CSVData ([System.IO.File]::ReadAllBytes(\"$batchfile\")) -Autostart -TargetDeliveryDomain 'targetdomain<\/em><\/strong>.onmicrosoft.com'<\/code><\/pre>\n\n\n\n
NOTE:<\/strong> At this point you are migrating the mailboxes because of the “-Autostart” switch.  Users in the batch will have ‘Syncing’ status.  When ready to complete they will be ‘Synced’.  <\/p>\n\n\n\n
You can run this command to check the status of a batch:<\/p>\n\n\n\n
# Get status of a migration batch:\nGet-MigrationBatch $batchname | fl<\/code><\/pre>\n\n\n\n
 Or this to check status of a single user:<\/p>\n\n\n\n
# Get details for a single mailbox\nGet-MigrationUser 'insertupnhere' | Get-MigrationUserStatistics | fl<\/code><\/pre>\n\n\n\n
Or this to get the status of all migration users, updated every 5 minutes:<\/p>\n\n\n\n
# output progress of all users every 5 mins\n$x = 0\nDo{\n$x = $x + 1\nGet-MigrationUser | Get-MigrationUserStatistics\n\nStart-Sleep -Seconds 300\n}\nUntil ( $x -eq 480 )<\/code><\/pre>\n\n\n\n
When the mailboxes in a batch have ‘Synced’ status, go ahead and complete the batch using this command: <\/p>\n\n\n\n
# Complete a Synced batch\nComplete-MigrationBatch $batchname -Confirm:$false<\/code><\/pre>\n\n\n\n
This can take a bit of time so have a beer or cup of tea then come back – done!  Once completed the mailuser you created in the target tenant will become a mailbox, and the mailbox in the source tenant will become a mailuser with a forwarding address set to the users target onmicrosoft.com address 👍 <\/p>\n\n\n\n
Some other commands I used are:<\/p>\n\n\n\n
# Restart a failed batch\n## Start-MigrationBatch $batchname\n\n# remove a completed batch\n## Remove-MigrationBatch $batchname -Confirm:$false\n\n# Remove failed users from batches due to failure\n## Get-MigrationUser | ? { $_.status -eq 'failed' } | Remove-MigrationUser -Confirm:$false<\/code><\/pre>\n\n\n\n
This migration went really smoothly… once the user was migrated, the forwarding was set correctly in the source tenant, and permissions were intact for access to Shared Mailboxes etc.  Now we are planning to tidy up and move additional email aliases, the accepted domains and MX records across to the new tenant… I’m impressed with how relatively easy this was!<\/p>\n\n\n\n
Until next time… ‘Hei kone ra’ from New Zealand Aotearoa! 🍻😜<\/p>\n\n\n\n
 <\/p>\n
<\/div>
<\/g><\/svg><\/i> \"Loading\"<\/p>
<\/div>","protected":false},"excerpt":{"rendered":"
Hello! Long time no\u2026 🍻😊🍻 I thought I would share some PowerShell I used during a recent cross-tenant migration. Firstly, the Microsoft documentation is really good and got the journey off to a good start: https:\/\/docs.microsoft.com\/en-us\/microsoft-365\/enterprise\/cross-tenant-mailbox-migration?view=o365-worldwide PLEASE NOTE: Following is some fairly raw PowerShell. You can’t just press Go! You’ll need to understand and update […]<\/p>\n
<\/div>\n
<\/g><\/svg><\/i> \"Loading\"<\/p>\n
<\/div>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_monsterinsights_skip_tracking":false,"_monsterinsights_sitenote_active":false,"_monsterinsights_sitenote_note":"","_monsterinsights_sitenote_category":0,"site-sidebar-layout":"default","site-content-layout":"","ast-site-content-layout":"","site-content-style":"default","site-sidebar-style":"default","ast-global-header-display":"","ast-banner-title-visibility":"","ast-main-header-display":"","ast-hfb-above-header-display":"","ast-hfb-below-header-display":"","ast-hfb-mobile-header-display":"","site-post-title":"","ast-breadcrumbs-content":"","ast-featured-img":"","footer-sml-layout":"","theme-transparent-header-meta":"","adv-header-id-meta":"","stick-header-meta":"","header-above-stick-meta":"","header-main-stick-meta":"","header-below-stick-meta":"","astra-migrate-meta-layouts":"default","ast-page-background-enabled":"default","ast-page-background-meta":{"desktop":{"background-color":"var(--ast-global-color-4)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"tablet":{"background-color":"","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"mobile":{"background-color":"","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""}},"ast-content-background-meta":{"desktop":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"tablet":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"mobile":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""}},"footnotes":""},"categories":[8,9],"tags":[13,70,97,24,72,76,16,71,99,98],"class_list":["post-381","post","type-post","status-publish","format-standard","hentry","category-powershell","category-ramblings","tag-13","tag-cross-tenant","tag-cross-tenant-mailbox-migration-step-by-step","tag-exchange","tag-how-to","tag-mailbox","tag-microsoft","tag-migration","tag-online","tag-step-by-step"],"post_mailing_queue_ids":[],"_links":{"self":[{"href":"https:\/\/www.howdoiuseacomputer.com\/index.php\/wp-json\/wp\/v2\/posts\/381"}],"collection":[{"href":"https:\/\/www.howdoiuseacomputer.com\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.howdoiuseacomputer.com\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.howdoiuseacomputer.com\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.howdoiuseacomputer.com\/index.php\/wp-json\/wp\/v2\/comments?post=381"}],"version-history":[{"count":8,"href":"https:\/\/www.howdoiuseacomputer.com\/index.php\/wp-json\/wp\/v2\/posts\/381\/revisions"}],"predecessor-version":[{"id":412,"href":"https:\/\/www.howdoiuseacomputer.com\/index.php\/wp-json\/wp\/v2\/posts\/381\/revisions\/412"}],"wp:attachment":[{"href":"https:\/\/www.howdoiuseacomputer.com\/index.php\/wp-json\/wp\/v2\/media?parent=381"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.howdoiuseacomputer.com\/index.php\/wp-json\/wp\/v2\/categories?post=381"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.howdoiuseacomputer.com\/index.php\/wp-json\/wp\/v2\/tags?post=381"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}
Now we can connect to the target tenant and create the Org Relationship and Migration Endpoint – you’ll need the ‘sourcedomain<\/em><\/strong>‘, app ID<\/em><\/strong> and secret<\/em><\/strong> to paste in here where the bold italics are (follow the MS article to set up the App Registration and Enterprise App, easy as!): Target tenant app setup<\/a>.<\/p>\n\n\n\n