Cross-tenant mailbox migration in now in Public Preview
Published Sep 22 2020 08:14 AM 63.4K Views
Microsoft

Historically, when an Exchange Online admin needed to move mailboxes from one tenant to another, the typical way to do that was to offboard the mailbox from the source tenant and import it into a target tenant.

 

Today, we are thrilled to announce the Public Preview of a built-in cross-tenant mailbox migration service that enables you to move mailboxes between tenants with minimal on-premises infrastructure dependencies (the new service eliminates some but not all on-premises components). The new cross-tenant mailbox migration service eliminates the need to offboard and onboard mailboxes, resulting in a faster and lower-cost migration. This is particularly beneficial for organizations undergoing mergers, acquisitions, divestitures, or splits.

 

The new move process includes enhanced security, as well as the ability to scope moves. It uses an Enterprise Application in Azure Active Directory (Azure AD) and Azure Key Vault, allowing tenant admins to manage both authorization and the scoping of mailbox migrations from one tenant to another. Cross-tenant mailbox migrations use an invitation and consent model to establish the Azure AD Enterprise Application used for authentication between tenants.

 

Prerequisites

Azure Key Vault is used to securely store and access the certificate/secret used to authorize and authenticate mailbox migration. For this reason, an Azure Key Vault subscription is required on the target tenant to perform cross-tenant mailbox migrations.

 

For the Public Preview, it is a recommended best practice to run the Microsoft-provided scripts with Global admin permissions to configure the Azure Key Vault storage and certificate, the move mailbox app, the migration endpoint, and the organization relationship.

 

In the source tenant, a mail-enabled security group is required prior to running setup. This group is used to scope the list of mailboxes that can move from the source tenant to the target tenant, which helps prevent unintended users from being moved.

 

You will also need the Tenant IDs for the source and target tenants, which you can find using these instructions.

 

Moving mailboxes

After setting up the necessary prerequisites, including tenant relationships and configuration settings, admins with the Move Mailbox management role can use the New-MigrationBatch cmdlet to move mailboxes between tenants. The move process performs the necessary tenant authorization checks, and in all cases, the admin of the target tenant initiates the move (which we refer to as a pull move), just like the on-premises to cloud migrations. Currently, all moves are triggered using PowerShell, but support for the Exchange admin center is coming soon.

 

Be sure to read this article (documentation available soon), which covers the necessary prerequisites, walks you through the steps needed to use perform cross-tenant mailbox migrations, and it details about the Microsoft-provided scripts on GitHub.

 

We’re excited to have you try out this new feature, and we’d love to hear your feedback. Let us know what you think!

81 Comments
Copper Contributor

Nice work! Can you please clarify why Outlook profile needs to be reconfigured once mailbox has been migrated to new tenant? Autodiscover process cannot use targetaddress to find the moved mailbox like for à traditional hybrid scenario ?

 

Thanks 

Copper Contributor

Mailbox guid changes so the profile won't reconnect.

Microsoft

Will this update the x500 addresses as well, so people will be able to reply to internal emails like they expect to?

Brass Contributor

Great Work. Thank you Microsoft Exchange Team.

Microsoft

Yes, the Outlook profile must be recreated post migration. AutoD will not redirect to the new tenant. This is a scenario we are investigating a solution for in a future release.

Microsoft

The mailbox guid on the target MailUser object pre migration should match that of the Mailbox in the source.

Microsoft

Yes, the X500 proxy is stamped on the source object post migration to support reply.

Iron Contributor

What I do not see within the documentation: What is the process in keep the primary SMTP Address. A domain can only be registered in one Tenant. How does this work during a tenant to tenant migration where we will have in both tenants mailboxes with the same primary SMTP Address domain?

Copper Contributor

Great !

Question : and all others services like Teams, Sharepoint, OneDrive ?

Copper Contributor

Great work! This is long expected!

 

