You can control access to the team projects and team project collections in your deployment of Visual Studio Team Foundation Server (TFS) by understanding and configuring the permissions that are assigned to the users and groups in that deployment. Team Foundation Server includes several utilities to help you view and manage permissions. For individual users and groups, use Team Web Access by following the procedures in View or change your permissions or join another team, or use Team Explorer by following the procedures in Change Permissions for a Group or User. You can also use these tools to deny users access to team projects. For more information, see Restricting access to projects in the deployment.
This is a reference topic about all the permissions available in a TFS deployment and what they do. For step-by-step examples of how to create custom groups, configure permissions to control access to resources, and other options, see Restrict access in TFS.
 Note |
|---|
This topic does not discuss the permissions for SharePoint Products or SQL Server Reporting Services. This topic discusses only those permissions that you set in TFS. For more information about how to set permissions in Reporting Services and SharePoint Products for users in TFS, see Add Users to Team Projects, Set Administrator Permissions for Team Project Collections, and Set Administrator Permissions for Team Foundation Server. |
In this topic
What's new in permissions
In this release of Team Foundation Server, the management interface for permissions has largely shifted to Team Web Access. You can open Team Web Access in the administration context and view and manage permissions at every level except for the server level. In addition, you can view information about why and how an individual permission has been set for a user or group by hovering over that permission and then choosing the Why? option.
This release of Team Foundation Server also creates a default team group when you create a team project. Although team groups have no manually configurable permissions themselves, membership in this group is required for users to use the Team features in Team Web Access. Additionally, this default team group is automatically added to the Contributors default group for the project. Unless you make modifications, any user you add to the team will have all the permissions attributed to the Contributors group.
Team Web Access has new controls for displaying the features that are available to users, and membership in the access groups for Team Web Access controls whether a user can see and use these controls. You can set access levels for groups and users, as well as set the default level for the entire deployment of TFS. For more information, see
Overview of default permission groups
Permissions determine the authorization for user actions such as workspace administration and project creation. When you create a project in TFS, five default groups are created for that project regardless of your choice of process template. By default, each of these groups has a set of permissions that are defined for them and that govern what members of those groups are authorized to do.
Project Administrators
Contributors
Readers
Build Administrators
The default team group, which has the name of your project appended by Team. For example, if you create a team project named "Code Sample," the group name for the team will be "Code Sample Team."
In addition to the default groups that are created for each team project, when you create a team project collection, seven default groups are created for that collection regardless of your choice of process template. Each of those groups also has a set of permissions that are defined for them.
Project Collection Administrators
Project Collection Service Accounts
Project Collection Build Administrators
Project Collection Build Service Accounts
Project Collection Valid Users
Project Collection Proxy Service Accounts
Project Collection Test Service Accounts
Four default groups are created at the server level when you install Team Foundation Server. Each of these groups has a set of permissions that are defined for them.
Team Foundation Administrators
Team Foundation Service Accounts
Team Foundation Valid Users
SharePoint Web Application Services
To effectively manage user membership in these default groups and to create custom groups, administrators must first understand the meaning of the permissions and the security implications for explicitly setting permissions. For more information about which permissions are assigned by default to each group, see
| Tip |
|---|
Certain features in TFS are only available to users who have the appropriate licensing level for those features. Access to those features is not controlled by permissions but by membership in licensing groups for Team Web Access. For more information, see Add Users to Team Projects, Change access levels, and the licensing whitepaper for Team Foundation Server. |
Permission states
You can specify two explicit authorization states for permissions in Team Foundation Server: Deny and Allow. There is also an implicit authorization that neither sets the permission to Allow nor sets the permission to Deny. This authorization is an implicit Deny state that is referred to as Not set.
Deny
Deny denies authorization for the user or group to perform the actions that are stated in the permission description. Deny is the most powerful permission state in TFS. If a user belongs to a TFS group that has a specific permission set to deny, that user cannot perform that function, even if he or she belongs to another group that has that permission set to allow. The only exception to this rule occurs when the user is a member of the Project Collection Administrators group for a team project collection, or the Team Foundation Administrators group, unless otherwise stated in the description of the permission. By default, if a user is a member of an administrators group, the permissions of that group override an explicit deny for that user in Team Foundation Server. If a permission setting overrides the default administrative permission, that override is noted in the description of the permission in the tables below.
Allow
Allow grants authorization for the user or group to perform the actions that are stated in the permission description. Allow is the second-most powerful permission state in TFS and is set most frequently, both explicitly and through inheritance to inherited allow. If you do not explicitly set a permission to allow, or membership in a default group does not set a permission to inherited allow, a user or group cannot perform that action in Team Foundation Server.
Not set
By default, most permissions in TFS are not set to either deny or allow. The permissions are left not set, which implicitly denies both users and groups authorization to perform the actions that are specified in the permission description. However, because the permission is neither explicitly set to deny nor explicitly set to allow, authorization for that permission can be inherited from other groups of which the user or group is a member.
Inheritance
When permission is not set for a user or group, the user or group can be affected by the explicit state for the permission for groups to which they belong because permissions in TFS are inherited. For example, when you review the permissions for a user or group, you might see both allow and inherited allow set for permissions. The latter permission is inherited from some other group the user or group belongs to. In this example, a user might belong to a group at the project level and a group at the collection level in a project. If one of those groups has a permission that is explicitly set to allow and the other group has the same permission not set, the user will have the inherited allow permission to perform the actions that are controlled by that permission. The user inherits permissions from both groups, and the allow permission takes precedence over the not set permission.
To understand why a permission is inherited, you can hover over the permission setting, and then choose Why?. A new window will open that displays the inheritance information for that permission.
| Note |
|---|
Permissions that are set outside TFS, such as in SharePoint Products, are not inherited in TFS. They are not discussed in this topic. |
Certain authorization settings take precedence over other authorization settings. In TFS, the deny permission takes precedence over all other permission settings, including allow, for that explicit structure. The deny permission does not take precedence if it is inherited from a hierarchical parent, such as in version control. For example, a user might belong to two groups in a project. For one group, Publish test results permission is set to deny; the other group has that permission set to allow. The deny setting takes precedence and the user is not authorized to publish test results. The only exceptions to this rule occur when either the explicit deny is inherited from a hierarchical parent or the user is a member of one of the following groups:
Project Administrators
Project Collection Administrators
Team Foundation Administrators
In hierarchical structures such as version control and work item tracking, the explicit permissions that are set on a particular object override those that are inherited from the parent objects.
Setting Permissions
Many of the permissions that you might want to set for TFS are controlled through the Team Web Access user interface, which you can open directly through Team Web Access, or you can open from Team Explorer. You can set permissions on a collection basis (collection-level permissions), on a project basis (project-level permissions), or by adding a user to a team group, a team basis. (Team-level permissions are implicit in membership for a team and not directly configurable.) You can also set area-level and iteration-level permissions for viewing and interacting with work items on a project basis. For more information about how to set permissions for users and groups, see Collaborate (dig deeper) and
To set permissions on a server basis (server-level permissions), you cannot use Team Web Access. You must use the administration console for Team Foundation Server to set server-level permissions.
Server-level permissions
Server-level permissions are not specific to a single team project or team project collection. They are set on a deployment-wide basis, and they grant permissions that can affect every project and collection in the deployment.
You can set these permissions for only two categories of users:
Server-level users and groups, such as Team Foundation Administrators
Custom groups that you create and add to the server level
You can set these permissions by opening the administration console for Team Foundation. You can also set these permissions by using the TFSSecurity command-line tool. For more information, see
The following table lists each server-level permission and provides a brief description of its purpose.
Permission Name | Name at command line | Description | ||
|---|---|---|---|---|
Administer warehouse | ADMINISTER_WAREHOUSE | Users who have this permission can change warehouse settings by using the ChangeSetting Web method of the WarehouseController.asmx Web service. For example, you could allow users to set the update interval for calculating the OLAP cubes. | ||
Create team project collection | CreateCollection | Users who have this permission can create and administer team project collections in Team Foundation Server. | ||
Delete team project collection | DeleteCollection | Users who have this permission can delete a team project collection from the deployment.
| ||
Edit instance-level information | GENERIC_WRITE tf: AdminConfiguration tf: AdminConnections | Users who have this permission can edit server-level permissions for users and groups in Team Foundation Server. They can add or remove server-level application groups from the collection. When set through the menus, the Edit instance-level information permission also implicitly allows the user to modify version control permissions. To grant all these permissions at a command prompt, you must use the tf.exe Permission command to grant the AdminConfiguration and AdminConnections permissions in addition to GENERIC_WRITE. Note Default server-level groups such as Team Foundation Administrators cannot be removed. | ||
Make requests on behalf of others | Impersonate | Users who have this permission can perform operations on behalf of other users or services. This permission should be assigned only to service accounts. | ||
Trigger Events | TRIGGER_EVENT | Users who have this permission can trigger alert events within Team Foundation Server. This permission should be assigned only to service accounts and members of the Team Foundation Administrators group. | ||
Use full Web Access features | FullAccess | Users who have this permission can use all of the features of Team Web Access. If this permission is set to Deny, the user will only see those features permitted for the Limited group in Team Web Access (see Change access levels). A Deny will override any implicit allow, even for accounts that are members of administrative groups such as Team Foundation Administrators. | ||
View instance-level information | GENERIC_READ | Users who have this permission can view server-level group membership and the permissions of those users. |
Collection-level permissions
Collection-level permissions are not specific to a single project. Instead, they are set on a collection-wide basis. You can set these permissions for only three categories of users:
Collection-level users and groups, such as Project Collection Administrators
Project-level groups that have been added to the collection level on your server that is running Team Foundation
Custom groups that you create and add to the collection level
You can set these permissions by choosing the collection in Team Explorer by choosing the Team menu, choosing Team Project Collection Settings, and then choosing Security, or by opening Team Web Access in administration mode, navigating to the collection level, and then choosing the Security tab. You can also set these permissions by using the TFSSecurity command-line tool, except for those command-line tools that have a tf: designation. For those tools with the tf: designation, use the Permission command of the tf command-line utility for version control to set the permissions. For more information, see
Permission Name | Name at Command Line | Description | ||
|---|---|---|---|---|
Administer build resource permissions | Users who have this permission can administer build resources. | |||
Administer Project Server integration | AdministerProjectServer | Users who have this permission can configure the integration of Team Foundation Server with Project Server to support synchronization between the two server products. | ||
Administer shelved changes | tf: AdminShelvesets | Users who have this permission can delete shelvesets created by other users. | ||
Administer workspaces | tf: AdminWorkspaces | Users who have this permission can create workspaces for other users and delete workspaces created by other users. | ||
Alter trace settings | DIAGNOSTIC_TRACE | Users who have this permission can change the trace settings for gathering more detailed diagnostic information about Web services for Team Foundation Server. | ||
Create a workspace | tf: CreateWorkspace | Users who have this permission can create a version control workspace. | ||
Create new projects | CREATE_PROJECTS | Users who have this permission can create projects in the team project collection.
| ||
Delete team project | Delete | Users who have this permission can delete team projects in the team project collection.
| ||
Edit collection-level information | GENERIC_WRITE tf: AdminConfiguration tf: AdminConnections | Users who have this permission can edit collection-level permissions for users and groups in the team project collection. They can add or remove collection-level Team Foundation Server application groups from the collection. When set through the menus, the Edit collection-level information permission also implicitly allows the user to modify version control permissions. To grant all these permissions at a command prompt, you must use the tf.exe Permission command to grant the AdminConfiguration and AdminConnections permissions, in addition to GENERIC_WRITE.
| ||
Make requests on behalf of others | Impersonate | Users who have this permission can perform operations on behalf of other users or services. This permission should be assigned only to service accounts. | ||
Manage build resources | ManageBuildResources | Users who have this permission can manage the build computers, build agents, and build controllers for the team project collection. These users can also grant or deny the View build resources and Use build resources permissions for other users. | ||
Manage process template | MANAGE_TEMPLATE | Users who have this permission can download, create, edit, and upload process templates to the team project collection. | ||
Manage test controllers | MANAGE_TEST_CONTROLLERS | Users who have this permission can register and de-register test controllers for the team project collection. | ||
Manage work item link types | WORK_ITEM_WRITE | Users who have this permission can add, remove, and change the types of links for work items. | ||
Trigger events | TRIGGER_EVENT | Users who have this permission can trigger project alert events within the team project collection. This permission should be assigned only to service accounts. | ||
Use build resources | UseBuildResources | Users who have this permission can reserve and allocate build agents. This permission should be assigned only to service accounts for build services. | ||
View build resources | ViewBuildResources | Users who have this permission can view build controllers and build agents that are configured for the collection. To use those resources, you need additional permissions. | ||
View collection-level information | GENERIC_READ | Users who have this permission can view collection-level group membership and the permissions of those users. | ||
View system synchronization information | SYNCHRONIZE_READ | Users who have this permission can call the synchronization application programming interfaces. This permission should be assigned only to service accounts. |
ImportantProject-level permissions
Project-level permissions are specific to a single project's users and groups. You can set these permissions by choosing the project in Team Explorer, choosing Settings, and then choosing Security, or by opening Team Web Access in administration mode, navigating to the project, and then choosing the Security tab. You can also set these permissions by using the TFSSecurity command-line tool.
Permission Name | Name at Command Line | Description |
|---|---|---|
Create test runs | PUBLISH_TEST_RESULTS | Users who have this permission can add and remove test results and add or modify test runs for the team project. |
Delete team project | DELETE | Users who have this permission can delete the project for which they have this permission from Team Foundation Server. |
Delete test runs | DELETE_TEST_RESULTS | Users who have this permission can delete a scheduled test for this team project. |
Edit project-level information | GENERIC_WRITE | Users who have this permission can edit project-level permissions for users and groups on Team Foundation Server. |
Manage test configurations | MANAGE_TEST_CONFIGURATIONS | Users who have this permission can create and delete test configurations for this team project. |
Manage test environments | MANAGE_TEST_ENVIRONMENTS | Users who have this permission can create and delete test environments for this team project. |
View project-level information | GENERIC_READ | Users who have this permission can view project-level group membership and the permissions of those project users. |
View test runs | VIEW_TEST_RESULTS | Users who have this permission can view test plans in this node. |
Build-level permissions
Build-level permissions are specific to a single project's users and groups. You can set build permissions at the team project level, and you can also set permissions for specific build definitions. You can set these permissions by opening the project in Team Explorer, choosing Builds, and under Actions, choosing Security. You can apply permissions to a specific build definition by choosing the build definition and then choosing Security. If you want to apply permissions to a build folder, select that folder, and from its sub-menu, choose Security. Additionally, you can set these permissions by using the TFSSecurity command-line tool.
Permission Name | Name at Command Line | Description |
|---|---|---|
Administer build permissions | Users who have this permission can administer the build permissions for other users. | |
View builds | ViewBuilds | Users who have this permission can view the queued and completed builds for this team project. |
Edit build quality | EditBuildQuality | Users who have this permission can add information about the quality of the build through the user interface for Team Foundation Build. |
Retain indefinitely | RetainIndefinitely | Users who have this permission can mark a build so that it will not be automatically deleted by any applicable retention policy. |
Delete builds | DeleteBuilds | Users who have this permission can delete a completed build. |
Manage build qualities | ManageBuildQualities | Users who have this permission can add or remove build qualities. |
Destroy builds | DestroyBuilds | Users who have this permission can permanently delete a completed build. |
Update build information | UpdateBuildInformation | Users who have this permission can add build information nodes to the system, and can also add information about the quality of a build. This permission should be assigned only to service accounts. |
Queue builds | QueueBuilds | Users who have this permission can put a build in the queue through the interface for Team Foundation Build or at a command prompt. They can also stop the builds that they have queued. |
Manage build queue | ManageBuildQueue | Users who have this permission can cancel, re-prioritize, or postpone queued builds. |
Stop builds | StopBuilds | Users who have this permission can stop any build that is in progress, including builds queued and started by another user. |
View build definition | ViewBuildDefinition | Users who have this permission can view the build definitions that have been created for the team project. |
Edit build definition | EditBuildDefinition | Users who have this permission can create and modify build definitions for this project. |
Delete build definition | DeleteBuildDefinition | Users who have this permission can delete build definitions for this project. |
Override check-in validation by build | OverrideBuildCheckInValidation | Users who have this permission can commit a changeset that affects a gated build definition without triggering the system to shelve and build their changes first. This permission should be assigned only to service accounts for build services and to build administrators who are responsible for the quality of the code. For more information, see Check in to a Folder that is Controlled by a Gated Check-in Build Process. |
Work item query permissions
Work item query permissions are specific to the queries and query folders that you create. You can set permissions on queries and folders that are created under Team Queries to enable or restrict access. You can set these permissions by choosing the project in Team Explorer, opening Work Items, opening the sub-menu for the query or folder for which you want to set permissions, and then choosing Security. You can also set these permissions on the query in Team Web Access. Additionally, you can set these permissions by using the TFSSecurity command-line tool.
Permission Name | Name at Command Line | Description |
|---|---|---|
Contribute | CONTRIBUTE | Users who have this permission can view and modify this query or query folder. |
Delete | DELETE | Users who have this permission can delete a query or query folder and its contents. |
Manage Permissions | MANAGEPERMISSIONS | Users who have this permission can manage the permissions for this query or query folder. |
Read | READ | Users who have this permission can view and use the query or the queries in a folder, but cannot modify the query or query folder contents. |
Area-level permissions for work item tracking
Area-level permissions are specific to a single project's users and groups. You can set these permissions by choosing the project in Team Explorer, choosing Settings, choosing Work Item Areas, choosing the down arrow, and then choosing Security, or by opening Team Web Access in the administration context, navigating to the project level, choosing the Areas tab, choosing the down arrow, and then choosing Security. Additionally, you can set these permissions by using the TFSSecurity command-line tool.
| Note |
|---|
Some work item tracking operations require multiple permissions. For example, you need multiple permissions to delete a node. |
Permission Name | Name at Command Line | Description |
|---|---|---|
Create child nodes | CREATE_CHILDREN | Users who have this permission can create area nodes. Users who have both this permission and the Edit this node permission can move or re-order any child area nodes. |
Delete this node | DELETE | Users who have both this permission and the Edit this node permission for another node can delete area nodes and reclassify existing work items from the deleted node. If the deleted node has child nodes, those nodes are also deleted. |
Edit this node | GENERIC_WRITE | Users who have this permission can set permissions for this node and rename area nodes. |
Edit work items in this node | WORK_ITEM_WRITE | Users who have this permission can edit work items in this area node. |
Manage test plans | MANAGE_TEST_PLANS | Users who have this permission can create and edit test plans for this node. If test plans have not been run, you can also delete them. |
View permissions for this node | GENERIC_READ | Users who have this permission can view the security settings for this node. |
View work items in this node | WORK_ITEM_READ | Users who have this permission can view, but not change, work items in this area node. If this permission is set to Deny, the user will not be able to see any work items in this area node. A Deny will override any implicit allow, even for accounts that are members of administrative groups such as Team Foundation Administrators. |
Iteration-level permissions for work item tracking
Iteration-level permissions are specific to a single project's users and groups. You can set these permissions by choosing the project in Team Explorer, choosing Settings, choosing Work Item Iterations, choosing the down arrow, and then choosing Security, or by opening Team Web Access in the administration context, navigating to the project level, choosing the Iterations tab, choosing the down arrow, and then choosing Security. Additionally, you can set these permissions by using the TFSSecurity command-line tool.
| Note |
|---|
Some work item tracking operations require multiple permissions. For example, you need multiple permissions to delete a node. |
Permission Name | Name at Command Line | Description |
|---|---|---|
Create child nodes | CREATE_CHILDREN | Users who have this permission can create iteration nodes. Users who have both this permission and the Edit this node permission can move or re-order any child iteration nodes. |
Delete this node | DELETE | Users who have both this permission and the Edit this node permission for another node can delete iteration nodes and reclassify existing work items from the deleted node. If the deleted node has child nodes, those nodes are also deleted. |
Edit this node | GENERIC_WRITE | Users who have this permission can set permissions for this node and rename iteration nodes. |
View permissions for this node | GENERIC_READ | Users who have this permission can view the security settings for this node. |
Version Control Permissions
Version control permissions are specific to source code files and folders. You can set these permissions by opening the sub-menu for the folder or file in Source Control Explorer, and then choosing Security. You can also set these permissions by using the tf command-line tool for version control.
In version control permissions, explicit deny takes precedence over administrator group permissions.
Permission Name | Name at Command Line | Description |
|---|---|---|
Read | tf: Read | Users who have this permission can read the contents of a file or folder. If a user has Read permissions for a folder, the user can see the contents of the folder and the properties of the files in it, even if the user does not have permission to open the files. |
Check out | tf: PendChange | Users who have this permission can check out and make a pending change to items in a folder. Examples of pending changes include adding, editing, renaming, deleting, undeleting, branching, and merging a file. Pending changes must be checked in, so users will also need the Check in permission to share their changes with the team. |
Check in | tf: Checkin | Users who have this permission can check in items and revise any committed changeset comments. Pending changes are committed at check-in. |
Label | tf: Label | Users who have this permission can label items. |
Lock | tf: Lock | Users who have this permission can lock and unlock folders or files. |
Revise other users' changes | tf: ReviseOther | Users who have this permission can edit the comments on checked-in files, even if another user checked in the file. |
Unlock other users' changes | tf: UnlockOther | Users who have this permission can unlock files locked by other users. |
Undo other users' changes | tf: UndoOther | Users who have this permission can undo a pending change made by another user. |
Administer labels | tf: LabelOther | Users who have this permission can edit or delete labels created by another user. |
Manage permissions | tf: AdminProjectRights | Users who have this permission can manage other users' permissions for folders and files in version control. |
Check in other users' changes | tf: CheckinOther | Users who have this permission can check in changes that were made by other users. Pending changes will be committed at check-in. |
Merge | tf: Merge | Users who have this permission for a given path can merge changes into this path. |
Manage branch | tf: ManageBranch | Users who have this permission for a given path can convert any folder under that path into a branch. Users with this permission can also take the following actions on a branch: edit its properties, re-parent it, and convert it to a folder. Users who have this permission can branch this branch only if they also have the Merge permission for the target path. Users cannot create branches from a branch for which they do not have the Manage Branch permission. |
Lab Management permissions
Visual Studio Lab Management permissions are specific to virtual machines, environments, and other resources. You can set these permissions by using the TFSLabConfig command-line tool.
Permission Name | Name at Command Line | Description |
View Lab Resources | Read | Users who have this permission can view information for the various Lab Management resources, which include collection host groups, project host groups, and environment. To view information about a specific lab resource, you must have the View Lab Resources permission for that resource. |
Manage Lab Locations | ManageLocation | Users who have this permission can edit the locations of Lab Management resources, which include collection host groups, collection library shares, project host groups, and project library shares. To edit a specific location, you must have the Manage Lab Location permission for that location. This permission for collection-level locations (collection host groups and collection library shares) also allows you to create project-level locations (project host group and project library share). |
Delete Lab Locations | DeleteLocation | Users who have this permission can delete the locations for Lab Management resources, which include collection host groups, collection library shares, project host groups, and project library shares. To delete a location, you must have the Delete Lab Location permission for that location. |
Write Environment and Virtual Machines | Write | Users who have this permission for a project host group can create environments. Users who have this permission for a project library share can store environments and templates. |
Edit Environment and Virtual Machines | Edit | Users who have this permission can edit environments and templates. The permission is checked for the object that is being edited. |
Delete Environment and Virtual Machine | Delete | Users who have this permission can delete environments and templates. The permission is checked for the object that is being deleted. |
Import Virtual Machine | Create | Users who have this permission can import a virtual machine from a VMM library share. This permission differs from Write because it only creates an object in Lab Management and does not write anything to the Virtual Machine Manager host group or library share. |
Manage Permissions | ManagePermissions | Users who have this permission can modify the permissions for a Lab Management object. This permission is checked for the object whose permissions are being modified. |
Manage Child Permissions | ManageChildPermissions | Users who have this permission can change the permissions of all the child Lab Management objects. For example, if a user has Manage Child Permission for a team project host group, the user can change permissions for all the environments under that team project host group. |
Start | Start | Users who have this permission can start an environment. |
Stop | Stop | Users who have this permission can stop an environment. |
Pause Environment | Pause | Users who have this permission can pause an environment. |
Manage Snapshots | ManageSnapshots | Users who have this permission can perform all snapshot management tasks for an environment, which include taking a snapshot, reverting to a snapshot, renaming a snapshot, deleting a snapshot, and reading a snapshot. |
See Also
Tasks
Concepts
Other Resources
