Configure initial groups, teams, members, and permissions

By using the plug-in file for Groups and Permissions, you can configure the initial security settings for a team project. You accomplish this by defining tasks that create security groups, nest groups, define groups as teams, configure initial team settings, assign members to groups, and allow or deny specific permissions to each group. In addition to performing these tasks, you can specify the initial security settings for collection-level, project-level, and project-classification areas.

Microsoft process templates assign several permissions to default groups. You can modify these assignments by customizing the plug-in file for Groups and Permissions. For more information about this plug-in, see Define groups, teams, and permissions using the Groups and Permissions Plug-in.

In this topic

  • Define and assign permissions to groups

  • Group macros and default groups

  • Nest groups and assign members to groups

  • Define a team

  • Assign collection-level permissions

  • Assign project-level permissions

  • Assign permissions to control area paths

  • Assign permissions to control iteration paths

For information about how to configure the initial security settings for a team project's functional areas, such as Team Foundation Build, Team Foundation version control, and Visual Studio Lab Management, see Control access to functional areas.

For information about how to customize types of work items to allow or deny access to groups or users, see Apply a rule to a work item field.

For more information about how to administer users and groups and control access for Visual Studio Application Lifecycle Management (ALM), see Manage users or groups in TFS.

Define and assign permissions to groups

You can use the group and member elements to specify a new security group in Team Foundation Server and add members to that group. You can use the group permission element to assign permissions to a group and to members of that group. You must encapsulate each of these elements within their corresponding container elements: groups, members, and permissions. You use the following the syntax structure for each of these elements:

<group name="Group Name" description="Description of Group"></group>
<member name="MemberName"></member>
<permission name="PermissionName" class="ClassName" allow="True | False"/>

The following table describes the attributes for the group, member, and group permission elements. You use these elements only in the Groups and Permissions plug-in file.

Element

Attribute

Description

group

name

Specifies the name of the group that you are creating.

isTeam

Indicates if the group is a team (true) or not (false).

description

Describes the purpose of the group to other users.

member

name

Specifies the name of a group that you are adding as a member of another group. You can create groups and pre-populate them with any of the following types of members:

  • Default groups that are defined in Team Foundation Server

  • Project groups that have been previously created in the groupsandpermissions.xml file (for example, [$$PROJECTNAME$$]\Contributors)

  • Groups and users who are defined in Active Directory, which you specify by using the following format:

    • DOMAIN\USERNAME

    • DOMAIN\GROUPNAME

For information about the format to use when you specify default groups, see Group macros and default groups later in this topic.

permission

name

Identifies which permission is being applied. For a list of the supported permissions, see the following sections later in this topic:

  • Assign collection-level permissions

  • Assign project-level permissions

  • Assign permissions to control area paths

  • Assign permissions to control iteration paths

class

Identifies the class, or area, where the group permission is granted. The following values are valid:

  • NAMESPACE: Specifies collection-level permissions.

  • PROJECT: Specifies project-level permissions.

  • CSS_NODE: Specifies permissions for viewing and managing area paths for a team project.

  • ITERATION_NODE: Specifies permissions for viewing and managing iteration paths for a team project.

allow

Uses a true or false value to indicate whether the permission is allowed or denied.

path

Identifies the node of the area path or iteration path where the permission is being applied. This attribute is valid only when class is set to CSS_NODE or ITERATION_NODE.

Group macros and default groups

The following table lists the macros that you can use to specify a default group that is defined in Team Foundation Server.

Note

You can specify the macros in the following table only in the plug-in for Groups and Permissions. You cannot specify these macros when you assign permissions by using the plug-ins for build, version control, or lab management.

Default groups

Macro

Project Collection Administrators

[SERVER]\$$PROJECTCOLLECTIONADMINGROUP$$

[SERVER]\$$TEAMFOUNDATIONADMINGROUP$$

$$COLLECTIONADMINGROUP$$

Project Collection Service Accounts

[SERVER]\$$PROJECTCOLLECTIONSERVICESGROUP$$

Project Collection Build Service Accounts

