Control Access to Functional Areas

You can configure the initial security settings for the following functional areas for a team project: team queries, Team Foundation version control, Team Foundation Build, and Visual Studio Lab Management. The process templates for Microsoft Solutions Framework (MSF) assign several permissions to default security groups. You can modify these assignments by customizing the plug-in file for the appropriate functional area. 

For information about how to configure security groups for Visual Studio Team Foundation Server, see Configure Initial Groups, Members, and Permissions.

In this topic

• Assigning Permissions to Functional Areas By Using the Functional Permission Element

• Assigning Permissions for Work Item Queries

• Assigning Permissions for Version Control

• Assigning Permissions for Build

• Assigning Permissions for Lab Management

For more information about how to administer users and groups and control access to Visual Studio Application Lifecycle Management (ALM), see Configuring Users, Groups, and Permissions.

Assigning Permissions to Functional Areas By Using the Functional Permission Element

You can use the functional permission element to allow or deny permissions for functional areas to a security group in Team Foundation Server, a Windows group, or a Windows identity. You use this element in the plug-in files for work item tracking, Team Foundation version control, Team Foundation Build, and Lab Management. You must encapsulate the permission element within its corresponding container: the permissions element. You use the following syntax structure for the functional permission element:

<permission allow="PermissionName" identity="GroupName"/>
<permission deny="PermissionName" identity="GroupName"/>
<permission allow="PermissionName" deny="PermissionName" identity="GroupName"/>

The following table describes the attributes for the functional permission element:

Attribute	Description
allow	Identifies the permissions that are granted. You specify permissions as comma-delimited text. For the names of the permissions that have been defined for each functional area, see the following sections later in this topic: Assigning Version Control Permissions Assigning Build Permissions Assigning Lab Management Permissions
deny	Identifies the permissions that are revoked. You specify permissions as comma-delimited text. Note Denied permissions take precedence over allowed permissions.
identity	Specifies the security group in Team Foundation Server, the Windows group, or the Windows identity to which the permissions are applied. For the format to use when you specify groups, see "Default Groups Defined in Team Foundation Server" in Configure Initial Groups, Members, and Permissions.

The following example shows how to grant permissions to allow the Contributors group to view builds and build definitions and to queue builds and edit build quality.

<taskXml>
   <permission allow="Read, PendChange, Checkin, Label, Lock" identity="[$$PROJECTNAME$$]\Contributors"/>
</taskXml>

Note

During runtime, if a permission cannot be found for an identity, the permission is searched for in any other groups to which the identity belongs. If the permission cannot be found, the permission is denied by default.

Assigning Permissions for Work Item Queries

In the workitems plug-in file, you can assign permissions that control access to team query folders. Query folder permissions are specific to queries and query folders. You can grant access to users and groups in Windows or to default groups that are defined for Team Foundation Server.

You assign these permissions by using the functional permission element, as the following example shows:

<Permission allow="Read, Contribute, Delete, ManagePermissions, FullControl" identity="="[$$PROJECTNAME$$]\$$PROJECTADMINGROUP$$" /> 

Note

After the team project is created, you can set permissions by right-clicking a query folder or query in Team Explorer and then clicking Security. For more information, see Organize and Set Permissions on Work Item Queries.

The following table describes the permissions that control access to query folders and queries. It also indicates the default assignments that are made in the MSF process templates. By default, the creators or owners of queries and query folders have full control of managing the queries that they created or own.

Permission	Description	Readers, Contributors, Builders	Creator Owners, Project Administrator Group, Project Collection Administrators
Read	Read. Can view and run a query or view a query folder and its contents
Contribute	Contribute. Can view and edit a query or query folder and its contents
Delete	Delete. Can view, edit, and delete a query or query folder and its contents
ManagePermissions	Manage Permissions. Can manage permissions for a query or query folder and its contents
FullControl	Full Control. Can view, edit, delete, and manage permissions for a query or query folder and its contents

Assigning Permissions for Version Control

You can assign permissions that control access to source code files and folders by changing the plug-in file for version control. Version control permissions are specific to source code files and folders. You can grant access to users and groups in Windows or default groups that are defined for Team Foundation Server.

You assign these permissions by using the functional permission element, as the following example shows:

<permission allow="Read, PendChange, Checkin, Label, Lock, Merge" identity="[$$PROJECTNAME$$]\@@Contributors@@" />

Note

After the team project is created, you can set these permissions by right-clicking the folder or file in Source Control Explorer, clicking Properties, and clicking the Security tab. On that tab, you can click the user or group for which you want to change permissions and then edit the permissions that are listed in Permissions. You can also set these permissions by using the tf command-line tool for version control or the TFSSecurity command-line tool. For more information, see Control Access to Team Foundation Version Control.

The following table describes the permissions that control access to source code files and folders. It also indicates the default assignments that are made in the MSF process templates.

Permission	Description	Readers	Contributors	Builders	Project Administrator Group
Read	Read. Can display the contents of a file or folder. If a user has Read permissions for a folder but not the files that it contains, the user can display the names and properties of those files, but the user cannot open them.
PendChange	Check out. Can check out and make a pending change to an item. Examples of pending changes include adding, editing, renaming, deleting, undeleting, branching, and merging a file.
Merge	Merge. Can merge changes into the path for which they have permissions.
Checkin	Check in. Can check in items and revise any committed changeset comments. Pending changes are committed when the user checks in the item.
Label	Label. Can label items.
Lock	Lock. Can lock an item so that other users cannot update it.
ReviseOther	Revise another user's changes. Can change the contents of someone else’s changeset comments and check-in notes.
UnlockOther	Unlock another user's changes. Can remove someone else’s lock.
UndoOther	Undo another user's changes. Can undo someone else’s pending changes.
LabelOther	Administer labels. Can modify someone else’s label.
AdminProjectRights	Manage permissions. Can configure security settings for version control.
CheckinOther	Check in another user's changes. Can perform a check-in as another user. This permission is required for conversion utilities.
ManageBranch	Manage branch. Users who have this permission for a given path can convert any folder under that path into a branch. Users who have this permission for a branch can also 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.

Assigning Permissions for Build

You can assign permissions that control access to build activities by changing the Build plug-in file. You can grant access to users and groups in Windows and groups in Team Foundation Server. For information about the format to use when you specify groups, see "Default Groups Defined in Team Foundation Server" in Configure Initial Groups, Members, and Permissions.

You assign these permissions by using the functional permission element, as the following example shows:

<Permission allow="ViewBuildDefinition, QueueBuilds, ViewBuilds, EditBuildQuality" identity="[$$PROJECTNAME$$]\@@Contributors@@" />

Note

After the team project is created, you can set these permissions by opening the project in Team Explorer, right-clicking Builds, and then clicking Security. You can apply permissions to a specific build definition by right-clicking the build definition and then clicking Security. If you want to apply permissions to a build folder, right-click it, and then click Security. Additionally, you can set these permissions by using the TFSSecurity command-line tool. For more information, see Managing Permissions.

The following table describes the permissions that you can assign that control access to the build functions of a team project. The table also indicates the default assignments that are made in the MSF process templates.

Note

The Override check-in validation by build 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.

Permission	Description	Readers	Contributors	Build Administrators	Project Administrators	Project Collection Administrators
ViewBuildDefinition	View build definition. Can view the build definitions that have been created for the team project.
ViewBuilds	View builds. Can view the queued and completed builds for this team project.
EditBuildQuality	Edit build quality. Can add information about the quality of the build through the interface for Team Foundation Build.
QueueBuilds	Queue builds. Can add a build to the queue through the interface for Team Foundation Build or at a command prompt.
DeleteBuildDefinition	Delete build definition. Can delete build definitions.
DeleteBuilds	Delete builds. Can delete a completed build.
DestroyBuilds	Destroy builds. Can permanently delete a completed build.
EditBuildDefinition	Edit build definition. Can create and modify build definitions.
ManageBuildQualities	Manage build qualities. Can add or remove build qualities, such as Ready for Deployment, Rejected, or Under Investigation. For more information, see Add or Remove Build Quality Values.
ManageBuildQueue	Manage build queue. Can cancel, re-prioritize, or postpone queued builds.
RetainIndefinitely	Retain indefinitely. Can mark a build so that it will not be automatically deleted by any applicable retention policy.
StopBuilds	Stop builds. Can stop a build that is in progress.
OverrideBuildCheckInValidation	Override check-in validation by build. Can commit a changeset that affects a gated build definition without triggering the system to shelve and build the changes first. For more information, see Check in to a Folder that is Controlled by a Gated Check-in Build Process.
UpdateBuildInformation	Update build information. Can add information about the quality of a build. This permission should be assigned only to service accounts.

Assigning Permissions for Lab Management

You can control access to activities in Lab Management by changing the Lab plug-in file. Permissions for Lab Management are specific to virtual machines, environments, and other resources. You can grant access to users and groups in Windows and groups in Team Foundation Server. You assign these permissions by using the functional permission element, as the following example shows:

<permission allow="Read, Create, Write, Edit, Start, Stop, ManageSnapshots, Pause" identity="[$$PROJECTNAME$$]\@@Contributors@@" />

Note

You can set permissions for Lab Management by using the TFSLabConfig command-line tool. To display information about a specific lab resource, you must have the Read permission for that resource. To delete a location, you must have the Delete Lab Locations permission for that location. For more information, see TFSLabConfig Permissions Command.

The following table describes the permissions that you can assign to control access to Visual Studio Lab Management. The table also indicates the default assignments that are made in the MSF process templates.

Permission	Description	Readers	Contributors	Project Collection Build Service Accounts group	Team Project Administrators group	Project Collection Administrators group
Read	View lab resources. Can view information for the various resources for Lab Management, which include collection host groups, project host groups, and environments.
Create	Import virtual machine. Can import a virtual machine from a Virtual Machine Manager (VMM) library share. This permission differs from Write because users can create an object in Lab Management but not write anything to the VMM host group or library share.
Write	Write environment and virtual Machines. Can create environments. Users who have this permission for a project library share can store environments and virtual machines.
Edit	Edit Environment and Virtual Machines. Can edit environments and virtual machines. The permission is checked for the object that is being edited.
Start	Start. Can start an environment.
Stop	Stop. Can stop an environment.
Pause	Pause. Can pause an environment.
ManageSnapshots	Manage snapshots. Can perform all snapshot management tasks, which include taking a snapshot, reverting to a snapshot, renaming a snapshot, deleting a snapshot, and reading a snapshot.
Delete	Delete environments and virtual machines. Can delete environments and virtual machines. The permission is checked for the object that is being deleted.
ManageLocation	Manage lab locations. Can edit the locations of resources for Lab Management, which include collection host groups, collection library projects, project host groups, and project library shares. This permission for collection-level locations (collection host groups and collection library shares) also allows a user to create project-level locations (project host groups and project library shares).
DeleteLocation	Delete lab locations. Can delete the locations of resources for Lab Management, which include collection host groups, collection library shares, project host groups, and project library shares.
ManageChildPermissions	Manage Child Permissions. Can change the permissions of all the child objects of Lab Management. For example, if a user has this permission for a team project host group, that user can change permissions for all the environments under that group.
ManagePermissions	Manage Permissions. Can modify the permissions for an object of Lab Management. This permission is checked for the object whose permissions are being modified.
EnvironmentOps	Environment Operations. Can start, stop, pause, and manage snapshots, in addition to performing other operations on an environment.

See Also

Concepts

Configure Initial Groups, Members, and Permissions

Customize Functional Areas within a Process Template

Other Resources

Control Access to Team Foundation Version Control