In this post I will discuss the nuances of changing identities in TFS 2010. The notion of changing an identity or mapping a user in TFS arises in scenarios where the identity's external identifier has changed, and we wish to make TFS aware of that change. Moving the server from workgroup to domain, moving from one hardware configuration to another, are examples of such scenarios that may entail changing identities - see In TFS 2008, identity change was accomplished by running the TFSAdminUtil Sid command. In TFS 2010 we provide the new and improved TFSConfig Identities command, aspects of which we discuss now.

  1. Target account restriction - the target account of the mapping should not already exist in TFS. This is a key restriction of TFSConfig Identities , as well as the older TFSAdminUtil Sid. If the target account is somehow introduced, either by being granted permissions or by group membership sync, it cannot be undone. Simply "removing" the user from group(s) will not work. Removing identities in TFS simply marks the record as logically deleted, and does not physically delete because the identity may own TFS artifacts such as changesets or work items.
  2. Batch versus individual mode - if account names are the same in both domains, the command can be run in batch mode. Otherwise identities can changed individually, specifying a different target account name.
  3. Identity source - if the identity was directly added to a TFS group, running the Identity Change command is sufficient. For accounts which were picked up by TFS by syncing AD groups, the source of the data should also reflect the change.
  4. Sync update - after running the identity change command, the next hourly sync will update all properties.

One scenario to which identity change is applicable is domain migration of account(s) in Active Directory. For this scenario, we have made an improvement in 2010 which makes it unnecessary to run identity change when the migration is to another domain within the same forest. Every identity in AD has a Guid in addition to the SID. In TFS 2010, we sync this AD Guid, and use it as the internal identity reference in TFS (TeamFoundationId). When an identity is domain migrated within the same AD forest, its SID changes but Guid remains the same. Hence TFS can automatically detect the SID change. This improves user experience because users will no longer get into the irredeemable state in which identity change does not work because the target account is already in TFS. Instead when the domain migrated account is added to TFS, its SID will automatically be updated.

Revert Behavior

There is a flip side to this to be aware. If identity change command is used to map unrelated accounts in the same AD environment, and if the old account is ever picked up again by TFS, then the identity change will revert back! It is easiest to explain this revert behavior by getting a bit technical. As stated above, every domain account in AD has a Guid, which is preserved during intra-forest AD migration. So let us say the following account is first added to TFS:

DomainA\foo, G1

with G1 being the Guid. This account is then “migrated” to "DomainB", and TFSConfig Identities is run, so this identity record in TFS becomes:

DomainB\foo, G1

If this was a true domain migration in AD within the same forest, this change will persist, because DomainA\foo is gone. But let us say that all that was done was to create a new account in DomainB, and DomainA\foo still exists in AD. Then if TFS ever encounters this account (for example, by group membership sync), then it will revert the identity row back to:

DomainA\foo, G1

This is the auto-Sid migration logic, which keys off of the identity Guid. Note that legitimate identity change, such as workgroup to domain account, or intra-forest AD migration, will never get reverted.

Some aspects of this topic have been discussed in the context of TFS Upgrade in Guidance for upgrading to TFS 2010 along with domain move.