[SERVER]\$$PROJECTCOLLECTIONBUILDSERVICESGROUP$$

$$COLLECTIONBUILDSERVICESGROUP$$

Project Collection Build Administrators

[SERVER]\$$PROJECTCOLLECTIONBUILDADMINSGROUP$$

$$COLLECTIONBUILDADMINISTRATORSGROUP$$

Project Administrators

$$PROJECTADMINGROUP$$

[$$PROJECTNAME$$]\$$PROJECTADMINGROUP$$

[$$PROJECTNAME$$]\Builders

Project creator

$$CREATOR_OWNER$$

@creator

Default team

@defaultTeam

Example: Nest groups and assign members to groups

The following example shows how to configure groups that are named TestGroup1, TestGroup2, and TestGroup3. In this example, you add TestGroup1 as a member of TestGroup2. For this code to be valid, you must define TestGroup1 before you define TestGroup2.

<task id="GroupCreation1"> 
    <taskXml>
      <groups>
        <group name="TestGroup1" description="Test group 1.  Contains no members out of the box.">
          <permissions>
            <permission name="GENERIC_READ" class="PROJECT" allow="true" />
          </permissions>
        </group>
        <group name="TestGroup2" description="Test group 2.  Contains TestGroup1 and Project Administrators.">
          <permissions>
            <permission name="GENERIC_READ" class="PROJECT" allow="true" />
          </permissions>
          <members>
            <member name="TestGroup1" />
            <member name="$$PROJECTADMINGROUP$$" />
          </members>
        </group>
        <group name="TestGroup3" description="Test group 3. Contains DOMAIN\USER, DOMAIN\GROUP, Project Administrators, and Project Collection Build Service Accounts.">
          <permissions>
            <permission name="GENERIC_READ" class="PROJECT" allow="true" />
          </permissions>
          <members>
            <member name="DOMAIN\USER" />
            <member name="DOMAIN\GROUP" />
            <member name="[$$PROJECTNAME$$]\$$PROJECTADMINGROUP$$" />
            <member name="[SERVER]\$$PROJECTCOLLECTIONBUILDSERVICESGROUP$$" />
          </members>
        </group>
      </groups>
    </taskXml>
</task>

Define a team

In addition to creating groups, you can assign a group as a team. Creating a team project also creates a default team. If you have several teams that want to organize their work separately from the other teams, then you can either define these teams within the Groups and Permissions plug-in file, or you can configure them after you create the team project. See Add another team or a hierarchy of teams.

The following example shows how to configure a group as a team. In this example, you specify the group, Dream Team, as a team and add the team project creator as a member of the team. Whatever iteration paths that you specify for the team must be defined in the Classifications plug-in file. See Define the initial areas and iterations in the classification plug-in.

<group name="Dream Team" isTeam="true" description="Next generation work">
   <permissions>
      <permission name="GENERIC_READ" class="PROJECT" allow="true" />
   </permissions>
   <members>
      <member name="@creator"/>
   </members>
   <teamSettings areaPath="Area">
      <iterationPaths backlogPath="Iteration">
         <iterationPath path="Release 1\Sprint 1" />
         <iterationPath path="Release 1\Sprint 2" />
         <iterationPath path="Release 1\Sprint 3" />
         <iterationPath path="Release 1\Sprint 4" />
         <iterationPath path="Release 1\Sprint 5" />
         <iterationPath path="Release 1\Sprint 6" />
      </iterationPaths>
   </teamSettings>
</group>

Assign collection-level permissions

You can assign collection-level permissions by using the group permission element and the NAMESPACE class. These permissions control access to resources that are available across team projects. You can set collection-level permissions for only the following 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

For the format to use when you specify groups, see Group macros and default groups earlier in this topic.

Note

You can set these permissions by right-clicking the server in Team Explorer and then clicking Security, by opening and using the administration console for Team Foundation, or by using the TFSSecurity and tf command-line tools. For more information, see Collection-Level Groups, Change groups and permissions with TFSSecurity, and Permission Command.

The following example shows how to grant collection-level permissions to the project administrators for a team project.

