Add permissions with TFSSecurity–The ultimate reference

UPDATE 7/15/2015: Hayder Casey from Microsoft provided me with the details on using the Tagging namespace. You can use this one to set the [Create Tag Definition] security setting.

UPDATE 4/25/2016: Microsoft has now updated MSDN to have  decent documentation on MSDN found here

Sooner or later, every TFS Administrator will face the challenge to set TFS Permissions with a script instead of the UI. When you start searching for this you will find TFSSecurity.

TFSSecurity is a command line tool and allows you to do all kinds of permissions activities. Adding groups, adding users to groups and setting permissions to artifacts in TFS. On of the hard things in TFS is the number of permissions you can set and the number of places where you can set them. You can find a list with all permissions in TFS on MSDN.

So, you have found TFSSecurity and you know what you want to set..Great ! Now you need to understand the TFSSecurity syntax. And that is, to say it nicely, very very hard.

To set permissions you need TFSSecurity /a+. The syntax of TFSSecurity looks like this

TFSSecurity /a+ Namespace Token Action Identity (ALLOW | DENY)
[/collection:CollectionURL] [/server:ServerURL]

With the server permissions you can find the namespace and action but Token cannot be found 
anywhere. Even worse. The token varies per namespace. For example the token for the 
VersionControlItems namespace is $/<project> and for the Iteration namespace 

vstfs:///Classification/Node/<guid>

There are many blog posts, forum posts other resources that show a number of these, but a complete list cannot be found anywhere. My colleague Fokko Veegens started a list and together with him we created this reference. Hope you will find it useful.

The reference

In the table below you will find the format of the Token for every namespace. This applies for all actions. pieces within [brackets] are optional.

Namespace Token Example
VersionControlItems $/<TeamProjectName>[/FolderName/ItemName] $/ProjectA
$/ProjectA/MAIN
$/ProjectA/MAIN/item.cs
WorkItemQueryFolders $/<teamprojectGuid>/
<queryfolderguid>
$/d1a506e1-07ee-4977-be51-a13ef280d544/7870b79b-bc41-45a3-b706-4a853dd4649b/
Git Repositories repositories/[<repositoryGuid>] repositories/
repositories/e316a5f1-35da-4618-98b8-8537108a7cfb/
Registry ?? ??
WorkItemTrackingProvision $/[TeamProjectGuid] $/
$/d1a506e1-07ee-4977-be51-a13ef280d544
Identity ?? ??
Job ?? ??
StrongBox StrongBox/ StrongBox/
Server FrameworkGlobalSecurity FrameworkGlobalSecurity
Collection NAMESPACE: NAMESPACE:
BuildAdministration BuildPrivileges BuildPrivileges
VersionControlPrivileges Global Global
Workspaces <empty> (cannot be set from tfssecurity as it requires a parameter for token)
ProjectServerAdministration ProjectServerPrivileges ProjectServerPrivileges
Project $PROJECT:vstfs:///Classification
/TeamProject
/<teamProjectGuid>
$PROJECT:vstfs:///Classification
/TeamProject
/d1a506e1-07ee-4977-be51-a13ef280d544
EventSubscription $SUBSCRIPTION:
CSS AreaUri

vstfs:///Classification/Node/
<AreaGuid>

vstfs:///Classification/Node
/531faeae-deda-4cda-a14a-aba0f2cf66a6
TeamLabSecurity $/
Iteration IterationUri

vstfs:///Classification/Node/
<iterationGuid>

vstfs:///Classification/Node
/16d52dcd-2908-41a2-88ec-b2a7315f0f90
Build <TeamProjectGuid> d1a506e1-07ee-4977-be51-a13ef280d544
Chat chatrooms/
Tagging /[TeamProjectGuid]/[TagId]/  You can pass in the ID of a tag but security on separate tags is not recommended. therefore use the TeamProjectGuid to set security on creating tags.

example: //d1a506e1-07ee-4977-be51-a13ef280d544

Some tips on retrieving tokens

So, now you know what to fill in, but how do you get all this guids and tokens ? Here are some tips

Use the api

When you use the TFS Api, you can find some guids quite easily. Fellow MVP’s Tarun Arora and Shai Raiten have very detailed posts about using the API.

In short.

  • Add a reference to Microsoft.TeamFoundation.Client.dll and Microsoft.TeamFoundation.WorkitemTracking.Client.dll

Use this code snippet to connect to TFS

public void GetSomeIDs()
{
  TfsTeamProjectCollection tpc = TfsTeamProjectCollectionFactory.
    GetTeamProjectCollection(new Uri("http://server:8080/tfs/
    DefaultCollection"));
  WorkItemStore wiStore = tpc.GetService<WorkItemStore>();
  ProjectCollection pc = wiStore.Projects;
  ICommonStructureService4 css = tpc.GetService<ICommonStructureService4>();

  for (int i = 0; i < pc.Count; i++)
  {
    Project p = pc[i];

    NodeInfo areaRootNode = css.GetNodeFromPath(string.Format("{0}\\{1}", 
      p.Name, "Area"));
    string areaUri = areaRootNode.Uri.ToString();
    NodeInfo iterationRootNode = css.GetNodeFromPath(string.Format("{0}\\{1}", 
      p.Name, "Iteration"));
    string iterationUri = iterationRootNode.Uri.ToString();

    //Shared Query Folder
    var q = p.QueryHierarchy as QueryFolder;
    string sharedQueryId = q["Shared Queries"].Id.ToString();

    //TeamProjectID
    string teamprojectID = p.Id.ToString();
  }
}

 

 

Use the UI and Sql

When you need to check some things. Set the permission to deny in the UI and check the tfs_collection database with these commands

select * from tbl_SecurityAccessControlEntry 
where denypermission > 0

select * from tbl_SecurityTokenDelta 
order by ChangeDate desc

Helper Excel

Fokko and I created an excel sheet that you can use to easily generate you own commands. Just fill in the grey fields. The EXECUTE Column contains the full TFSSecurity command

image

Download the sheet here

Resources:

As said. There are many resources. Could not have done this without them. First Fokko Veegens who created a initial list. Jasper Gilhuis for some code to retrieve some Id’s

Advertisements

10 Responses to “Add permissions with TFSSecurity–The ultimate reference”

  1. great tip! thanks!

  2. I tried to use the TFSSecurity to set “Create Tag Definition” permission but seems that my server doesn’t have the namespace Tagging… is there somewhere a sample how to apply this setting? Didn’t find it anywhere.

  3. This just saved me a great deal of hassle. Thanks a ton for listing down the token formats 🙂

  4. Thank you very much. Gave me a lot of hints.
    I searched a long time how to build the token for build definitions. In analysing the browser traffic I found it.
    After the project GUID you can add slash-Builddefinition-ID e.g.:
    d1a506e1-07ee-4977-be51-a13ef280d544/33
    for BuildDefintionId 33.

    Perhaps helpfull for someone else.

Trackbacks/Pingbacks

  1. Team Foundation Server (TFS) – Client – Command Line Tooling – Permissions | Daniel Adeniji's - Learning in the Open - January 6, 2015

    […] Add permissions with TFSSecurity–The ultimate reference https://roadtoalm.com/2014/07/28/add-permissions-with-tfssecuritythe-ultimate-reference/ […]

  2. Administrando usuários, grupos e permissões no console com TFSSecurity - egomesbrandao | blog - January 17, 2017

    […] Eu uso uma tabela compartilhada pelo Rene van Osnabrugge, aqui. […]

%d bloggers like this: