Both newer versions of TFS and VSTS have a comprehensive REST API for permission assignments. While all relevant functions are there, it is not always easy to work the API based on the documentation available.

Official Documentation -> 

How do I know which namespace and token to use?

While there is a call to list out all security namespaces on the server (TFS), a given collection or a given account (VSTS), it can be difficult to work out which one to use for a particular context.

An easy way to retrieve the correct namespace is to use WebAccess with Fiddler or the Network tab in your browser’s developer features.

While the network recording (or Fiddler trace) is running, go to a page that displays permissions. (In this case, I am viewing the permissions for all git repositories in a given project)

A call to “DisplayPermissions” will be registered as the permission pane is loaded in.

This call has two GET parameters that are of interest to us:

  • permissionSetId
    • This is the Namespace ID
    • To cross check what namespace is referenced, you can compare it to the list produced by this call
  • permissionSetToken
    • This is the token used for this access control list
    • We can see that we are asking for the access control list for repoV2/<GUID>
    • The GUID will match the project ID in this case. If we were looking at a particular repo the token would change to: repoV2/<ProjectGUID>/<GitRepoGUID>
    • Token formats are particular to each namespace. Release management for example uses a combination of the project guid, the release definition id (if applicable), and the environment id (if also applicable)

How do Access Control Lists work?

An access control list contains the effective permissions behind a namespace and a token.

In our example where we are looking for repoV2/<ProjectGUID> in the Git Repository namespace, this is the associated Access Control List for a given project guid:

We can use the API to add or remove entries from the access control list.

Why is this useful?

Understanding namespaces and permission tokens is an essential requirement if you are looking to automate permission assignments in TFS or VSTS.

Once you know how to read, add, or remove access control entries, you can start adding/removing accounts in bulk and auditing effective permission assignments.

One practical use case is the automatic assignment or audit of (Azure) AD groups across ACLs that are managed at a project level. (for example: Git repos, Release Definitions, Release Environments, Build Definitions)