<group name="PROJECTADMINGROUP" description="Members of this group can add, modify, and delete items within the team project.">
   <permissions>
       <permission name="GENERIC_READ" class="NAMESPACE" allow="true" />
       <permission name="WORK_ITEM_WRITE" class="NAMESPACE" allow="true" />
       <permission name="MANAGE_LINK_TYPES" class="NAMESPACE" allow="true" />
       <permission name="MANAGE_TEMPLATE" class="NAMESPACE" allow="true" />
       <permission name="MANAGE_TEST_CONTROLLERS" class="NAMESPACE" allow="true" />
    </permissions>
</group>

The following table describes the collection-level permissions that you can assign.

Note

By default, no collection-level permissions are assigned in the MSF process templates.

Permission

Description

DIAGNOSTIC_TRACE

Alter trace settings. Can change the trace settings for gathering more detailed diagnostic information about Web services for Team Foundation Server.

CREATE_PROJECTS

Create new projects. Can create projects in the team project collection.

GENERIC_WRITE

Edit collection-level information. Can edit collection-level permissions for users and groups in the team project collection. Users who have this permission can perform the following tasks:

  • Add, remove, or rename a collection-level application group from the collection in Team Foundation Server.

    Note

    You cannot remove default collection-level groups, such as Project Collection Administrators.

  • Add or remove a user or group in Windows user or another application group in Team Foundation Server (at the server level).

  • Change collection-level permissions for users and groups.

Additionally, users who have this permission can modify permissions for version control, and they have write access to all files in version control unless their access is explicitly denied by other permissions.

MANAGE_TEMPLATE

Manage process templates. Can download, create, edit, and upload process templates to the team project collection.

MANAGE_TEST_CONTROLLERS

Manage test controllers. Can register and de-register test controllers for the team project collection.

MANAGE_LINK_TYPES

Manage work item link types. Can add, remove, and change the types of links for work items.

GENERIC_READ

View collection-level information. Can view membership of collection-level groups and the permissions of those users.

Assign project-level permissions

You can assign project-level permissions in the Groups and Permissions plug-in file. You assign these permissions by using the group permission element and the PROJECT class. These permissions control access to a single project's resources. You can grant access to users and groups in Windows, groups in Team Foundation, and groups that you have previously defined in the Groups and Permissions plug-in file. For the format to use when you specify groups, see Group macros and default groups earlier in this topic.

The following example shows how to grant several permissions to the Contributors group for a team project.

<group name="Contributors" description="Members of this group can add, modify, and delete items within the team project.">
   <permissions>
      <permission name="GENERIC_READ" class="PROJECT" allow="true" />
      <permission name="DELETE_TEST_RESULTS" class="PROJECT" allow="true" />
       <permission name="PUBLISH_TEST_RESULTS" class="PROJECT" allow="true" />
       <permission name="VIEW_TEST_RESULTS" class="PROJECT" allow="true" />
       <permission name="MANAGE_TEST_ENVIRONMENTS" class="PROJECT" allow="true" />
      <permission name="MANAGE_TEST_CONFIGURATIONS" class="PROJECT" allow="true" />
   </permissions>
</group>

The following table describes the project-level permissions that you can assign and indicates the default assignments that are made in the MSF process templates.

Permission

Description

Readers

Contributors

Build Administrators

GENERIC_READ

View project-level information. Can view membership of project-level groups and the permissions of those members.

check mark check mark check mark

VIEW_TEST_RESULTS

View test runs. Can view test plans in this node.

check mark check mark check mark

MANAGE_TEST_CONFIGURATIONS

Manage test configurations. Can create and delete test configurations for the team project.

check mark check mark

MANAGE_TEST_ENVIRONMENTS

Manage test environments. Can create and delete test environments for the team project.

check mark check mark

PUBLISH_TEST_RESULTS

Create test runs. Can add and remove test results and add or modify test runs for the team project.

check mark check mark

DELETE_TEST_RESULTS

Delete test runs. Can delete a scheduled test for the team project.

check mark check mark

DELETE

