| title | ms.author | author | manager | ms.date | audience | f1.keywords | ms.topic | ms.service | localization_priority | ms.collection | description | |||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
SharePoint Migration Identity Mapping Tool |
jhendr |
JoanneHendrickson |
serdars |
01/11/2018 |
ITPro |
|
article |
sharepoint-online |
Normal |
|
Use the Identity Mapping feature of the SharePoint Migration Assessment Tool to assist in your Identity Migration. |
Use the Identity Mapping feature of the SharePoint Migration Assessment Tool to assist in your Identity Migration.
Note
To download the SharePoint Migration Tool, select: Download the SharePoint Migration Assessment Tool
Identity Migration is the process of mapping identities from the SharePoint on-premises environment to the target-state Azure AD.
Since user and group synchronization from AD to Azure AD is new to many customers, it is 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 Azure Active Directory. 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.
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 are not 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: Azure Active Directory Identity Scan
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 Azure AD synchronization. If SharePoint content is owned by users who have not been migrated, their user permissions will not 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 are not synchronized.
Initial preparation of all users and groups is needed to determine which users and groups to migrate.
-
Ideally all users and groups will 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:
-
Download the assessment tool to a computer in your SharePoint farm. To download, go here: SharePoint Migration Assessment Tool
-
Provide consent to allow the tool to access your Azure Active Directory.
-
Run: SMAT.exe -GenerateIdentityMapping
-
Open FullIdentityReport.csv in Excel.
-
Filter on TypeOfMatch = NoMatch. These users and groups will not 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 will need to add contoso\johndoe's Azure AD account back into permissions to resolve the issue.
-
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.
-
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 will typically want to sync those additional users and groups to Azure AD and rerun the identity mapping process.
-
Sync additional users and groups to Azure AD.
-
Repeat until you get a FullIdentityReport.csv that properly represents your expectations post migration.
The tool will perform a pre-flight validation check to ensure the operator has access to Azure Active Directory. Access to Azure Active Directory is required to perform the identity mapping process.
When prompted, enter Azure AD credentials. If needed the logon prompt will ask for consent. Azure tenant admin consent is required for this application to read Azure Active Directory.
If your sign-in fails or you are unable to provide consent, you will see the following failure:
If you say no at the prompt, the tool will exit without performing any identity mapping scans.
If you choose to continue with the Identity Mapping process, you will receive one more prompt when the Azure Active Directory scan runs. If you are unable to authenticate or provide consent at that point, the Azure Active Directory scan will fail. You will still receive the reports, but mapping will not be performed. The resulting output is representative of all the identities that have access to the source SharePoint environment.
The identity mapping scans can be configured in the ScanDef.json file. This file is located in the same directory as SMAT.exe.
To generate the Identity Mapping Reports, you need to consent to allow assessment tool to read your Azure AD 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.
-
Download the assessment tool from here: SharePoint Migration Assessment Tool
-
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.
-
When prompted with the Azure sign in dialog, enter your Azure tenant admin credentials.
-
When prompted for consent, select Accept.
-
The SMAT.exe application will indicate 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 is possible for a user with Azure tenant admin rights to run the tool and only provide consent for themselves.
-
Download the assessment tool from here: SharePoint Migration Assessment Tool
-
At the command line, type
Run SMAT.exe -GenerateIdentityMapping -
When prompted with the Azure sign in dialog, enter your Azure Tenant Admin credentials.
-
When prompted for consent, select OK. This will only consent the app for the sign in provided.
-
The identity mapping will run and generate the needed reports.
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.
-
Browse https://portal.azure.com
-
Log in as an organization admin.
-
Locate Enterprise applications.
-
Select All applications.
-
In the list of applications, select SharePoint Identity Mapping Tool, and then select Delete.
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.
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 Azure AD identity.
If the identity is not found in Active Directory, the Active Directory fields will be empty. The FoundInAD field will be false and ReasonNotFoundInAD will contain a reason code.
If the identity was not found in Azure Active Directory, the Azure Active Directory fields will be empty. The FoundInAzureAD field will be false and ReasonNotFoundInAzureAD will contain a reason code.
| Column name | Source | Description |
|---|---|---|
| UniqueID |
SharePoint |
For Windows accounts this will be a Security Identifier (SID). For non-Windows accounts, this will be the claim used to ACL SharePoint. |
| TypeOfMatch |
Assessment Tool |
ExactMatch - The source identity is a Windows account and we were able to match the SID in SharePoint to the OnPremisesSecurityIdentifier in Azure AD. PartialMatch - The match was based on UserPrincipalName, Email, or Display Name. For groups, we only partial match on Display Name. NoMatch - Unable to match the identity against any information. |
| IsGroup |
SharePoint |
True if the identity is a group. |
| ACLExists |
SharePoint |
True if the identity is associated with permissions in SharePoint. This indicates the identity has access to some piece of content. |
| MySiteExists |
SharePoint |
True if the identity is a user and that user has a My Site/OneDrive associated with their profile. |
| ClaimType |
SharePoint |
Type of claim authentication mode associated with the identity. This will be one of the following values Classic - These are classic Windows accounts. No claims are involved and the user was ACL'ed using a Windows Security Identifier [SID]. Windows - Windows claims. TrustedSTS - SAML claim provider. Forms - Forms authentication is used. ASPNetMembership - .NET Membership provider. ASPNetRole - .NET Role provider. ClaimProvider - Claims based provider. LocalSTS - Local SharePoint Token Service. https://social.technet.microsoft.com/wiki/contents/articles/13921.sharepoint-20102013-claims-encoding.aspx |
| SharePointLoginName |
SharePoint |
Login name associated with the identity found in SharePoint. |
| SharePointDisplayName |
SharePoint |
Display name associated with the identity found in SharePoint. |
| SharePointProfileEmail |
SharePoint |
Email address associated with the user. This is only populated if the identity is a user, the user has a SharePoint profile, and that profile has an email set. |
| ActiveDirectoryDisplayName |
Active Directory |
Display name found in Active Directory. |
| ActiveDirectoryDomain |
Active Directory |
Domain name in which the identity was located. |
| SamAccountName |
Active Directory |
Account name for the identity. This value will be empty for groups. |
| GroupType |
Active Directory |
Type of group. This will be empty for users. |
| GroupMemberCount |
Active Directory |
Number of members in the group. This will not reflect nested group counts. For example, if there is a group that contains 3 other groups, this will show as 3. This value will be empty for users. |
| DistinguishedName |
Active Directory |
The distinguished name associated with the identity in Active Directory. Example: CN=Bob Smith,OU=UserAccounts,DC=contoso,DC=com |
| AccountEnabled |
Active Directory |
True if the account is enabled in Active Directory. This will be empty for groups. |
| LastLoginTimeInAD |
Active Directory |
Date and time the user account last logged into Active Directory. This does not indicate the logon was associated with SharePoint, but can be used to determine if this is an active user account. This will be empty for groups. |
| FoundInAD |
Active Directory |
True if the identity was found in Active Directory. |
| ReasonNotFoundInAD |
Active Directory |
Reason why we did not find the account in Active Directory. This will be one of the following: BadCredentials - The username/password provided was invalid for the domain. DomainSidMatchNotFound - The SID found in SharePoint has a domain SID that does not match any of the located domains. InvalidSecurityIdentifier - The SID found in SharePoint is invalid. OnPremisesSidTranslationFailed - The SID appeared to be invalid, we tried to force a translation and that failed. UnableToConnect - Unable to connect to the domains. UnableToDetermine - We were unable to determine AD properties returned from the domain. UnknownException - An unexpected error occurred. Details are logged in the SMAT.log file. UserNotFoundInRemoteAd - We found a valid domain, but were unable to locate the identity using the SID. If FoundInAD is true, then this will be empty. |
| AzureObjectID |
Active Directory |
Object ID of the identity in Azure AD. |
| AzureUserPrincipalName |
Active Directory |
User principal name of the identity. This is only populated for users. |
| AzureDisplayName |
Active Directory |
Display name associated with the identity in Azure AD. |
| FoundInAzureAD |
Active Directory |
True if the identity was located in Azure AD. |
| ReasonNotFoundInAzureAD |
Active Directory |
The reason why we did not find the account in Azure Active Directory. The reason can be: PrincipalNotFound - Unable to locate the identity in Azure AD. AdalExceptionFound - Authentication failure to Azure AD. UnknownException - Unexpected error occurred. Details will be in the SMAT.log file. This will be empty if FoundInAzureAd is true. |
| MappingRationale |
Active Directory |
Use this open notes field to track unmapped users. |
| SanID |
Assessment Tool |
Unique identifier of a particular execution of the identity mapping process. Each time you run the tool, it will generate a distinct ID. |
IdentityMapping.csv is a pre-generated identity mapping file. All identities are represented in the file. Unmapped identities will have blank values for TargetIdentity.
| Column name | Description |
|---|---|
| UniqueIdentity |
Unique value to identify the object in the source environment. For Windows identities, this will be the Security Identifier (SID). For all other identity types, this will be the claim found in SharePoint. |
| TargetIdentity |
Identity to map the source identity to. For users, this value is the User Principal Name of the user in Azure Active Directory. For groups, this value is the Object ID of the group in Azure Active Directory. |
| IsGroup |
True if the row represents a group. |