I just gave the process a try and failing to migrate the mailboxes. Getting error - "MigrationTransientException: The call to 'https://bn8pr14mb2497.namprd14.prod.outlook.com/mrs/Microsoft.Exchange.MailboxReplicationService.Pro... OAuth' failed. Error details: Access is denied.. --> The call to 'https://bn8pr14mb2497.namprd14.prod.outlook.com/mrs/Microsoft.Exchange.MailboxReplicationService.Pro...' failed. Error details: Access is denied.. --> Access is denied." 

 

Any help would be greatly appreciated!

 

I was able run the source and tenant scripts successfully but had to make a few adjustments in the SetupCrossTenantRelationshipForTargetTenant script as detailed below:

Included AzureRM.Storage in the Import-AzureModules function as Get-AzureRmStorageAccount command failed without it.

Included the command "Enable-OrganizationCustomization" if the (Get-OrganizationConfig).IsDehydrated is True as New-OrganizationRelationship command fails if the tenant is Hydrated.

New-OrganizationRelationship command did not include the -OAuthApplicationId $appId parameter, so added that too.

 

Microsoft

Hi @daysey. Can you make sure the application id values on both the Org Rel and the migration endpoint match and are correct? If they are and you are still receiving this error, go ahead and send the details to our feedback alias:

Copper Contributor

Hi @Georgia Huggins, yes they match. I'll send you the details now. Thanks!

Microsoft

Hi @Peter Forster Post mailbox migration, the target address on the mailUser object will point to the migrated mailbox in the target tenant. If you need to take the domain from the source tenant and move it to the target, it will have to be removed from the source and given to the target during some sort of cut over window. I would also recommend viewing the Ignite presentation on these features at: https://techcommunity.microsoft.com/t5/video-hub/supporting-mergers-acquisitions-and-divestitures-in....

Microsoft

@Musa_Birkan I recommend watching this Ignite presentation for additional information on the other services: https://techcommunity.microsoft.com/t5/video-hub/supporting-mergers-acquisitions-and-divestitures-in...

Thanks!

Copper Contributor

Great feature get introduce as public preview ,waited for long time. 

Brass Contributor

I am unable to migrate a test mailbox based on this issue:

 

Error: MigrationPermanentException: One or more X500 proxy addresses or legacyExchangeDN of source mailbox are missing on target MEU as X500 proxy address. --> One or more X500 proxy addresses or legacyExchangeDN of source mailbox are missing on target MEU as X500 proxy address.

 

