Cross-tenant SharePoint migration lives or dies on identity mapping

Move a SharePoint site to another tenant and the files arrive intact — but every permission on them points at users who do not exist in the new tenant, so unless you mapped those identities first, the content lands locked.

New to cloud? CAMPUX is a free, build-first course. Start here →

SharePoint tenant to tenant migration moves whole sites from one Microsoft 365 tenant to another using SharePoint Online PowerShell, without the content leaving the Microsoft cloud. Files, versions, and metadata carry. Permissions only re-attach for the users you mapped first with cross-tenant identity mapping. And here is the part the other guides skip: the feature is sold to Enterprise Agreement customers by the 100 GB, so whether you can use it at all is a purchasing question before it is a technical one.

Two companies merge. One has to give up its tenant, and its SharePoint sites need to move into the other. This is part of the broader Azure tenant-to-tenant migration problem, and SharePoint is the piece where people get surprised. Microsoft's cross-tenant SharePoint migration — the same thing people search for as SharePoint tenant to tenant migration — moves sites from one tenant to another using SharePoint Online PowerShell, and the detail that makes it attractive is that the content never leaves the Microsoft 365 cloud during the move. When a site finishes, a redirect is left in the original location so existing links keep working. The files copy over fine. What trips teams up is who can open them afterward.

First question: can you use this feature at all

Answer this before you plan anything. The Cross-Tenant Shared Data Migration feature and its licenses are available to Enterprise Agreement customers only, and you buy them through your Microsoft account team. Licenses are priced per 100 GB of data moved, so the size of the purchase falls out of how much SharePoint storage you are actually moving. Microsoft allows a grace of 20 percent on top, in case the sites grow between sizing and cutover.

Size it by summing the storage used across the sites in scope. In SharePoint Online PowerShell that is Get-SPOSite -Limit <String> | Select-Object Url, StorageUsageCurrent, which returns bytes. Add up the sites you plan to move, divide by 100 GB, add the headroom, and you have the number to take to your account team.

If you are not an Enterprise Agreement customer, this native path is closed to you and no amount of PowerShell opens it. Your route is a third-party migration product instead — see the tooling choices for cross-tenant migration and where third-party tools beat the native ones. Decide this early. Teams that discover the licensing gate two weeks before cutover lose the two weeks.

Why identity mapping is the whole game

A permission on a SharePoint file is a pointer to a user or group. When you move that file to a new tenant, the pointer still names a user from the old tenant — an identity the target has never heard of. There is nothing for the permission to re-attach to. Cross-tenant identity mapping is the step that fixes this: it establishes a one-to-one relationship between each source user and their corresponding account in the target, so the migration knows that "Adele from the old tenant" is "Adele in the new tenant." Do that first, and permissions re-attach on the way in. Skip it, and every access entry for an unmapped user is dropped, because the person it referred to does not exist on the target side.

Files carry themselves. Permissions do not — they only survive if you have already told the target which new user each old one became.

Microsoft is explicit about the dependency. Users with permissions to a site keep their access after the move only if those users and groups were accounted for in the identity mapping step. That single sentence is the difference between a clean cutover and a support queue full of "I can't get into anything."

How you build the identity map, and the cmdlet that uploads it

For SharePoint the identity map is a file you build yourself: a single CSV listing every user and group on the source alongside the account that replaces it on the target. There is a strict one-to-one rule. You cannot map one source user to several target users, so if an administrator owns several source sites, that ownership has to be reassigned to the real people before you start — anything left pointing at a doubled-up account does not migrate.

The file has six columns and no header row. The first three describe the source — the literal word User or Group, the source tenant ID, and the source user principal name (or the group object ID). The last three describe the target: the target user principal name, the target email address, and the user type. Groups follow the same shape with their own object IDs, and Microsoft 365 groups carry the group alias in the fifth column. Users and groups live in the same file. The tenant ID comes from the Properties blade of Microsoft Entra ID in each tenant.

The SharePoint administrator on the target tenant then uploads it with Add-SPOTenantIdentityMap -IdentityMapPath <identitymap.csv>, and the mapping is applied automatically as each migration runs. Close the file before you upload it or the cmdlet fails on a file lock. To check what the service holds for one person, run Get-SPOTenantIdentityMappingUser -Field SourceUserKey -Value <upn>.

