SharePoint 2013: Working with Move-SPUser and Set-SPUser when migrating users

Print this posting

Introduction

This posting consolidates my notes with regard to migrating user accounts from old SharePoint instances to new ones. I had the need to cleanup and migrate a subset of users from a legacy, Internet-facing SharePoint 2007 farm, using a dedicated instance of Active Directory Lightweight Directory Services (ADLDS), all co-located on a single server. User account maintenance over the years had not be consistent nor robust and as a result user account formats were inconsistent and also reflected changing domain implementations.  Looking through the site collection's AllUsers list, one would see varying user account userLogin formats, such as:

• i:0#.f|OLDDOMAIN1|First.Last
• i:0#.f|OLDDOMAIN2|First.Last
• i:0#.f|OLDDOMAIN3|First.Last
• [machine name]\First.Last

Even the display names of these user accounts frequently contained varying domain names and other odd formats.  I also found some duplication and special character usage. There was no relationship between the old ADLDS and the new AD authentication services, and so performing a simple user migration was not possible.  Alot of user accounts had never experienced a login event, and many others had not been used in over a year.  Given the formatting of the old user accounts, additional effort was needed to cleanup the user account formatting in SharePoint, and then appropriately map the user accounts to their new implementations in AD.

Migrating Old User Accounts to New Domain

To do this, I first migrated the content DB using the usual pathway of: 2007 --> 2010 --> 2013, where both the intermediary 2010 and final 2013 farm web applications were configured as standard claims-based authentication web applications.  After the content DB was satisfactorily migrated and the site brought up, I reviewed the list of users in the old ADLDS, drafting a list of which ones really needed to be migrated.  To draft this list, I pulled user account information via repadmin, and then I coordinated with legacy site stakeholders, providing them lists of the old accounts for them to review.  I also pulled user account lastlogins to better identify and determine user accounts useful to migrate.  Over the course of several rounds of stakeholder review and comment, a final list was drafted.

Next, I used this basic script to pull the list of users in the migrated site collection.  The migrated content was contained in a single content database, a single web application, containing a single site collection. So, I only needed to look at one AllUsers list, like so:

$web=Get-SPWeb [new web application URL]
$web.AllUsers | Select-Object DisplayName, ID, userLogin  | Sort-Object DisplayName | Format-table -auto

This list revealed the extent of what needed to be done.  About a third of what was listed here needed to be migrated.  Because the usernames were so varied, it wasn't clear to me that writing a loop function would be the most time-effective approach.  Instead, I copied the target user accounts into Excel, and then used standard Excel string manipulation tools to generate the following set of statements for each user account to be migrated:

$User=Get-SPUser -Identity "i:0#.f|OLDDOMAIN|First.Last" -Web "[new web app URL]"
Move-SPUser -Identity $User -NewAlias "NEWDOMAIN\First.Last" -IgnoreSID -confirm:$false

In some cases, users had two accounts, due to what appear to have been misspellings or a customization request by a user, such as to shorten a name to a letter or two.  In such cases, I had to create two sets of user account migration steps, each set moving the legacy user account to the same destination account:

$User=Get-SPUser -Identity "i:0#.f|OLDDOMAIN|First.Last" -Web "[new web app URL]"
Move-SPUser -Identity $User -NewAlias "NEWDOMAIN\First.Last" -IgnoreSID -confirm:$false
$User=Get-SPUser -Identity "i:0#.f|OLDDOMAIN|F.Last" -Web "[new web app URL]"
Move-SPUser -Identity $User -NewAlias "NEWDOMAIN\First.Last" -IgnoreSID -confirm:$false

I then incorporated these statements into PowerShell script and executed.  It was useful to have it as a script because in this way I could re-execute the script over multiple trial migration runs - each fresh content database migration bringing with it the old user accounts untouched, and a portion of these would need to be re-mapped to their counterparts in AD.

Cleaning Up User Account Display Names

Another aspect of migrating the old user accounts involved cleaning up the user account DisplayName.  Here again I found a variety of formats and special characters and here again I used Excel string manipulation tools to quickly draft a set of statements for each user account needing cleanup:

$name=Get-SPUser -Identity "i:0#.f|OLDDOMAIN|First.Last" -Web "[New web app URL]"
Set-SPUser -Identity $name -Web "[new web app URL]" -DisplayName "First Last"

These statements I also placed into a PowerShell script for re-use during subsequent trial migration runs.

References

• Active Directory Lightweight Directory Services
• SharePoint’s hidden user-list – User Information List
• TIP: how to use repadmin to find user info in AD LDS
• SharePoint 2013 - The content processing component failed to process the security descriptor of the item
• Capitalizing First Letter of Every Word with Powershell 2
• Windows PowerShell Tip of the Week: The String’s the Thing
• Make a Choice
• Set-SPUser
• Get-SPUser
• Move-SPUser : The parameterless Read method can only be used when this instance was initialized with an SPUser object.
• How to Customize the "Sorry, this site hasn't been shared with you"

Notes

• Thanks to Trevor Seward for his assistance in this posting that helped me to better understand some aspects of the Move-SPUser command.
• The Move-SPUser NewAlias value must be in Pre-Windows 2000 format.  This means 20 characters or less. Otherwise, you will see errors like, "Move-SPUser : The user does not exist or is not unique."  You can determine the pre-Windows 2000 username currently set for the user by going to the account in Active Directory Users and Computers control panel, and then selecting the Account tab.
• The Move-SPUser NewAlias value must be of a user account that exists within the new AD domain.  For example, if you are moving a user to DOMAIN\First.Last, then DOMAIN\First.Last must be a valid AD account already created in the domain.  If this user account does not exist, you will see an error like, "Move-SPUser : The user does not exist or is not unique." 
• You need to refresh the $web object to see the changes.  This is because executing the Get-SPWeb command effectively takes a snapshot of the site collection and stores it in the $web object (as shown above).  If you want to see your changes reflected in the AllUsers list, you need to re-execute Get-SPWeb.