Step 5: SharePoint Identity mapping

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

• Step 1: Connect to the source and the target tenants
• Step 2: Establish trust between the source and the target tenant
• Step 3: Verify trust is established
• Step 4: Precreate users and groups
• Step 5: Prepare identity mapping
• Step 6: Start a Cross-tenant SharePoint migration
• Step 7: Post migration steps\n

Create the identity mapping file

In this step of the cross-tenant migration process, you're going to create a single CSV (comma separated values) file that contains the mapping of the users and groups on the source tenant to their corresponding users and groups on the target tenant.

We recommend you take the time to verify your mappings, ensuring they're accurate before starting any migrations to the target tenant.

There's a one-to-one relationship in the identity mapping file. You can't map the same user to multiple users in the target tenant. For example, if you have instances where the admin is the owner of multiple SharePoint accounts, the ownership must be changed to match the corresponding user you wish to migrate from Source to Target. If you don't, those account files don't migrate.

Example: In this example, the admin owns multiple SharePoint accounts.

Cross-tenant migration supports this scenario:

Example:

Create the CSV file

There are six columns needed in your CSV file. The first three are your source values, each providing detail about where your data is currently located. The remaining three columns are the corresponding info on the target tenant. All six columns must be accounted for in the file. Create your file in Excel and save it as a .csv file.

Users and groups are included in the same file. Depending on whether it's a user or group, what you enter in the column is different. In each of the columns enter values as shown in the examples. Do NOT include column headings.

Users. Enter your values as shown in this example for Users:

Guest users. You can map guest accounts in the source tenant to member accounts in the target tenant. You can map a source guest account to a target guest account if the guest already exists. Enter your values as shown in this example for guests:

Groups. Enter your values as shown in this example for groups:

Example:

Microsoft 365 Groups. Enter your values as shown in this example for Microsoft 365 groups:

Multiple users and groups in a CSV file:

Example:

Obtain the source tenant company ID

To obtain Source Tenant Company ID:

1. Sign in as Admin to your Azure portal.
2. Select or Search for Microsoft Entra ID.
3. Scroll down on the left-hand panel and select Properties.
4. Locate the Tenant ID Field. The required Tenant ID is in that box.

To obtain source group object ID:

1. Sign in to source tenant as Admin to Azure Groups.
2. Search for your required groups.
3. Select the required group instance and then Copy to clipboard. Paste this value in the sourceGroupObjectId column of your mapping CSV file.
4. If you have multiple groups to map, then repeat these steps for each group.

To obtain target group object ID:

1. Sign in to Target tenant as Admin to Azure Groups
2. Search for your required groups.
3. Select the required group instance and then Copy to clipboard. Paste this value in the targetGroupObjectId column of your mapping CSV file.
4. If you have multiple groups to map, then repeat this process to obtain those specific targetGroupObjectId's.
5. For the GroupName, use the same ID as the TargetGroupObjectId you obtained.

Upload the identity map

Once the identity mapping file is prepared, the SharePoint Administrator on the target tenant uploads the file to SharePoint. This file allows identity mapping to occur automatically as part of the cross-tenant migration.

1. To upload the identity Map on the target tenant, run the following command. For -IdentityMapPath, provide the full path and filename of the identity mapping CSV file.

Add-SPOTenantIdentityMap -IdentityMapPath <identitymap.csv>

Uploading any new identity map overwrites the current one. Make sure that any revision or addition includes ALL users and groups for the full migration. Your identity map should always include everyone you're wanting to migrate.

To look at the mapping entries in the identity mapping file for a particular user: Use the command Get-SPOTenantIdentityMappingUser to view mapping entries. Set Field to SourceUserKey and Value to the user’s UPN.

Example:

get-spoTenantIdentityMappingUser -Field SourceUserKey -Value usera@Contoso.onmicrosoft.com

Verify cross-tenant compatibility status

Before starting any cross-tenant migrations, make sure that both SharePoint database schemas are up to date and compatible between source and target.

To perform this check, run this cmdlet on your Source tenant.

Get-SPOCrossTenantCompatibilityStatus -PartnerCrossTenantHostURL [Target tenant hostname]

Get-SPOCrossTenantCompatibilityStatus -PartnerCrossTenantHostURL https://m365x12395529-my.sharepoint.com

• If the tenant status shows as Compatible or Warning, you can then proceed with the next step of starting cross-tenant migrations.
• If the tenant status shows as Incompatible, your tenants need to be patched/updated to ensure compatibility.

Step 6: Start a SharePoint cross-tenant migration