Three traps are worth naming. Every upload replaces the map already there, so any revision has to contain everyone you still intend to migrate, not just the people who changed — and you upload again every time the file changes, or the migration runs on the old version. For a group-connected site the target URL must match the alias of the new group on the target, or that migration fails. And this file is the SharePoint half of the job only: mailboxes are a separate exercise with its own tool, Cross-Tenant Identity Mapping, whose PowerShell module writes Exchange attributes such as ExchangeGuid and LegacyExchangeDN onto target mail users. Do not reach for it here, and if you are doing both workloads see the hybrid identity path.

Do not confuse this with the mailbox side of the move. Mapping identities is the shared prerequisite; the mailboxes themselves go across with cross-tenant mailbox migration and its own prerequisites.

SharePoint tenant to tenant migration, step by step

Microsoft's supported path is seven steps, and the order is not negotiable. It follows the shape of the problem: you do not point a content migration at a target that has not been prepared to receive its owners.

Step three has a delay built into it that surprises people. When you test the relationship you may get DormantByPartner, which means the partner's requested trust is still inside a seven-day waiting period after creation. That is not an error to troubleshoot. It is a clock, and it belongs in your cutover calendar rather than in your cutover weekend.

There is a hard rule inside step six: do not pre-create the destination site. If the target site already exists, the migration fails — you cannot overwrite or merge into an existing site. Group-connected sites are the one nuance, where the target Microsoft 365 group is precreated in a specific way and must not be linked to an existing SharePoint site, but a plain site URL that already exists on the target will stop the move cold.

How to migrate a SharePoint site to another tenant

With trust verified and identities mapped, a single site is one command, run by a SharePoint admin or Global admin on the source tenant. Check compatibility first with Get-SPOCrossTenantCompatibilityStatus -PartnerCrossTenantHostURL <target host url>; a status of Compatible or Warning means you may continue. Then:

• A standalone site: Start-SPOCrossTenantSiteContentMove -SourceSiteUrl <url> -TargetSiteUrl <url> -TargetCrossTenantHostUrl <url>
• A group-connected site: Start-SPOCrossTenantGroupContentMove -SourceGroupAlias <alias> -TargetGroupAlias <alias> -TargetCrossTenantHostUrl <url>, which takes group aliases rather than site URLs

Both commands take -PreferredMoveBeginDate and -PreferredMoveEndDate in UTC, which is how you schedule a batch for a weekend window instead of firing it now. You can queue up to 4,000 migrations per batch, and hold up to 4,000 pending in the queue at any one time; beyond that, split into batches and schedule the next one as the current batch nears completion.

Watch the run with Get-SPOCrossTenantUserContentMoveState -PartnerCrossTenantHostURL <partner url> from either tenant, adding -SourceUserPrincipalName for one person and -Verbose for detail. The states you will see are NotStarted, Scheduled, ReadytoTrigger, InProgress, Success, Rescheduled, and Failed. Rescheduled is not a failure — the move did not complete and was requeued for another pass. A move can be cancelled with Stop-SPOCrossTenantSiteContentMove or Stop-SPOCrossTenantGroupContentMove, but only while its status is neither In Progress nor Success. After that, the way back is a rollback plan you wrote in advance, not a cmdlet.

What carries, and what needs a second pass

Draw a clear line here before you plan the cutover, because the two halves need very different amounts of your attention. The feature covers Microsoft 365 group-connected sites including the ones behind Teams, modern sites with no group, classic SharePoint sites, and communication sites.

One boundary catches people out. Migrating a Teams-connected SharePoint site moves the SharePoint content and nothing else — not the Teams channels, not the chat, not the structure around them. That is a separate job, covered in Teams cross-tenant migration. The same split applies to personal files, which travel on the OneDrive cross-tenant path rather than this one.

Carries as part of the move: files, their version history, folders, list items, and file metadata all travel with the site. Existing sharing links are automatically redirected to the new location, so a link someone bookmarked or emailed keeps resolving. Permissions carry for every user and group you mapped.

Needs manual attention on the target: the customizations. SharePoint 2010 and 2013 workflows must be re-created and republished. Apps must be republished and possibly modified. Power Apps and Power Automate flows must be recreated and reconnected to the site. Web parts that reference content in other sites or other Microsoft 365 services may need rebuilding. And sensitivity labels are their own project — protection or policy tied to a label will not be present after the move, and sites using labels with user-defined permissions cannot be migrated until those labels are removed. The rule of thumb: the more a thing was configured rather than stored, the more likely it needs a human on the far side.

Verify after — and remember it is one-and-done