Delete team project. Can delete from Team Foundation Server the project for which the user has this permission.

GENERIC_WRITE

Edit project-level information. Can edit project-level permissions for users and groups in Team Foundation Server.

Assign permissions to control area paths

You can assign permissions that control access to area definitions by using the group permission element and the CSS_NODE class. These permissions control access to a single project's classification structure. You can grant access to users and groups in Windows, groups in Team Foundation, and groups that you have previously defined in the Groups and Permissions plug-in file. For information about the format to use when you specify groups, see Group macros and default groups earlier in this topic.

The following example shows how to grant several permissions to the Contributors group for a team project.

<group name="Contributors" description="Members of this group can add, modify, and delete items within the team project.">
   <permissions>
      <permission name="GENERIC_READ" class="CSS_NODE" allow="true" />
      <permission name="WORK_ITEM_READ" class="CSS_NODE" allow="true" />
      <permission name="WORK_ITEM_WRITE" class="CSS_NODE" allow="true" />
      <permission name="MANAGE_TEST_PLANS" class="CSS_NODE" allow="true" />
   </permissions>
</group>

The following table describes the permissions that you can assign to control access to the hierarchical structure for the project's area and iteration nodes. The table also indicates the default assignments that are made in the MSF process templates.

Note

Some operations for tracking work items require multiple permissions. For example, you need multiple permissions to delete a node.

Permission

Description

Readers

Contributors

Build Administrators

GENERIC_READ

View this node. Can view the security settings for an area node.

check mark check mark check mark

WORK_ITEM_READ

View work items in this node. Can view, but not change, work items that are assigned to an area node.

check mark check mark check mark

WORK_ITEM_WRITE

Edit work items in this node. Can edit work items that are assigned to an area node.

check mark check mark

MANAGE_TEST_PLANS

Manage test plans. Can create and edit test plans that are assigned to an area node. If test plans have not been run, you can also delete them.

check mark check mark

CREATE_CHILDREN

Create and order child nodes. Can create area nodes. Users who have both this permission and the GENERIC_WRITE permission can move or re-order any child area node.

DELETE

Delete this node. Can delete area nodes.

Users who have both this permission and the GENERIC_WRITE 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.

GENERIC_WRITE

Edit this node. Can set permissions for and rename area nodes.

Assign permissions to control iteration paths

You assign permissions that control access to iteration paths by using the group permission element and the ITERATION_NODE class. These permissions control access to the milestone releases or iterations for a single project. You can grant access to users and groups in Windows, groups in Team Foundation, and groups that you have previously defined in the Groups and Permissions plug-in file. For information about the format to use when you specify groups, see Group macros and default groups earlier in this topic.

The following example shows how to grant several permissions to the Contributors group for a team project:

<group name="Contributors" description="Members of this group can add, modify, and delete items within the team project.">
   <permissions>
      <permission name="GENERIC_READ" class="ITERATION_NODE" allow="true" />
      <permission name="GENERIC_WRITE" class="ITERATION_NODE" allow="true" />
      <permission name="CREATE_CHILDREN" class="ITERATION_NODE" allow="true" />
   </permissions>
</group>

The following table describes the permissions that you can assign to control access to the hierarchical structure for the project's iteration nodes. Because the MSF process templates do not specify any ITERATION_NODE permissions, all team members can create, view, and delete iteration nodes.

Note

Some operations for tracking work items require multiple permissions. For example, you need multiple permissions to delete a node.

Permission

Description

GENERIC_READ

View this node. Can view the security settings for a node.

CREATE_CHILDREN

Create and order child nodes. Can create iteration nodes. Users who have both this permission and the GENERIC_WRITE permission can move or re-order any iteration node.

DELETE

Delete this node. Can delete iteration nodes.

Users who have both this permission and the GENERIC_WRITE 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.

GENERIC_WRITE

Edit this node. Can set permissions for iteration nodes and rename nodes.

See Also

Concepts

Define groups, teams, and permissions using the Groups and Permissions Plug-in

Control access to functional areas

Manage users or groups in TFS

Permission reference for Team Foundation Server