MigrateUsers Method Breaks All Web Application Permissions

On my current project we are doing a migration from SharePoint 2007 to SharePoint 2010. Updating our current authentication scheme (a mix of .Net forms and Windows authentication) to utilize claims authentication is one of the requirements for this project. One major difference between how SharePoint treats users in SharePoint 2007 and SharePoint 2010 claims authentication mode is the username it reads to resolve users. In SharePoint 2007 these were pretty plain representations of a username you would recognize. This changed to a more complex string in SharePoint 2010 to allow for resolution of users from a larger number of possible sources. The below table gives an example of this; please note that there are other authentication types I am leaving out.

Authentication Type	SharePoint 2007 convention	SharePoint 2010 convention
Individual Windows User (NTLM)	domainusername	i:0#.w|domainusername
Active Directory Group (NTLM)	domaingroupname	c:0+.w|s-1-1-11-111111111-1111111111-111111111-1111 (SID for group)
Forms Authentication	formsprovidername:username	i:0#.f|formsprovidername|username
Claims Authentication (custom provider)		i:0e.t|providername|username

Microsoft added a method on the SPWebApplication object that you can call to migrate your users, you can call it in powershell like so:
$w = Get-SPWebApplication “http://yoursharepointsite.com/”
$w.MigrateUsers($True)
This command will change all usernames from the 2007 convention to the 2010 convention.
It seems a little too easy and too good to be true. Upon running this method the first time the conversation between me and the support engineer I was working with went a little bit like so (language in real life may have been a tad more colorful):
Me: Did you run it? I still get access denied on the web application.
Support: Yes, it finished with no errors too. Oh crap, I get access denied too! I’m giving your account full access to the web application with a user policy in CA, try it again.
Me: I’m still getting a darn access denied message. No frickin’ way, did we just kill SharePoint?
Support: SharePoint declared deceased at 3pm on 8/5/2011. Shucks.
After we stopped freaking out, we tried re-attaching a copy of the content database taken before running the MigrateUsers method. This didn’t help, we still got access denied everywhere on the web application even with a Farm Administrator account. We ended up having to recreate the web application and re-attaching the earlier copy of the content database to get it back up and running. After trying this multiple times and having it fail every time I did some searching on the web. I found a few mentions of updating the PortalSuperUser and PortalSuperReader account for the web application so they were in the correct user format before the user migration. After trying this a couple times and getting the same result as before we found the problem!
We were creating our web application with a powershell script. When we set the PortalSuperUser and PortalSuperReader accounts in the script we were using the old format (domainuser) and it seemed to be persisting somewhere in the content database causing the user migration to break all permissions on the web application. To fix this we updated our powershell script to create the web application with the super user and super reader accounts using the new format (i:0#.w|domainusername) and this fixed the broken permissions after running the MigrateUsers method.
If you need to customize your usernames further (i.e. your user’s domain is changing or you are moving from forms to claims authentication) you can modify the username string directly. If your SharePoint 2010 application has the latest patches applied Microsoft made a callback available in one of the cumulative updates so you can hook into the MigrateUsers method and run your custom code. If you are still on the RTM version you can modify the user profile properties directly through powershell.