The SPMigrateUsers Tool for Changing Account Identities in SharePoint 2010

There are times in SharePoint when you want or need to change an account identity.  The best example is with SAML claims.  In virtually of my examples I use email address as the identity claim for users.  I do this because a) most people have an email address and b) an email address is something that most users understand.  However, I get push back every now and then about using email address because people can change it.  When you change your email address, then obviously all the permissions you have would break.  To be honest, I don’t consider this to be a frequent scenario, or I wouldn’t use email address to begin with.  However I will grant you that it does occasionally happen, so what do you do when all of your SharePoint is secured with email addresses?

The key to controlling this is in a blog post I did previously on the IMigrateUserCallback interface:  http://blogs.technet.com/b/speschka/archive/2011/01/27/migrating-user-accounts-from-windows-claims-to-saml-claims.aspx.  In that post I describe how to migrate identities using this interface and provided an example of how to convert a Windows claims identity to a SAML claims identity.  What I decided to do is just write a little Windows application that will let you enter the credentials that you want to change and it will make the modification for you.  It’s goal in life is to be used as a simple one-off tool for making these changes, however you could easily take the source code (which I’m including with this post) and modify it to do something more creative, such as reading in a list of users from a file or database and doing the comparisons yourself.

What’s also nice about this tool though is that it can actually be used for multiple scenarios.  So not only can you use it to convert from one email address to another, you can also use it to convert from one group name to another.  This is another case where certain Ops folks tell me, hey, you should use SIDs for the group names (i.e. Role claims in SAML) because if you rename the group the SID remains the same.  While that’s also true, again, a) I don’t see that happen a ton, b) how many of you want to start typing in group SID names and adding them to SharePoint groups (please seek therapy now if you answer yes) and c) SIDs mean nothing outside of your local Active Directory – as soon as you move into a cloud-based service like Azure, Google, Yahoo, Facebook, etc. your SID will be as useless as [fill in your own “useless as a …” joke here].

The other thing that’s nice about this tool is that it doesn’t restrict you to just making changes within a single type of provider.  Want to change a Windows group to a SAML role claim?  You can do that.  Want to change a SAML identity claim to an FBA membership user?  You can do that.  Want to change an FBA role to an AD group?  You can do that.  You get the idea – I’ve tried just about every combination of different “users” and “groups” between different providers and so far all have converted back and forth successfully.

The tool itself is hopefully pretty straightforward to use; here’s a picture of it:

When the application first starts up it loads up a list of all the web applications.  For each web application it populates the two combo boxes below it with a list of all the providers being used on that web application.  If you have multiple SAML providers or multiple FBA providers, each one will be listed in the drop down.  You simply choose which provider you are migrating from and which you are migrating to.  In the Claim Value section you type in the value that want to migrate, and what you want to migrate it to.  Just type the value in the Plain Text Value edit fields and click either the identity claim button (the one on the left) or the group claim button (the one on the right).  The description in the text gives a full explanation of this and the text on the buttons changes so it makes more sense depending on which identity provider you are using.

For example, suppose you are only using SAML authentication and wanted to migrate the email address “steve@contoso.com” to “stevep@contoso.com”.  You would pick your web application and the SAML authentication provider would be selected by default in each drop down.  Then in the Before Values section you would type “steve@contoso.com” in the Plain Text Value edit and click the ID Claim button; that puts the correct encoded claim value in the Encoded Value edit.  Next you would type “stevep@contoso.com” in the After Values Plain Text Value edit.  Click on the ID Claim button again it puts the correct value in the Encoded Value edit box (NOTE:  In the picture above the button in the After Values section says “User” instead of “ID Claim” because in that example it is migrating from SAML claims to Windows claims).  Once all of your values have been provided just click the Migrate button to complete the process; a message box will appear informing you when the migration is complete.

In the process of testing this across several different web applications and several different authentication types I did run across a couple of issues that I want to raise here in case you see them as well.  In one case I got an Access Denied error message when trying to migrate the users for one particular web application.  I never was able to track down why this was occurring so the best I can say is that something is wonky in that web app, but I’m not sure what because it worked on all the four or five other web apps I tried in my farm.

The second thing is that in one case the migration said it completed successfully but I could not log in as the migrated user.  In digging into it further I found that the account I was migrating from was not being pushed through the IMigrateUserCallback function (i.e. it’s a SharePoint problem, not a coding problem with this application).  If that happens to you I recommend using the source code and Visual Studio to step through the debugger to make sure the account you’re migrating from is getting called.  Unfortunately I had one lonely FBA membership user that got stuck alone in the wilderness.

Finally one last thing to note – don’t freak out if you migrate an account from one value to another, then log in as the new user and see the old account name, etc. in the welcome control in the top right corner of the page.  The migrate function just changes the account name.  If the other user information changes at all then as long as you update the user profiles the correct information should get pushed down to all the site collections on the next sync with the profile system.

That’s it – have it and hope it helps.  As I said above the complete source code is included so feel free to play with it and modify as needed for your scenario.

Here’s a link to the source code: