Step 4: Pre-creating users and groups (preview)


Cross-Tenant SharePoint migration is currently in a private preview stage of development. As an unfinished project, any information or availability is subject to change at any time. Support for private-preview customers will be handled via email. Cross-Tenant SharePoint migration is covered by the preview terms of the Microsoft Universal License Terms for Online Services.

This is Step 4 in a solution designed to complete a Cross-tenant SharePoint migration. To learn more, see Cross-tenant SharePoint migration overview.

Identify users and groups to be migrated

To ensure that SharePoint permissions are retained as part of the migration, a mapping file needs to be created to align users from the source tenant to the target tenant.

  1. Identify the full list of SharePoint users and sites that will be migrated from the source to the target tenant.
  2. Identify the list of Microsoft 365 Groups that are connected to any Group-connected SharePoint sites that will be migrating as part of your project.
  3. Prepare a complete list of users, groups, and Microsoft 365 groups that will be migrated to the target tenant.

Pre-create users, groups, and Microsoft 365 groups on the target tenant

  • Pre-create users and groups as needed in the target tenant’s directory.
  • All users who are migrating to the target tenant must have new user identities created for them in the target tenant.


Note: If these users are also having their OneDrive migrated, make sure that these new users don't attempt to sign-in to their new target OneDrive until their corresponding OneDrive migration is complete.

  • All users whose SharePoint accounts are migrating to the target tenant must be assigned the appropriate SharePoint license.
  • Any users who remain in the source tenant but need access to resources migrating to the target tenant should have new guest identities created for them in the target tenant.
  • Pre-created users must be added as members of any appropriate security groups or unified groups before the SharePoint migration begins.
  • If the user or group name already exists in the target tenant, create a user or group with a different name and make a note of it for the next step.
  • We recommend that SharePoint site creations are restricted in the target tenant to prevent users from creating SharePoint sites.


To learn more on restricting SharePoint site creation, see Disable SharePoint creation for some users

Pre-create Microsoft 365 groups connect to SharePoint sites

Microsoft 365 groups connected to SharePoint sites must be pre-created using the Exchange Online management shell

These commands send a request to the tenant with whom you want to establish trust.

  1. Sign in to the Exchange Online Management Shell as an Exchange Online Admin or Microsoft 365 Global admin. Enter the password for target tenant when prompted.
Connect-ExchangeOnline –UserPrincipalName <UserPrincipalName>
  1. Create the appropriate Microsoft 365 groups, where AccessType matches the access type of the corresponding Microsoft 365 group on the source tenant.
New-UnifiedGroup -DisplayName <TargetGroupDisplayName> -Alias <TargetGroupAlias> -AccessType <Private|Public> 


Microsoft 365 Groups connected to SharePoint sites MUST be pre-created using this method. Pre-creating Microsoft 365 groups using any other methods will cause SharePoint site migrations to fail.

Step 5: Prepare the identity mapping file