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 →

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 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.

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."

The sequence: identity settles, then content moves

The order is not negotiable, and it follows the shape of the problem. You do not point the content migration at a target that has not been prepared to receive its owners.

1. Establish trust between the source and target tenants so they are allowed to move data to each other.
2. Precreate the users and groups on the target — every identity that holds permissions on the sites you plan to move.
3. Run identity mapping so each source user is linked one-to-one to their target account. This is where the mapping file is built.
4. Only then schedule the SharePoint site moves. The migration reads the mapping to re-attach permissions as content lands.

There is a hard rule inside step four: 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, but a plain site URL that already exists on the target will stop the move cold.

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.

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

Cross-tenant SharePoint migration moves your files, versions, and metadata cleanly inside the Microsoft cloud and redirects the old links for you. 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 cross-tenant SharePoint migration?

It is a Microsoft 365 capability that moves SharePoint sites from one 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.

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.

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, but never a standalone site with the same URL you are migrating into.

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.