Best practices and recommendations when migrating users in SharePoint

Migrating users in SharePoint can be frustrating. As an Escalation Engineer on SharePoint at Microsoft Support, I've dealt with many issues on this topic. Now it is time to share some recommendations to help you avoid them.

This article is not a detailed step by step of everything that must be done. It is intended as a guide to explain the right way to do it. It applies to every user migration scenario, although the examples in this article illustrate a migration from Windows to federated authentication.

What you should not do

• Do not attempt a granular migration. It should be for every user, on every web applications.
• Do not allow users to authenticate with the new account before it is migrated.
• Do not allow users to authenticate with the old account after it is migrated.
• Do not use cmdlet Convert-SPWebApplication.
• Do not use cmdlet Move-SPUser.
• Do not build a script that gets the list of users to migrate at run-time.

Before the migration

A lot of work can be done before the migration, and that is a good news since it means that you can get prepared for it.

One task is to create a csv file that contains all accounts (users and groups) to migrate, and map their old account format (for example, "i:0#.w|contoso\yvand") with the new one (for example, "i:05.t|contoso.local|yvand@contoso.local").

A simple way to get the list of accounts to migrate is to query the content databases. For example, the SQL command below returns the list of Windows users and groups:

SELECT DISTINCT tp_Login FROM UserInfo WHERE tp_Login LIKE 'i:0#.w|%' OR tp_Login LIKE 'c:0+.w|%'        

Then you need to build the corresponding new format for each account. PowerShell and Excel will probably be your best tools for that.

Ideally, the account that will run the migration script should be the setup account, but whether you use it or not, ensure that this account is farm administrator, has full control on all web applications and has full control permission on the User Profile Service Application.

During the migration

Do not allow users to sign in to the sites.

In the User Profile Application service, deactivate the profile synchronization and delete the synchronization connections.

Parse your csv file using PowerShell, to migrate each account individually using SPFarm.MigrateUserAccount(), for example:

$oldlogin = "i:0#.w|contoso\yvand";
$newlogin = "i:05.t|contoso.local|yvand@contoso.local";
[Microsoft.SharePoint.Administration.SPFarm]::Local.MigrateUserAccount($oldlogin, $newlogin, $false);         

The migration is farm wide, so the account will be migrated in all the web applications and in the User Profile Application service.

After the migration

Do not allow users to sign-in with their old account. If you need to hide the provider selection page, do not manually set "sign in page URL" to "/_trust/" (it causes problems with Office integration). Instead, use a custom login page, for example this one, or build your own.

Following this guide does not guarantee that you will not get into trouble, but the overall process should be much easier to manage. Feel free to share your experience on this topic!