I have verified that the x500 address (there's only one) has been applied to the MEU object. Removed and reapplied but cannot get past this error which makes me think this may not actually be the issue.

 

Any ideas and what I can do to get past this?

 

Thanks,

 

-Scott

 

UPDATE:

 

Roman (crosstenantmigrationpreview@service.microsoft.com) investigated and pointed out what should have been obvious to me that I had not included ALL x500 addresses from Source tenant object. After adding the other x500 address, not just the LegacyExchangeDN, the mailbox was successfully migrated.

 

Thank you Roman!

Copper Contributor

@daysey , facing the very same issue. Initially thought it could be because of the various preparation and running the scripts. I redid the whole thing, prepared my batch and after a few minutes same as yours:

 

Error: MigrationTransientException: The call to 'https://gv0p278mb0115.chep278.prod.outlook.com/mrs/Microsoft.Exchange.MailboxReplicationService.ProxyService/OAuth' failed. Error details: Access is denied.. --> The call to 'https://gv0p278mb0115.chep278.prod.outlook.com/mrs/Microsoft.Exchange.MailboxReplicationService.ProxyService/OAuth' failed. Error details: Access is denied.. --> Access is denied.

 

Did you finally manage to go through it?

 

Thanks.

 

J.

Copper Contributor

@Joa_B, nope, no luck. I continued to get the same error and tried reaching out to support for help with no luck. So recreated everything in a prod tenant and now getting the same error as @Scott Barr 

 

I have a case open with MS and will update if I find a resolution to the issue.

Brass Contributor

@daysey  Please note the update to my post. Make sure you have the LegacyExchangeDN plus any additional x500 address. Many mailboxes have several x500 addresses in the Source tenant from multiple past migrations and the migration will not work until you match all x500 addresses between the Source and Target.

Also suggest using the crosstenantmigrationpreview@service.microsoft.com address instead of Support as they responded and resolved my issue on the same day.

 

Good luck!

Brass Contributor

@Georgia Huggins 

 

Thanks for this feature, nice to see you guys are working on it.

 

A note though: if the user has to change the PrimarySMTP domain, then it kinds of completely defeat the purpose in most migration scenarios.

 

When we acquired a company, we also acquired its identity and domain. We did a migration O365 > Exchange OnPremises with all the liberties we have OnPremises (so declaring their domain in AD / Exchange), and so were able to do it granularly and keep all the time their email domain (source and onprem target).

 

But here if you tell me they have to change their email (so basically forget their identity), then your tool can realistically only be used for one-shot full tenant migration, or I suppose very rare cases where an acquired company accepts to "lose" its identity.

 

Couldn't you at least find a way to declare the Source Tenant domain in Exchange (e.g. as Internal Relay)? So users would still keep their email address domain (same as you can do OnPremises), and us admins can do granular migrations without caring to have to migrate everything (Teams, OneDrive, etc) one shot.

Copper Contributor

@daysey 

 

I am facing the same issue. Have you found any solution?

Copper Contributor

Thanks @Scott Barr, I was able to complete the migration after adding all possible x500 addresses from the source user.

 

@Arjun_Rajan, which of the errors are you referring to? I experienced two different errors using separate tenants. Access denied error using trial tenants and x500 error using prod tenants.

Copper Contributor

Hi @daysey 

 

Facing the X500 issue, Even I added all X500 email address

Copper Contributor

Hey @Arjun_Rajan, did you make sure the Exchangeguid is same and legacyexchangeDN also added as an x500 on the MEU? I can send you the script I'm using if you want.

Brass Contributor

Hey @Scott Schnoll

 

I am testing this feature however I keep getting the below error with every migration batch

 

Error: 

Error: MigrationTransientException: The call to https://vi1pr05mb5647.eurprd05.prod.outlook.com/mrs/Microsoft.Exchange.MailboxReplicationService.Pro...' failed.

Error details: Access is denied.. --> The call to 'https://vi1pr05mb5647.eurprd05.prod.outlook.com/mrs/Microsoft.Exchange.MailboxReplicationService.Pro...' failed. Error details:

Access is denied.. --> Access is denied.

 

I have sent an email to 'crosstenantmigrationpreview@service.microsoft.com', hoping you or your team will be able to help me with this.

Microsoft

Do the migrated mail and meeting items keep the source smtps in their From/To/CC fields or are they rewritten to match the target domain?    I read Cross-tenant mailbox migration (preview) a couple of times but couldn't find this called out.   Thanks!

Copper Contributor

Question - Upon migration completion, when the MailUser is assigned a mailbox (and converted from a MailUser) how is the user given an o365 licence to operate?

 

Copper Contributor

When running the script for the preparation of the target tenant I receive "Please enter the key vault url for the migration app's secret". Any ideas as of why this is happening? I do have a key vault subscription.

Thanks

Copper Contributor

Hey @ApoorvaKasbekar

 

Did you solve your issue?

I've same issue:

 

Error: MigrationTransientException: The call to 'https://pa4pr06mb7197.eurprd06.prod.outlook.com/mrs/Microsoft.Exchange.MailboxReplicationService.Pro...' failed. Error details: Access is denied.. --> The call to 'https://pa4pr06mb7197.eurprd06.prod.outlook.com/mrs/Microsoft.Exchange.MailboxReplicationService.Pro...' failed. Error details: Access is denied.. --> Access is denied.
 
Copper Contributor

Thanks ms for the great feature. 

Successful completed t2t migration of 500 mailboxes.

 

Copper Contributor

@Sjaak null check whether mailbx move permissions hasbeen applied in source tenant.

I faced the same problem. When we are preparing the destination tenant it will trigger mail to source destination mailadmin id when we click on the its not applying req permissions dont know y. 

Work around is copy the link(it is generated in powershell when we are preparing the dest tenant) pasted it in private browser and sign in with the source global admin creds

 

Copper Contributor

Thanks @Kiran2150 : did the trick for us !

 

We now run into a weird situation.

I created a test MailboxUser on source tenant, prepared a MailUser accordingly on the federated target tenant.

I just sent and received a couple of mails, added an appointment and sent an invitation to populate the mailbox a bit.

When I launch the cross-tenant migration for that user, I run in the following error :

 

Error: MigrationPermanentException: Source mailbox 'Tests TECHNIQUES' contains unsupported mailbox location(s) - ComponentShared. Cross tenant moves support only moving Primary mailbox, or Primary + Archive mailbox. Please remove unsupported mailbox location(s) and try again. --> Source mailbox 'Tests TECHNIQUES' contains unsupported mailbox location(s) - ComponentShared. Cross tenant moves support only moving Primary mailbox, or Primary + Archive mailbox. Please remove unsupported mailbox location(s) and try again.

It basically states that the source Mailbox containe one or multiple ComponentShared mailbox locations and that those cannot be moved within a cross-tenant migration.

 

Problem is this Mailbox only have one primary location and no ComponentShared one :

 

MailboxLocations                          : {1;7f6f523c-c8ac-4321-b964-c56e46bd1876;Primary;FRAP264.PROD.OUTLOOK.COM;d5d70b4e-d1af-4a55-9550-763722395a2b}

I tried to run the migration batch with option -PrimaryOnly but it fails stating a parameter issue.

 

Does anybody have any idea what I could try now ? I've jumped in so many hoops to get that far and now I feel really clueless and don't know where to go from there...

 

Brass Contributor

Sjaak null ensure the Admin has consented to the app in the source tenant 

Copper Contributor

Finally we have native functionality! Thank you Team!

Copper Contributor

Hi,

 

The migration fails with: "Your organization does not authorize 'pull' or Inbound moves from the remote organization. Contact your administrator to confirm organization relationships are configured correctly."

 

After digging I found that I have set the wrong ResourceTenantId when running SetupCrossTenantRelationshipForTargetTenant.ps1.

 

This resulted in wrong tenant id in the Organization relationship DomainNames property.

 

Changed it with 

Set-OrganizationRelationship -Identity [RelationshipId] -DomainNames [CorrectResourceTenantID]

 

Works! :)

