TFS automation - User Management
This is part 1 of the TFS automation series, aimed at developers and administrators building systems to automate various portions of the SDLC pipeline. Today we will talk about the automation of user management.
User access management is a critical piece of the TFS automation/administration function, especially at an enterprise scale. When migrating from one version of TFS to another or when merging one LoB instance to an enterprise instance, enterprises often have the need to take stock of the users provisioned and their access to collections and projects, in TFS. During this process, some customers would also need the ability to remove certain accounts (service accounts, expired accounts etc.) from a project/collection. This could be a time-consuming task depending on the number of users and team projects.
In addition, there has been some breaking and some behavioral changes in the API set between the TFS versions (2010 and 2015 as an example). As an example, IGroupSecurityService interface is deprecated as of TFS 2012 and it is recommended to use IidentityManagementService for all identity related operations. Similarly, while ICommonStructureService3 was in use for TFS 2010, it has been replaced with IcommonStructureService4 for TFS 2015 and above.
// ICommonStructureService3 is being used for backward compatibility with TFS 2010.
// Replace with ICommonStructureService4, after migration to TFS15
structureSvc = tpCollection.GetService<ICommonStructureService3>();
// IGroupSecurityService is deprecated as of TFS 2012 and needs to be removed, after migration to TFS15
// Use IIdentityManagementService for TFS15
groupSecuritySvc = tpCollection.GetService<IGroupSecurityService>();
// use for TFS15
idMgmtSvc = tpCollection.GetService<IIdentityManagementService>();
In order to perform user management operations, using the TFS object model, we need the below components:
- Microsoft.TeamFoundation.Client
- TfsTeamProjectCollection - create, open and authenticate the connection to TFS
- ICommonStructureService - Used to fetch Team Project info based on name
- IIdentityManagementService - to fetch user identity, verify group membership and add/remove users from a group
- IGroupSecurityService - used for TFS versions lesser than 2012, to list/create/remove user groups
- Microsoft.TeamFoundation.Common
- Supporting classes
These assemblies can be found, typically, in the shared path – C:\Program Files\Common Files\microsoft shared\Team Foundation Server\<version>.
I created a sample in an effort to help customers automate this process. There are 2 components to the sample code:
- The helper library (TFSPermissionHelpers)
- A GUI to help administrators perform batch operations (TFSUserManagementUtil). This uses the helper library internally.
The full code sample for the helper library and the admin GUI is provided on GitHub.
The provided GUI application can be used as-is by administrators to perform bulk operations. The helper library could also be plugged into the user provisioning workflow system, in use by the enterprise (as an example, where there are detailed processes/regulation associated with user access). The library can work with both csv and json formats, to accommodate service-level integration. Another use case would be for customers to use the library and create a self-service portal for users.
The first step is to create a csv/json file that captures the user data. One assumption made here is that addition of users is specific to groups and team projects. However, the removal of users is at a Team Project level (and not at an individual group level). This, of course, can be changed in code to achieve use-cases that need removal of users from specific groups only.
csv format-
DomainName\TFSPowerUser,Contributors|Readers,DemoWeb|CloudDemo
DomainName\TFSDummyUser,Contributors|Readers,DemoWeb|CloudDemo
json format-
[ {
"UserName": "DomainName\\TFSPowerUser",
"GroupNames": [ "Contributors", "Readers" ],
"TeamProjectNames": [ "DemoWeb", "CloudDemo" ]
},
{
"UserName": "DomainName\\TFSDummyUser",
"GroupNames": [ "Contributors", "Readers" ],
"TeamProjectNames": [ "DemoWeb", "CloudDemo" ]
} ]
More detailed documentation, along with the code is available here.
- Anonymous
April 04, 2017
Good one. Great to see you start blogging!