How to Preserve Sharing Decisions During Migration in OneDrive for Business

When you migrate OneDrive for Business content between tenants or to a new user, sharing permissions often get lost or reset. Users lose access to shared files, and external sharing links stop working. This article explains how to use the Microsoft 365 migration tools and PowerShell to preserve sharing decisions during a OneDrive migration.

Sharing decisions include internal permissions, external sharing links, and access expiry settings. Without proper planning, these settings are replaced by default permissions after the migration. You will learn the exact steps to export sharing metadata before migration and reapply it after files are moved.

We cover the Microsoft Migration Manager, SharePoint Migration Tool SPMT, and PowerShell scripts that capture and restore sharing settings. By following these steps, you can ensure that shared files remain accessible to the same people after the migration completes.

Why Sharing Decisions Are Lost During OneDrive Migration

OneDrive sharing decisions are stored as metadata on each file and folder. When you migrate content between tenants, the object IDs of users and groups change. The target OneDrive does not recognize the old user IDs, so it treats all sharing settings as invalid. By default, migration tools either skip sharing metadata or replace it with the target user’s default permissions.

The Microsoft Migration Manager and SPMT can preserve sharing permissions if you configure identity mapping. Identity mapping creates a lookup table that matches source user IDs to target user IDs. Without identity mapping, the migration process discards sharing links and permissions. External sharing links also break because the link URLs contain tenant-specific identifiers that differ between source and target.

To preserve sharing decisions, you must export the sharing metadata before migration, create an identity map, and then reapply permissions after migration. The following sections explain each step in detail.

Steps to Preserve Sharing Permissions During OneDrive Migration

Follow these steps in order. You must have global admin or SharePoint admin access in both source and target tenants. You also need the SharePoint Online Management Shell installed.

1. Export sharing metadata from the source OneDrive
   Open the SharePoint Online Management Shell as an administrator. Run the command Export-SPOUserProfile -LoginName user@source.com -OutputFile C:\migration\sharing.xml. This exports all sharing permissions and links for the user’s OneDrive. Repeat for each user whose OneDrive you plan to migrate. Store the XML files in a secure folder.
2. Create an identity mapping file
   In the Microsoft 365 admin center, go to Settings > Migration > Migration Manager. Select OneDrive migration and then Create identity mapping. Download the CSV template. Fill in the source user principal name UPN and the target UPN for each user. Upload the completed CSV file to Migration Manager. This mapping tells the migration tool how to translate user IDs.
3. Configure the migration with permission preservation
   In Migration Manager, select the source OneDrive location and the target OneDrive location. Under Advanced settings, enable Preserve permissions. This option uses the identity mapping to reassign sharing permissions to the correct target users. Also enable Preserve sharing links if you want external sharing links to continue working. Start the migration scan. Review the scan report for any permission warnings.
4. Run the migration
   After scanning, select Migrate. The migration process moves files and re-applies sharing permissions using the identity mapping. The tool logs any permissions that could not be mapped. After migration completes, verify that files are shared with the correct users in the target OneDrive.
5. Reapply orphaned permissions using PowerShell
   If the migration report shows unmapped permissions, use the exported XML file from step 1. Run Set-SPOUser -Site https://target.sharepoint.com/personal/user_target -LoginName user@target.com -IsSiteCollectionAdmin $true to grant temporary admin access. Then run Grant-SPOSitePermission -Identity https://target.sharepoint.com/personal/user_target -User user@source.com -Role Contribute to reapply missing permissions. Replace the URLs and usernames with your target values.

Common Issues When Preserving OneDrive Sharing Permissions

External sharing links do not work after migration

External sharing links contain a tenant-specific identifier. When you migrate to a new tenant, the old links point to a tenant that no longer hosts the files. To fix this, generate new external sharing links in the target OneDrive. Use the Set-SPOSite -Identity https://target.sharepoint.com/personal/user_target -SharingCapability ExternalUserAndGuestSharing command to enable external sharing, then have users reshare the files.

Permission errors appear for groups that no longer exist

If the source tenant used distribution groups or security groups that do not exist in the target tenant, the migration tool cannot map those groups. You must recreate those groups in the target tenant with the same members. Then update the identity mapping CSV to include the group object IDs. Rerun the migration scan to apply the corrected mapping.

OneDrive sync client shows missing permissions error

After migration, the OneDrive sync client may show a red X on shared folders. This happens when the sync client still references the old sharing metadata. Instruct users to pause and resume sync in the OneDrive system tray. Right-click the OneDrive icon, select Pause syncing > 2 hours, then click Resume syncing. The sync client will refresh the permission metadata from the server.

Migration Manager vs SPMT for Preserving Sharing Decisions

Item	Migration Manager OneDrive	SharePoint Migration Tool SPMT
Description	Built-in Microsoft 365 admin center tool for tenant-to-tenant OneDrive migration	Free desktop tool for migrating content from local file shares or SharePoint to OneDrive
Permission preservation	Supports identity mapping and Preserve permissions checkbox	Supports Preserve permissions option but requires manual identity mapping CSV
Sharing links preservation	Preserves sharing links when enabled in advanced settings	Does not preserve sharing links; links must be recreated
Best use case	Tenant-to-tenant migrations with many users	Small-scale migrations or content from file servers

Use Migration Manager for tenant-to-tenant migrations where you need to preserve sharing links. Use SPMT for migrations from local file servers or SharePoint on-premises where sharing links do not exist. Both tools require identity mapping to preserve internal permissions.

You can now preserve sharing decisions during a OneDrive migration by using the Microsoft Migration Manager with identity mapping and the Preserve permissions option. Start by exporting sharing metadata from the source OneDrive, then create an identity mapping CSV in the admin center. After migration, use PowerShell to reapply any permissions that the tool could not map. For external sharing links, generate new links in the target tenant because old links contain tenant-specific identifiers that cannot be transferred. This approach ensures that users maintain access to shared files without manual resharing.