Copper Contributor

Hello,

 

I am having the same error: 

MigrationTransientException: The call to 'https://ph0pr01mb6264.prod.exchangelabs.com/mrs/Microsoft.Exchange.MailboxReplicationService.ProxyService/OAuth' failed. Error details: Access is denied
My setup has been validated by Microsoft 365 Support. They did not find any problem with my cross-tenant configuration (OAuthApp, KeyVault, Cert, Org Relationships, Tenant Targeted Releases).
I have matching x500 and LegacyExchangeDN. I have no additional X500.

I have matching ExchangeGUIDs and correct External Address/Target Address from the source tenant.  

 

Could you please help me?

 

Thank you

Copper Contributor

After migration is complete the Source tenant Mailbox is converted to Mailuser.

 

Is there an option to keep the source as a Mailbox, and may be configure a forwarder.

 

Our organization requires keeping the mailboxes for 7 years. This is Ok when the user is deleted, as the mailbox remains as InactiveMalbox according the retention policy. Thus we can do Contents searches, etc.

 

When converted to a MailUser we no longer can do content searches in the source tenant.

Copper Contributor

Just FYI, I also saw the issue mentioned by others in this thread:

.../Microsoft.Exchange.MailboxReplicationService.ProxyService/OAuth' failed. Error details: Access is denied.. --> Access is denied.

 

In my case I think it was related to creating the cross-tenant migration using the old EAC. After a more close read of the guide I found the clear instructions to use PowerShell or the new EAC to generate the cross-tenant migration. Using the new EAC made the migration batch complete successfully.

 