This is a one-time move, not a sync. The content is moved from source to target with a redirect left behind, and incremental or delta passes cannot be performed. That has a practical consequence: you cannot seed early and catch changes later, which is why users are told to close their files and stop editing during their migration window. Start with a small batch of sites to validate your process before you schedule large ones.

After a move, verify the things that were supposed to survive. Open a site as a mapped user and confirm access is intact. Spot-check a document's version history. Click an old sharing link and confirm the redirect lands you in the new location. Then walk the manual list — workflows, flows, apps, labels — and rebuild what did not come across. Verification is not ceremony here; it is the only way to catch a permission that quietly dropped because someone was missing from the mapping file.

The takeaway

SharePoint tenant to tenant migration moves your files, versions, and metadata cleanly inside the Microsoft cloud and redirects the old links for you — once you have cleared the Enterprise Agreement licensing gate. The part that decides whether the migration is a success or a helpdesk event is identity mapping: map every source user to their target account first, and permissions re-attach as content arrives; skip anyone, and their access is simply gone. Get the sequence right, trust then precreate then map then move, plan a manual pass for the customizations, and verify before you call it done. Map identities first and the cutover is quiet; skip the mapping and you will meet every unmapped user again in the support queue.

Questions people also ask

What is SharePoint tenant to tenant migration?

SharePoint tenant to tenant migration, which Microsoft calls cross-tenant SharePoint migration, moves SharePoint sites from one Microsoft 365 tenant to another using SharePoint Online PowerShell, without the content ever leaving the Microsoft cloud. The content is moved from source to target, and a redirect is left in the original location so existing links keep working. It is a one-time move, not an incremental sync.

How do I migrate a SharePoint site to another tenant?

Connect to both tenants with Connect-SPOService, establish trust in both directions with Set-SPOCrossTenantRelationship, verify it reads GoodToProceed with Test-SPOCrossTenantRelationship, precreate the users and groups on the target, run cross-tenant identity mapping, then check compatibility and start the move with Start-SPOCrossTenantSiteContentMove for a standalone site or Start-SPOCrossTenantGroupContentMove for a group-connected one. Do not create the target site first.

What is cross-tenant identity mapping?

For SharePoint it is a six-column CSV file that lists every source user and group beside the target account that replaces it, uploaded to the target tenant with Add-SPOTenantIdentityMap. The mapping is then applied automatically as each site migrates, which is what lets permissions re-attach on the other side. Each upload replaces the previous map, so every revision must contain everyone still in scope. Mailbox migration uses a different tool with the same name in Exchange, Cross-Tenant Identity Mapping, and its module is not the one to use here.

Does cross-tenant SharePoint migration keep permissions?

Only if you account for the users first. Permissions re-attach on the target because identity mapping links each source user to their target account, so the migration knows who the old access entries now refer to. Users and groups that were not mapped lose their access, because on the target their old identity does not exist to re-attach to.

What carries over in a cross-tenant SharePoint migration?

Files, their version history, folders, list items, and file metadata carry as part of the site move. Existing sharing links are redirected to the new location. Permissions carry for users who were mapped during identity mapping. What does not carry cleanly includes workflows, apps, Power Platform flows, some web parts, and sensitivity labels, which need re-creation or attention on the target.

Do you need a license for cross-tenant SharePoint migration?

Yes. The Cross-Tenant Shared Data Migration feature and its licenses are available to Enterprise Agreement customers only, purchased through your Microsoft account team, and priced per 100 GB of data moved. Size the purchase from the storage used across the sites in scope, with a 20 percent grace allowance for growth. If you are not an Enterprise Agreement customer, a third-party migration tool is the route instead.

Can I merge into an existing SharePoint site on the target tenant?

No. If the target site already exists, the migration fails, because you cannot overwrite or merge into an existing site. Do not pre-create the destination site. For group-connected sites you do precreate the target Microsoft 365 group in a specific way, and that group must not be linked to an existing SharePoint site.

Is cross-tenant SharePoint migration incremental?

No. It is a one-and-done move. The content is moved from source to target and a redirect is left behind, so incremental or delta passes cannot be performed. You cannot run it once to seed and again to catch changes, which is why users are told to stop editing during their migration window and why you validate before the cutover.

Does cross-tenant SharePoint migration move Microsoft Teams content?

No. If you migrate a Teams-connected SharePoint site, only the SharePoint site content moves to the target. Teams content, channels, and the structure around them are not included and are a separate piece of work. Group-connected sites are supported, so the files land, but the Team itself has to be rebuilt on the target tenant.