SharePoint Migration Identity Mapping Tool

Use the Identity Mapping feature of the SharePoint Migration Assessment Tool to help your Identity Migration.

Introduction

Identity Migration is the process of mapping identities from the SharePoint on-premises environment to the target-state Microsoft Entra ID.

Since user and group synchronization from AD to Microsoft Entra ID is new to many customers, it's essential to assign appropriate resources. Perform all internal planning and execute all identity migration-related tasks in unison with your overall on-premises migration plan.

The identity project's most important goal is verification that all needed users and groups are synchronized to Microsoft Entra ID. If you migrate without doing this analysis first, users could lose access to content.

Reference this document for information about the process, roles and responsibilities, artifacts, and controls associated with the One-time Identity Migration process.

Overview

The goal of the identity migration is to synchronize all possible users and to disposition any remaining unmapped records with justification as to why they aren't synchronized. This synchronization and disposition process must be complete prior to preparation of user acceptance testing, which is Dry Run 1. All unmapped records must have valid justification and be approved by the Microsoft project team.

Run three different scans to perform identity mapping:

• SharePoint Migration Identity Mapping Tool: SharePoint Identity Scan

• SharePoint Migration Identity Mapping: Active Directory Identity Scan

• SharePoint Migration Identity Mapping Tool: Microsoft Entra Identity Scan

Process

Use this process for Users and Groups that have access to SharePoint found in the FullIdentityReport.csv report.

Care should be taken to ensure all required users and groups are included in the Microsoft Entra synchronization. If SharePoint content is owned by users who haven't been migrated, their user permissions won't be migrated.

The goal is to synchronize 100% of the identities that have access to the source SharePoint environment or provide reasons for any identities that aren't synchronized.

Initial preparation of all users and groups is needed to determine which users and groups to migrate.

• Ideally all users and groups have TypeOfMatch set to ExactMatch or PartialMatch.

• If there are exceptions, make notes in the MappingRationale field of the FullIdentityReport.csv file for tracking purposes.

Steps:

1. Download the assessment tool to a computer in your SharePoint farm. To download, go here: SharePoint Migration Assessment Tool

2. Provide consent to allow the tool to access your Microsoft Entra ID.

3. Run: SMAT.exe -GenerateIdentityMapping

4. Open FullIdentityReport.csv in Excel.

5. Filter on TypeOfMatch = NoMatch. These users and groups won't have access to content post migration. For example, contoso\johndoe is listed as NoMatch. AclExists is True. Post migration any content that contoso\johndoe had access to on the source will not work for that account post migration. A site owner needs to add contoso\johndoe's Microsoft Entra account back into permissions to resolve the issue.

6. Filter on TypeOfMatch = PartialMatch. Ensure the matches we found are correct. It is possible for partial matches to be incorrect if multiple people have the same Display Names or the User Principal Names changed from the source to target.

7. Build a plan to remediate the gaps. For example, if you are using Windows identities and there are users and groups that have TypeOfMatch set to NoMatch or PartialMatch, then you'll typically want to sync those other users and groups to Microsoft Entra ID and rerun the identity mapping process.

8. Sync other users and groups to Microsoft Entra ID.

9. Repeat until you get a FullIdentityReport.csv that properly represents your expectations post migration.

Preflight validation checks

The tool performs a preflight validation check to ensure the operator has access to Microsoft Entra ID. Access to Microsoft Entra ID is required to perform the identity mapping process.

When prompted, enter Microsoft Entra credentials. If needed the sign in prompt asks for consent. Azure tenant admin consent is required for this application to read Microsoft Entra ID.

If your sign-in fails or you're unable to provide consent, you'll see the following failure:

If you say no at the prompt, the tool exits without performing any identity mapping scans.

If you choose to continue with the Identity Mapping process, you'll receive one more prompt when the Microsoft Entra ID scan runs. If you're unable to authenticate or provide consent at that point, the Microsoft Entra ID scan fails. You'll still receive the reports, but mapping won't be performed. The resulting output is representative of all the identities that have access to the source SharePoint environment.

Configuration File

The identity mapping scans can be configured in the ScanDef.json file. This file is located in the same directory as SMAT.exe.

Consent to read directory data

To generate the Identity Mapping Reports, you need to consent to allow assessment tool to read your Microsoft Entra directory. There are two methods available.

Option 1: Run the assessment tool with the -ConfigureIdentityMapping switch.

This option gives the assessment tool access to your tenant's Enterprise Applications section. It allows anyone in your tenant to run the tool to perform identity mapping for migration in Microsoft 365.

1. Download the assessment tool from here: SharePoint Migration Assessment Tool

2. Run: SMAT.exe -ConfigureIdentityMapping

   Note

   It is not required to run this step on the SharePoint environment. You can run the above command on any machine that has access to the Azure tenant.

3. When prompted with the Azure sign in dialog, enter your Azure tenant admin credentials.

4. When prompted for consent, select Accept.

5. The SMAT.exe application indicates the application was successfully registered. A SharePoint admin is now able to run the identity mapping process.

   

Option 2: Run the assessment tool as a user with Azure Tenant Admin rights.

It's possible for a user with Azure tenant admin rights to run the tool and only provide consent for themselves.

1. Download the assessment tool from here: SharePoint Migration Assessment Tool

2. At the command line, type Run SMAT.exe -GenerateIdentityMapping

3. When prompted with the Azure sign in dialog, enter your Azure Tenant Admin credentials.

4. When prompted for consent, select OK. This will only consent the app for the sign in provided.

5. The identity mapping will run and generate the needed reports.

Remove Consent

Follow the steps below to remove consent for the SharePoint Identity Mapping Application from your Azure Tenant. Once these steps have been performed, it will be necessary to provide consent the next time you run the identity mapping process.

1. Browse https://portal.azure.com

2. Sign in as an organization admin.

3. Locate Enterprise applications.

4. Select All applications.

5. In the list of applications, select SharePoint Identity Mapping Tool, and then select Delete.

Reports generated

There are two reports generated by the -GenerateIdentityMapping switch. Each report is used as part of the identity mapping process.

Both reports indicate users granted permissions to SharePoint content.

FullIdentityReport.csv

The FullIdentityReport.csv contains a dump of all the identity data we discovered about the users and groups that were listed as active in the SharePoint environment. The purpose of this report is to understand all the users and groups that have access to SharePoint and whether those identities have an associated Microsoft Entra identity.

If the identity isn't found in Active Directory, the Active Directory fields are empty. The FoundInAD field is false and ReasonNotFoundInAD will contain a reason code.

If the identity wasn't found in Microsoft Entra ID, the Microsoft Entra ID fields will be empty. The FoundInAzureAD field will be false and ReasonNotFoundInAzureAD will contain a reason code.

IdentityMapping.csv

IdentityMapping.csv is a pregenerated identity mapping file. All identities are represented in the file. Unmapped identities have blank values for TargetIdentity.

See also

Other Resources

Download the SharePoint Migration Assessment Tool