Cross-tenant SharePoint permissions

How MigrationFox carries SharePoint and OneDrive sharing across two Microsoft 365 tenants: the user mapping, what is copied, what happens to users who aren’t mapped, and what isn’t supported.

When to use this

Tenant-to-tenant SharePoint and OneDrive moves: acquisitions, divestitures, rebrands, and any migration where the source and destination are different Microsoft 365 organizations. Within one tenant you don’t need a mapping, because people keep the same identity.

The problem

A permission says who can do what on an item. Within one tenant, the person is the same account on both sides. Across tenants, the source account doesn’t exist at the destination: alice@acme.com means nothing inside New Company’s directory, and the person may now be alice.smith@newcompany.com.

Copying the permission as is would either fail or share the file with an outside address. So each source user has to be translated to the right destination user before the permission is written. That is what the user mapping does.

Turn on permissions

In the SharePoint & OneDrive wizard (web or MigrationFox Desktop), tick Migrate permissions (on a folder or library copy the option is called Include permissions). It is on by default. Then add a user mapping for a cross-tenant move.

User mapping

One mapping covers users. You can set it in two places:

For the whole project: on the project’s Connect tab, click User mapping to open it (it starts collapsed until a mapping is saved). Paste lines or click Upload CSV, then Save user mapping. Every migration in the project that copies permissions or uses True History Mode uses this list, unless the migration brings its own.
For one migration: in the wizard, under User mapping (optional, cross-tenant). Paste lines, click Upload CSV, or download the Template.

Format

One user per line: the source email, then the destination email, separated by a comma (a semicolon or tab also works). A header row is optional.

sourceEmail,destEmail
alice.finance@acme.com,alice.smith@newcompany.com
bob.marketing@acme.com,bob.jones@newcompany.com
carol.legal@acme.com,carol.davis@newcompany.com

Both values must be email addresses. Lines that can’t be read are pointed out by line number before you save.

Users not on the list

When a mapping is set, permissions for users who aren’t on it are dropped, not granted to their old address. This avoids accidental external sharing. To keep someone’s access, add them to the mapping. For an external partner who should keep access at the destination, map their address to itself (for example partner@agency.com,partner@agency.com); whether that works depends on the destination tenant’s external sharing settings.

What is copied

With permissions on, for each file (and each folder whose sharing is set on the folder itself):

People the item is shared with directly, translated through the mapping, with their access level: view, edit or review. Owner access is granted as edit, the highest level the sharing API allows.
Mail-enabled groups the item is shared with, by the group’s email address. Across tenants, the group must exist at the destination with the same address.
“Anyone” and “People in your organization” links, recreated as new links at the destination. The old link URLs don’t carry over, and the destination tenant’s sharing policy decides whether an “Anyone” link can be created.

People are not emailed when access is granted at the destination.

What is not copied

Users not in the mapping (when a mapping is set). Listed in the migration log.
Grants to SharePoint site groups (Owners, Members, Visitors) on individual files and folders.
Custom permission levels on files. They are skipped rather than downgraded.
Links shared with specific people are not recreated as links.
Groups are not mapped through the user mapping, and MigrationFox does not create users or groups or change group membership at the destination. Those stay directory tasks for your IT team.

A permission that fails at the destination (for example, a mapped user who doesn’t exist there) doesn’t stop the file. The file still copies, and the failure is written to the migration log.

Site-level permissions and True History Mode

Full site copy: copying site permission levels, SharePoint groups with their members, and site and list role assignments is in early access and switching on for every account soon. It uses the same user mapping: across tenants, only mapped users are granted access.
True History Mode: uses the same user mapping to set original authors at the destination. Authors without a match may show as System Account.

Check before you migrate

Migration Rehearsal (a read-only scan) checks the site’s users against your mapping on a cross-tenant move and raises a permissionRisk warning listing users with no entry.
After the run, download the Permission mapping report (PDF) from the migration’s page. It is offered for SharePoint destinations.

Map, or leave out?

Decision shortcut

If the person’s email will be @newcompany.com after the move, map them to that address. If they are an outside collaborator who should keep access, map their address to itself and check the destination’s external sharing settings. If they are leaving the business, leave them off the list and their permissions are dropped.

Troubleshooting

Symptom	Likely cause	Fix
The mapping shows lines “not understood”	A line is missing one of the two addresses, or a value isn’t an email address.	Fix the listed lines. Each line needs `source email,destination email`. Save CSV files as UTF-8.
A user was granted access but can’t open the file	The destination account has no SharePoint license, or hasn’t signed in yet.	Assign the license and have the user sign in once. The permission already points at the right account.
A mapped user’s permission failed with “not found”	The destination address in the mapping isn’t an account in the destination tenant (for example, an alias rather than the sign-in address).	Use the user’s sign-in address (UPN) from the destination tenant, then run the migration again with Incremental or Copy and replace for the affected files.
A group’s access is missing	The group doesn’t exist at the destination with the same email address, or it was a SharePoint site group.	Create the group at the destination and share the content with it, or share directly with its members.
“Anyone” links are missing	The destination tenant’s sharing policy doesn’t allow “Anyone” links.	Confirm the policy is intentional. If it is, have owners re-share those files with the right people.

What MigrationFox does not do

Mapping is explicit. MigrationFox does not guess matches from names (alice@acme.com looking like alison@newcompany.com is how access mistakes start), does not create users or groups in the destination tenant, and does not change group membership. The migration grants access only to identities that already exist.

SharePoint site migration overview: what a site migration copies
Migration Rehearsal: check the mapping against a real site before the production run
Microsoft: External collaboration settings: the tenant-level controls for guest access