RTFM... :)

Copper Contributor

Hello Teams 

 

Facing the same issue mrs/Microsoft.Exchange.MailboxReplicationService.ProxyService/OAuth‎' failed. Error details: Access is denied.. --> Access is denied.

 

Created migration batch using PowerShell 

X500 and legacyexchangedn is updated 

Exchange guid is updated 

 

Can someone please help me to fix this issue 

 

Copper Contributor

I have also the problem with the missing X500 address on the target mailuser.  After manualy adding the x500 address the migration works for the testuser. 

 

Error: MigrationPermanentException: One or more X500 proxy addresses or legacyExchangeDN of source mailbox are missing on target MEU as X500 proxy address. --> One or more X500 proxy addresses or legacyExchangeDN of source mailbox are missing on target MEU as X500 proxy address.

 

Has someone already a script adding the missing X500 address to the target mailuser.

 

thank you

Copper Contributor

Like quite a few other people in this page I experienced the error:

Microsoft.Exchange.MailboxReplicationService.ProxyService/OAuth‎' failed. Error details: Access is denied

 

In my case it turned out to be caused by the fact that the source tenant admin used insufficient credentials when acknowledging the creation of the migration enterprise application in his tenant.

 

It took some time to troubleshoot this and would have been easier with these two suggested changes to the process/documentation:

 

1. When opening the tenant application creation link and clicking accept there is no feedback whether the operation was successful or not. It just redirects to a standard Microsoft page. This means source tenant admin is unaware if the migration application was created in his tenant or not.

2. The validation steps should include to check in the Azure AD portal that the enterprise application used by the migration has been created and that required permissions on MS Graph and Exchange Online have been assigned. Only steps to validate the creation of the organization relationship are listed in the check list.

 

Otherwise, seems to work well, thank you.

Copper Contributor

Hello, I'm wondering how folks are pre-creating the MEU's in the target?

I've tried using the code included in the FAQ section of the Preview document, but it fails - it seems as if that code is expecting a different version of the NEW-MAILUSER cmdlet. For a while I was getting "Parameter set cannot be resolved using the specified named parameters" even though i was only using the params specified in MS's sample code. After this i tried omitting the -UserPrincipalName parameter and -SamAccountName parameter because the version of NEW-MAILUSER i have in scope after Connect-ExchangeOnline does not accept either of those parameters.

Is the sample code working for others? Does anyone have another script to do this critical task?

Copper Contributor

@monadnomad I can send you the script I used if that works for you. You can provide an email to send it to.

Copper Contributor

@daysey, yes, please. You can mail me at dan at transact dot com. TIA

Copper Contributor

Hello @Georgia Huggins

Early in this thread you asked @daysey  "Can you make sure the application id values on both the Org Rel and the migration endpoint match and are correct?"

 

Are you talking about the output of Get-OrganizationRelationship? I find that the names do not match as so:

Target Side
     Name                  : target_source_2408
     DomainNames           : {cc6c2838-b662-4f22-8bb1-7b3e98e4efdd}
     MailboxMoveEnabled    : True
     MailboxMoveCapability : Inbound
     
Source Side
     Name                  : target_source_2828
     DomainNames           : {cc6c2838-b662-4f22-8bb1-7b3e98e4efdd}
     MailboxMoveEnabled    : True
     MailboxMoveCapability : RemoteOutbound

Is this related to the OAuth errors that are blocking our progress?

 

(If, OTOH, you mean the GUID for the Azure application, I checked and they DO match on both the source and target.)

Copper Contributor

@daysey, after a little tweaking to support my environment your script worked a treat. Props, friend!  I truly appreciate you sharing.

 

Still fighting with the OAuth errors a number of folks have experienced. I found that the OAuthApplicationId for my OrganizationRelationship was blank, so I set it to match the ApplicationId in my MigrationEndpoint.

 

Error: MigrationTransientException: The call to 'https://bn6pr0101mb2945.prod.exchangelabs.com/mrs/Microsoft.Exchange.MailboxReplicationService.Proxy...' failed. Error details: Access is denied.. --> The call to 'https://bn6pr0101mb2945.prod.exchangelabs.com/mrs/Microsoft.Exchange.MailboxReplicationService.Proxy...' failed. Error details: Access is denied.. --> Access is denied.

Copper Contributor

Cross-Tenant Mailbox Migration OAuth Errors: a lesson learned

 

TLDR: make certain you paste the correct Tenant GUID (SOURCE vs TARGET)

 

It turned out we had the wrong GUID in TWO places and this double error was confounding troubleshooting.

  • First Error: wrong GUID set in the Organization Relationship

The output of (Get-AzureADTenantDetail).ObjectId on the TARGET should match the output of (Get-OrganizationRelationship).DomainNames on the SOURCE tenant.

If not, Set it on the SOURCE relationship side. (Please don't try to change it on your target AzAD side.)

  • Second Error: wrong GUID used when calling VerifySetup.ps1 on the source side. This prevented the script from detecting the first error.

When you run the verify script on the SOURCE, erroneously using the SOURCE GUID instead of the TARGET GUID, it may tell you that all tests are Passed, even if the Organization Relationship is not correct.

 

I hope this helps somebody.

 

Big Thanks to Roman for bringing fresh eyes to the case and pointing out the problem.

Copper Contributor

Hello,

 

I am having the same error: 

MigrationTransientException: The call to

Status: Syncing
Data migrated:
Migration rate:
Error: MigrationTransientException: The call to 'https://lo0p265mb3180.gbrp265.prod.outlook.com/mrs/Microsoft.Exchange.MailboxReplicationService.Prox...' failed. Error details: Access is denied.. --> The call to 'https://lo0p265mb3180.gbrp265.prod.outlook.com/mrs/Microsoft.Exchange.MailboxReplicationService.Prox...' failed. Error details: Access is denied.. --> Access is denied.
Last successful sync date:
Data consistency score:

I have matching ExchangeGUIDs and correct External Address/Target Address from the source tenant.  

 

Thank you

Copper Contributor

@Kunjal Amin , this one solved it for me:

Check in the Azure AD portal of the source tenant that the enterprise application used by the migration has been created and that required permissions on MS Graph and Exchange Online have been assigned:

  1. Open up Azure AD portal -> Azure AD -> Enterprise Applications
  2. You should see an application named something like [target tenant]_Friends_[source tenant][some number] - e.g. contoso_Friends_wingtip_2198
  3. Check that proper permissions are assigned to the enterprise application:
    • Microsoft Graph: Read and Write directory data 
    • Office 365 Exchange Online: Move mailboxes between organizations

 

In general run the checks listed in the article (the above check is not included for some reason).

 

Apart from this obvious pitfalls are:

Ensure ALL X500 alias'es are copied from source mailboxes to target mailboxes. Copying the legacyExchangeDN won't cut it.

Ensure ALL mailbox users are added to your migration group.

 

Hope this helps.

Morten

Easy Office 365 Management: https://easy365manager.com

 

PS - Lessons learned: This article does NOT address how to handle Office 365 (unified) groups, Teams, SharePoint/OneDrive. Check the scope of this in the source tenant!

 

Copper Contributor

Hello,

 

I am running into an error with the initial setup scripts. We have run both Target and Source scripts. No errors popped up during that process. We also had no issue with the consent links. We ran the verification scripts after and it gave us errors. 

 

Target side

Verifying AAD application ....Passed

Verifying Keyvault .....Passed

Verifying OrganizationRelationship .....Passed

Verifying MigrationEndoint .....Passed

 

Then it relists them again and says "errors"

 

Source side

Verifying AAD Application .....Passed

Verifying OrganizationRelationship .....Failed

 

I am not sure what to do at this point. Any assistance would be much appreciated. Thanks.

Co-Authors
Version history
Last update:
‎Feb 07 2023 04:29 PM
Updated by: