Dela via


Use TFSSecurity to manage groups and permissions for Azure DevOps

Azure DevOps Server 2022 | Azure DevOps Server 2020 | Azure DevOps Server 2019

You can use the TFSSecurity command-line tool to create, modify, and delete groups and users in Azure DevOps Server, and additionally modify permissions for groups and users. For information about how to perform these tasks in the user interface, see Add users or groups to a project.

Important

The TFSSecurity command-line tool has been deprecated for use with Azure DevOps Services. While TFSSecurity may work for some Azure DevOps Services scenarios, it is not supported. The recommended method to make changes to security groups and permissions for Azure DevOps Services is either using the Web portal, the az devops security or az devops permission command line tools, or the Security REST API.

Command-line tool location

Azure DevOps command line tools are installed in the /Tools directory of an Azure DevOps application-tier server.

  • Azure DevOps Server 2020: %programfiles%\Azure DevOps Server 2020\Tools
  • Azure DevOps Server 2019: %programfiles%\Azure DevOps Server 2019\Tools
  • TFS 2018: %programfiles%\Microsoft Team Foundation Server 2018\Tools
  • TFS 2017: %programfiles%\Microsoft Team Foundation Server 15.0\Tools
  • TFS 2015: %programfiles%\Microsoft Team Foundation Server 14.0\Tools
  • TFS 2013: %programfiles%\Microsoft Team Foundation Server 12.0\Tools
  • TFS 2012: %programfiles%\Microsoft Team Foundation Server 11.0\Tools
  • TFS 2010: %programfiles%\Microsoft Team Foundation Server 2010\Tools

Note

Even if you are logged on with administrative credentials, you must open an elevated Command Prompt to perform this function.

Permissions

/a+: Add permissions

Use /a+ to add permissions for a user or a group in a server-level, collection-level, or project-level group. To add users to groups from the web portal, see Set permissions at the project- or collection-level.

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

Prerequisites

To use the /a+ command, you must have the View collection-level information or the View instance-level information permission set to Allow, depending on whether you are using the /collection or /server parameter, respectively. If you are changing permissions for a project, you must also have the Edit project-level information permission for the project set to Allow. For more information, see Permission and groups reference.

Parameters

Argument Description
Namespace The namespace that contains the group to which you want to add permissions for a user or group. You can also use the tfssecurity /a command to view a list of namespaces at the server, collection, and project level.
Identity The identity of the user or the group. For more information about identity specifiers, see Identity specifiers later in this article.
  • ALLOW
    The group or user can perform the operation that the Action specifies.
  • DENY
    The group or user cannot perform the operation that the Action specifies.
/collection :CollectionURL Required if /server is not used. Specifies the URL of a project collection in the following format: http:// ServerName : Port / VirtualDirectoryName / CollectionName
/server :ServerURL Required if /collection is not used. Specifies the URL of an application-tier server in the following format: http:// ServerName : Port / VirtualDirectoryName

Remarks

Run this command on an application-tier server for Azure DevOps.

Access control entries are security mechanisms that determine which operations a user, group, service, or computer is authorized to perform.

Example: Display available namespaces

The following example displays what namespaces are available at the server-level for the application-tier server that is named ADatumCorporation.

Note

The examples are for illustration only and are fictitious. No real association is intended or inferred.

tfssecurity /a /server:ServerURL 

Sample output:

    TFSSecurity - Team Foundation Server Security Tool
    Copyright (c) Microsoft Corporation.  All rights reserved.

    The target Team Foundation Server is http://ADatumCorporation:8080/.

    The following security namespaces are available to have permissions set on them:

         Registry
         Identity
         Job
         Server
         CollectionManagement
         Warehouse
         Catalog
         EventSubscription
         Lab

    Done.

Example: Display available actions

The following example displays what actions are available for the server-level namespace at the collection level.

tfssecurity /a Server /collection:CollectionURL 

Sample output:

    TFSSecurity - Team Foundation Server Security Tool
    Copyright (c) Microsoft Corporation.  All rights reserved.

    The target Team Foundation Server is http://ADatumCorporation:8080/.

    The following actions are available in the security namespace Server:
        GenericRead
        GenericWrite
        Impersonate
        TriggerEvent

    Done.

Example: Assign an instance-level permission

The following example grants the server-level View instance-level information permission to the ADatumCorporation deployment for the Datum1 domain user John Peoples (Datum1\jpeoples).

tfssecurity /a+ Server FrameworkGlobalSecurity GenericRead n:Datum1\jpeoples ALLOW /server:http://ADatumCorporation:8080 

Sample output:

    TFSSecurity - Team Foundation Server Security Tool
    Copyright (c) Microsoft Corporation.  All rights reserved.

    The target Team Foundation Server is http://ADatumCorporation:8080/.
    Resolving identity "n:Datum1\jpeoples"...
      [U] Datum1\jpeoples (John Peoples)
    Adding the access control entry...
    Verifying...

    Effective ACL on object "FrameworkGlobalSecurity":
      [+] GenericRead                        [INSTANCE]\Team Foundation Valid Users
      [+] GenericRead                        [INSTANCE]\SharePoint Web Application Services
      [+] Impersonate                        [INSTANCE]\SharePoint Web Application Services
      [+] GenericRead                        [INSTANCE]\Team Foundation Service Accounts
      [+] GenericWrite                       [INSTANCE]\Team Foundation Service Accounts
      [+] Impersonate                        [INSTANCE]\Team Foundation Service Accounts
      [+] TriggerEvent                       [INSTANCE]\Team Foundation Service Accounts
      [+] GenericRead                        [INSTANCE]\Team Foundation Administrators
      [+] GenericWrite                       [INSTANCE]\Team Foundation Administrators
      [+] TriggerEvent                       [INSTANCE]\Team Foundation Administrators
      [+] GenericRead                        DATUM1\jpeoples

    Done.

Example: Assign a collection-level permission

The following example grants the collection-level View collection-level information permission to the Collection0 project collection for Datum1 domain user John Peoples (Datum1\jpeoples).

tfssecurity /a+ Server FrameworkGlobalSecurity GenericRead n:Datum1\jpeoples ALLOW /collection:http://ADatumCorporation:8080/Collection0

Sample output:

    TFSSecurity - Team Foundation Server Security Tool
    Copyright (c) Microsoft Corporation.  All rights reserved.
    The target Team Foundation Server is http://ADatumCorporation:8080/COLLECTION0.
    Resolving identity "n:Datum1\jpeoples"...
      [U] DATUM1\jpeoples (John Peoples)
    Adding the access control entry...
    Verifying...

    Effective ACL on object "FrameworkGlobalSecurity":
      [+] GenericRead                        [Collection0]\Project Collection ValidUsers
      [+] GenericRead                        [Collection0]\Project Collection Service Accounts
      [+] GenericWrite                       [Collection0]\Project Collection Service Accounts
      [+] Impersonate                        [Collection0]\Project Collection Service Accounts
      [+] TriggerEvent                       [Collection0]\Project Collection Service Accounts
      [+] GenericRead                        [Collection0]\Project Collection Administrators
      [+] GenericWrite                       [Collection0]\Project Collection Administrators
      [+] TriggerEvent                       [Collection0]\Project Collection Administrators
      [+] GenericRead                        [INSTANCE]\SharePoint Web Application Services
      [+] Impersonate                        [INSTANCE]\SharePoint Web Application Services
      [+] GenericRead                        [Collection0]\Project Collection Build Service Accounts
      [+] GenericRead                        DATUM1\jpeoples

    Done.

/a-: Remove a user or a group from membership in a group

Use the /a- command to remove a user or a group from membership in a server-level, collection-level, or project-level group. To remove users from groups from the web portal, see Remove user accounts.

tfssecurity /a- Namespace Token Action Identity (ALLOW | DENY) [/collection:CollectionURL] [/server:ServerURI]

Prerequisites

To use the /a- command, you must have the View collection-level information or the View instance-level information permission set to Allow, depending on whether you are using the /collection or /server parameter, respectively. If you are changing permissions for a project, you must also have the Edit project-level information permission for the project set to Allow.

Parameters

Argument Description
Namespace The namespace that contains the group to which you want to remove permissions for a user or group. You can also use the tfssecurity /a command to view a list of namespaces at the server, collection, and project level.
Identity The identity of the user or the group. For more information about identity specifiers, see Identity specifiers later in this article.
  • ALLOW
    The group or user can perform the operation that the Action specifies.
  • DENY
    The group or user cannot perform the operation that the Action specifies.
/collection :CollectionURL Required if /server is not used. Specifies the URL of a project collection in the following format: http:// ServerName : Port / VirtualDirectoryName / CollectionName
/server :ServerURL Required if /collection is not used. Specifies the URL of an application-tier server in the following format: http:// ServerName : Port / VirtualDirectoryName

Remarks

Run this command on an application-tier server for Azure DevOps.

Access control entries are security mechanisms that determine which operations a user, group, service, or computer is authorized to perform on a computer or server.

Example: Display server-level namespaces

The following example displays what namespaces are available at the server level for the application-tier server that is named ADatumCorporation.

Note

The examples are for illustration only and are fictitious. No real association is intended or inferred.

tfssecurity /a /server:ServerURL 

Sample output:

    TFSSecurity - Team Foundation Server Security Tool
    Copyright (c) Microsoft Corporation.  All rights reserved.

    The target Team Foundation Server is http://ADatumCorporation:8080/.

    The following security namespaces are available to have permissions set on them:

         Registry
         Identity
         Job
         Server
         CollectionManagement
         Warehouse
         Catalog
         EventSubscription
         Lab

    Done.

Example: Display collection-level available actions

The following example displays what actions are available for the server namespace at the collection level.

tfssecurity /a Server /collection:CollectionURL 

Sample output:

    TFSSecurity - Team Foundation Server Security Tool
    Copyright (c) Microsoft Corporation.  All rights reserved.

    The target Team Foundation Server is http://ADatumCorporation:8080/.

    The following actions are available in the security namespace Server:
        GenericRead
        GenericWrite
        Impersonate
        TriggerEvent

    Done.

Example: Remove an instance-level permission

The following example removes the server-level View instance-level information permission to the ADatumCorporation deployment for the Datum1 domain user John Peoples (Datum1\jpeoples).

tfssecurity /a- Server FrameworkGlobalSecurity GenericRead n:Datum1\jpeoples ALLOW /server:http://ADatumCorporation:8080 

Sample output:

    TFSSecurity - Team Foundation Server Security Tool
    Copyright (c) Microsoft Corporation.  All rights reserved.

    The target Team Foundation Server is http://ADatumCorporation:8080/.
    Resolving identity "n:Datum1\jpeoples"...
      [U] Datum1\jpeoples (John Peoples)
    Removing the access control entry...
    Verifying...

    Effective ACL on object "FrameworkGlobalSecurity":
      [+] GenericRead                        [INSTANCE]\Team Foundation Valid Users
      [+] GenericRead                        [INSTANCE]\SharePoint Web Application Services
      [+] Impersonate                        [INSTANCE]\SharePoint Web Application Services
      [+] GenericRead                        [INSTANCE]\Team Foundation Service Accounts
      [+] GenericWrite                       [INSTANCE]\Team Foundation Service Accounts
      [+] Impersonate                        [INSTANCE]\Team Foundation Service Accounts
      [+] TriggerEvent                       [INSTANCE]\Team Foundation Service Accounts
      [+] GenericRead                        [INSTANCE]\Team Foundation Administrators
      [+] GenericWrite                       [INSTANCE]\Team Foundation Administrators
      [+] TriggerEvent                       [INSTANCE]\Team Foundation Administrators

    Done.

Example: Remove a collection-level permission

The following example removes the collection-level View collection-level information permission to the Collection0 project collection for Datum1 domain user John Peoples (Datum1\jpeoples).

tfssecurity /a+ Server FrameworkGlobalSecurity GenericRead n:Datum1\jpeoples ALLOW /collection:http://ADatumCorporation:8080/Collection0

Sample output:

    TFSSecurity - Team Foundation Server Security Tool
    Copyright (c) Microsoft Corporation.  All rights reserved.
    The target Team Foundation Server is http://ADatumCorporation:8080/COLLECTION0.
    Resolving identity "n:Datum1\jpeoples"...
      [U] DATUM1\jpeoples (John Peoples)
    Removing the access control entry...
    Verifying...

    Effective ACL on object "FrameworkGlobalSecurity":
      [+] GenericRead                        [Collection0]\Project Collection ValidUsers
      [+] GenericRead                        [Collection0]\Project Collection Service Accounts
      [+] GenericWrite                       [Collection0]\Project Collection Service Accounts
      [+] Impersonate                        [Collection0]\Project Collection Service Accounts
      [+] TriggerEvent                       [Collection0]\Project Collection Service Accounts
      [+] GenericRead                        [Collection0]\Project Collection Administrators
      [+] GenericWrite                       [Collection0]\Project Collection Administrators
      [+] TriggerEvent                       [Collection0]\Project Collection Administrators
      [+] GenericRead                        [INSTANCE]\SharePoint Web Application Services
      [+] Impersonate                        [INSTANCE]\SharePoint Web Application Services
      [+] GenericRead                        [Collection0]\Project Collection Build Service Accounts

    Done.

/acl: Display the access control list

Use /acl to display the access control list that applies to a particular object.

tfssecurity /acl Namespace Token [/collection:CollectionURL] [/server:ServerURL]

Prerequisites

To use the /acl command, you must have the View collection-level information or the View instance-level information permission set to Allow, depending on whether you are using the /collection or /server parameter, respectively. For more information, see Permission reference for Azure DevOps Server.

Parameters

Argument Description
Namespace The namespace that contains the group to which you want to view permissions for a user or group.
/collection :CollectionURL Required if /server is not used. Specifies the URL of a project collection in the following format: http:// ServerName : Port / VirtualDirectoryName / CollectionName
/server :ServerURL Required if /collection is not used. Specifies the URL of an application-tier server in the following format: http:// ServerName : Port / VirtualDirectoryName

Remarks

Run this command on an application-tier server for Azure DevOps.

Access control entries are security mechanisms that determine which operations a user, group, service, or computer is authorized to perform on a computer or server.

Example: List ACL assignments to a sever-level namespace

The following example displays what users and groups have access to the FrameworkGlobalSecurity token in the server namespace within the ADatumCorporation deployment.

Note

The examples are for illustration only and are fictitious. No real association is intended or inferred.

tfssecurity /acl Server FrameworkGlobalSecurity /server:ServerURL 

Sample output:

	TFSSecurity - Team Foundation Server Security Tool
	Copyright (c) Microsoft Corporation.  All rights reserved.
	The target Team Foundation Server is http://ADatumCorporation:8080/.
	Retrieving the access control list for object "Server"...

	Effective ACL on object "FrameworkGlobalSecurity":
	  [+] GenericRead                        [INSTANCE]\Team Foundation Valid Users
	  [+] GenericRead                        [INSTANCE]\SharePoint Web Application Services
	  [+] Impersonate                        [INSTANCE]\SharePoint Web Application Services
	  [+] GenericRead                        [INSTANCE]\Team Foundation Service Accounts
	  [+] GenericWrite                       [INSTANCE]\Team Foundation Service Accounts
	  [+] Impersonate                        [INSTANCE]\Team Foundation Service Accounts
	  [+] TriggerEvent                       [INSTANCE]\Team Foundation Service Accounts
	  [+] GenericRead                        [INSTANCE]\Team Foundation Administrators
	  [+] GenericWrite                       [INSTANCE]\Team Foundation Administrators
	  [+] TriggerEvent                       [INSTANCE]\Team Foundation Administrators
	  [+] GenericRead                        DATUM1\jpeoples

	Done.

Groups

/g: List the groups

Use /g to list the groups in a project, in a project collection, or across Azure DevOps Server.

tfssecurity /g [scope] [/collection:CollectionURL] [/server:ServerURL]

Prerequisites

To use the /g command, you must have the View collection-level information or the View instance-level information permission set to Allow, depending on whether you are using the /collection or /server parameter, respectively. To use the /g command within the scope of a single project, you must have the View project-level information permission set to Allow. For more information, see Permission and groups reference.

Parameters

Argument Description
scope Optional. Specifies the URI of the project for which you want to display groups. To obtain the URI for a project, open Team Explorer, right-click the project, click Properties, and copy the entire entry for URL.
/collection :CollectionURL Required if /server is not used. Specifies the URL of a project collection in the following format: http:// ServerName : Port / VirtualDirectoryName / CollectionName
/server :ServerURL Required if /collection is not used. Specifies the URL of an application-tier server in the following format: http:// ServerName : Port / VirtualDirectoryName

Remarks

Run this command on an application-tier server for Azure DevOps.

The /g command of the TFSSecurity command-line utility displays information about every group within the selected scope. This scope can be the project collection (/server) or the application-tier server (/instance). If used with the scope of a project, it will display information only about the groups associated with that project.

Example: Display collection-level group information

The following example displays information for all the groups within a project collection.

tfssecurity /g /collection:CollectionURL

/g+: Add a user or another group to an existing group

Use /g+ to add a user or another group to an existing group.

tfssecurity /g+ groupIdentity memberIdentity [/collection:CollectionURL] [/server:ServerURL]

Prerequisites

To use the /g+ command, you must have the View collection-level information and Edit collection-level information or the View instance-level information and Edit instance-level information permissions set to Allow, depending on whether you are using the /collection or /server parameter, respectively. For more information, see Security groups and permission reference.

Parameters

Argument Description
groupIdentity Specifies the group identity. For more information on valid identity specifiers, see Identity specifiers later in this article.
memberIdentity Specifies the member identity. For more information on valid identity specifiers, see Identity specifiers later in this article.
/collection :CollectionURL Required if /server is not used. Specifies the URL of a project collection in the following format: http:// ServerName : Port / VirtualDirectoryName / CollectionName
/server :ServerURL Required if /collection is not used. Specifies the URL of an application-tier server in the following format: http:// ServerName : Port / VirtualDirectoryName

Remarks

Run this command on an application-tier server for Azure DevOps.

You can also add users and groups to an existing group using Team Explorer. For more information, see Set permissions at the project- or collection-level.

Example: Add a user to a server-level group

The following example adds the Datum1 domain user John Peoples (Datum1\jpeoples) to the Team Foundation Administrators group.

Note

The examples are for illustration only and are fictitious. No real association is intended or inferred.

tfssecurity /g+ "Team Foundation Administrators" n:Datum1\jpeoples /server:http://ADatumCorporation:8080

Sample output:

    TFSSecurity - Team Foundation Server Security Tool
    Copyright (c) Microsoft Corporation.  All rights reserved.

    The target Team Foundation Server is http://ADatumCorporation:8080/.
    Resolving identity "Team Foundation Administrators"...
    a [A] [INSTANCE]\Team Foundation Administrators
    Resolving identity "n:Datum1\jpeoples"...
      [U] DATUM1\jpeoples (John Peoples)
    Adding John Peoples to [INSTANCE]\Team Foundation Administrators...
    Verifying...

    SID: S-1-9-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-0-0-0-0-1

    DN:

    Identity type: Team Foundation Server application group
       Group type: AdministrativeApplicationGroup
    Project scope: Server scope
     Display name: [INSTANCE]\Team Foundation Administrators
      Description: Members of this group can perform all operations on the Team Foundation Application Instance.

    4 member(s):
      [U] Datum1\hholt (Holly Holt)
      [U] Datum1\jpeoples (John Peoples)
      [G] BUILTIN\Administrators (BUILTIN\Administrators)
    s [A] [INSTANCE]\Team Foundation Service Accounts

    Member of 2 group(s):
    a [A] [Collection0]\Project Collection Administrators
    e [A] [INSTANCE]\Team Foundation Valid Users

    Done.

/g-: Remove a user or group

Use /g- to remove a user or a user group from an existing group.

tfssecurity /g- groupIdentity memberIdentity [/collection:CollectionURL] [/server:ServerURL]

Prerequisites

To use the /g- command, you must have the View collection-level information and Edit collection-level information or the View instance-level information and Edit instance-level information permissions set to Allow, depending on whether you are using the /collection or /server parameter, respectively. For more information, see Security groups and permission reference.

Parameters

Argument Description
groupIdentity Specifies the group identity. For more information about valid identity specifiers, see Identity specifiers later in this article.
memberIdentity Specifies the member identity. For more information about valid identity specifiers, see Identity specifiers later in this article.
/collection :CollectionURL Required if /server is not used. Specifies the URL of a project collection in the following format: http:// ServerName : Port / VirtualDirectoryName / CollectionName
/server :ServerURL Required if /collection is not used. Specifies the URL of an application-tier server in the following format: http:// ServerName : Port / VirtualDirectoryName

Remarks

Run this command on an application-tier server for Azure DevOps.

You can also add users and groups to an existing group using Team Explorer. For more information, see Remove users from a project group or Set permissions at the project- or collection-level.

Example: Remove a user from a server-level group

The following example removes the Datum1 domain user John Peoples (Datum1\jpeoples) from the Team Foundation Administrators group.

Note

The examples are for illustration only and are fictitious. No real association is intended or inferred.

tfssecurity /g- "Team Foundation Administrators" n:Datum1\jpeoples /server:http://ADatumCorporation:8080

Sample output:

    TFSSecurity - Team Foundation Server Security Tool
    Copyright (c) Microsoft Corporation.  All rights reserved.

    The target Team Foundation Server is http://ADatumCorporation:8080/.
    Resolving identity "Team Foundation Administrators"...
    a [A] [INSTANCE]\Team Foundation Administrators
    Resolving identity "n:Datum1\jpeoples"...
      [U] DATUM1\jpeoples (John Peoples)
    Removing John Peoples from [INSTANCE]\Team Foundation Administrators...
    Verifying...

    SID: S-1-9-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-0-0-0-0-1

    DN:

    Identity type: Team Foundation Server application group
       Group type: AdministrativeApplicationGroup
    Project scope: Server scope
     Display name: [INSTANCE]\Team Foundation Administrators
      Description: Members of this group can perform all operations on the Team Foundation Application Instance.

    3 member(s):
      [U] Datum1\hholt (Holly Holt)
      [G] BUILTIN\Administrators (BUILTIN\Administrators)
    s [A] [INSTANCE]\Team Foundation Service Accounts

    Member of 2 group(s):
    a [A] [Collection0]\Project Collection Administrators
    e [A] [INSTANCE]\Team Foundation Valid Users

    Done.

/gc: Create a project-level group

Use /gc at a command prompt to create a project-level group. To create a project-level group from the user interface, see Manage users or groups.

tfssecurity /gc Scope GroupName [GroupDescription] [/collection:CollectionURL]

Prerequisites

To use the /gc command, you must have the Edit Project-Level Information permission for that project set to Allow. For more information, see Permission reference.

Parameters

Argument Description
Scope The URI of the project to which you want to add a project-level group. To obtain the URI for a project, connect to it, and open Team Explorer, hover over the name of the project in Home, and read the address. Alternatively, connect to the project in Web Access and copy the URL.
GroupName The name of the new group.
GroupDescription A description of the project group. Optional.
/collection :CollectionURL The URL of the project collection. Required. The group will be created within the project collection. The format for the URL is http:// ServerName : Port / VirtualDirectoryName / CollectionName

Remarks

Run this command on an application-tier server for Azure DevOps.

A project-level group is a security group for your project. You can use project groups to grant read, write, and administrative permissions that meet the security requirements of your organization.

Example: Add a security group to a project

The following example creates a group that is specific to the project that the URI "vstfs://Classification/TeamProject/00000000-0000-0000-0000-000000000000" specifies. The group is named "Test Group" and has the description "This group is for testing."

Note

The examples are for illustration only and are fictitious. No real association is intended or inferred.

You must replace the placeholder GUID with the URI of the project for which you want to create this group. To obtain the URI for a project, open Team Explorer, right-click the project, click Properties, and copy the entire value of the URL property.

After you run the command, you can verify the group in Team Explorer. Right-click the project that you used in the command, click Project Settings, and then click Group Memberships. In the Project Groups on TeamProjectName dialog box, the Groups list includes Test Group .

Note

You can use the /gc command to create groups but not to add any users to the groups or assign any permissions. To change the membership of the group, see /g+: Add a user or another group to an existing group and /g-: Remove a user or group. To change the permissions for the group, see /a+: Add permissions and /a-: Remove a user or a group from membership in a group.

tfssecurity /gc "vstfs:///Classification/TeamProject/00000000-0000-0000-0000-000000000000" "Test Group" "This group is for team members who test our code" /collection:CollectionURL

/gcg: Create a server or collection-level group

Use the /gcg command to create a server-level or collection-level group. To create a collection-level group from the web portal, see Set permissions at the project- or collection-level.

tfssecurity /gcg GroupName [GroupDescription] [/collection:CollectionURL] [/server:ServerURL]`

Prerequisites

To use the /gcg command, you must have the Edit project-level information permission for that project set to Allow. For more information, see Security groups and permission reference.

Parameters

Argument Description
GroupName The group name.
GroupDescription A description of the group. Optional.
/collection :CollectionURL Required if /server is not used. Specifies the URL of a project collection in the following format: http:// ServerName : Port / VirtualDirectoryName / CollectionName
/server :ServerURL Required if /collection is not used. Specifies the URL of an application-tier server in the following format: http:// ServerName : Port / VirtualDirectoryName

Remarks

Run this command on an application-tier server for Azure DevOps.

Server-level groups are created directly on the application tier and apply to all project collections. Collection-level are created at the project collection level. They apply to that collection and have implications for all projects within the collection. In contrast, project groups apply to a specific project within a collection but not any other projects in that collection. You can assign permissions to server-level groups so that members of those groups can perform tasks in Azure DevOps Server itself, such as creating project collections. You can assign permissions to collection-level groups so that members of those groups can perform tasks across a project collection, such as administering users.

Note

You can use the /gcg command to create groups, but you cannot use it to add any users to the groups or assign any permissions. For information about how to change the membership of a group, see /g+: Add a user or another group to an existing group and /g-: Remove a user or group. For information about how to change the permissions for the group, see /a+: Add permissions and /a-: Remove a user or a group from membership in a group.

Example: Add a collection-level security group

The following example creates a collection-level group that is named "Datum Testers" with the description "A. Datum Corporation Testers."

Note

The examples are for illustration only and are fictitious. No real association is intended or inferred.

tfssecurity /gcg "Datum Testers" "A. Datum Corporation Testers" /collection:CollectionURL

The following example creates a server-level group that is named "Datum Auditors" with the description "A. Datum Corporation Auditors."

tfssecurity /gcg "Datum Auditors" "A. Datum Corporation Auditors" /server:ServerURL

/gd: Delete a server or collection-level group

Use /gd to delete a server-level or collection-level group.

tfssecurity /gd groupIdentity [/collection:CollectionURL] [/server:ServerURL]

Prerequisites

To use the /gd command, you must have the View collection-level information and Edit collection-level information or the View instance-level information and Edit instance-level information permissions set to Allow, depending on whether you are using the /collection or /server parameter, respectively. For more information, see Security groups and permission reference.

Parameters

Argument Description
groupIdentity Specifies the group identity.
/collection :CollectionURL Required if /server is not used. Specifies the URL of a project collection in the following format: http:// ServerName : Port / VirtualDirectoryName / CollectionName
/server :ServerURL Required if /collection is not used. Specifies the URL of an application-tier server in the following format: http:// ServerName : Port / VirtualDirectoryName

Remarks

Run this command on an application-tier server for Azure DevOps. To modify permissions through the web portal, see Set permissions at the project- or collection-level.

Example: Delete a collection-level security group

The following example deletes a group from the project collection. The group is identified by "S-1-5-21-2127521184-1604012920-1887927527-588340", the security identifier (SID). For more information about finding the SID of a group, see /im: Display information about identities that compose direct membership. You can also use the friendly name to delete a group.

Note

The examples are for illustration only and are fictitious. No real association is intended or inferred.

tfssecurity /gd S-1-5-21-2127521184-1604012920-1887927527-588340 /collection:CollectionURL

/gud: Change the description for a server or collection-level group

Use /gud to change the description for a server-level or collection-level group.

tfssecurity /gud GroupIdentity GroupDescription [/collection:CollectionURL] [/server:ServerURL]

Prerequisites

To use the /gud command, you must have the Edit project-level information permission set to Allow. For more information, see Security groups and permission reference.

Parameters

Argument Description
GroupIdentity Specifies the group identity. For more information about valid identity specifiers, see Identity specifiers later in this article.
GroupDescription Specifies the new description for the group.
/collection :CollectionURL Required if /server is not used. Specifies the URL of a project collection in the following format: http:// ServerName : Port / VirtualDirectoryName / CollectionName
/server :ServerURL Required if /collection is not used. Specifies the URL of an application-tier server in the following format: http:// ServerName : Port / VirtualDirectoryName

Remarks

Run this command on an application-tier server for Azure DevOps.

Example: Add a description to a security group

The following example associates the description "The members of this group test the code for this project" with the group "Datum Testers."

Note

The examples are for illustration only and are fictitious. No real association is intended or inferred.

tfssecurity /gud "Datum Testers" "The members of this group test the code for this project" /collection:CollectionURL

/gun: Rename a group

Use /gun to rename a server-level or collection-level group.

tfssecurity /gun GroupIdentity GroupName [/collection:CollectionURL] [/server:ServerURL]

Prerequisites

To use the /gun command, you must have the View collection-level information and Edit collection-level information or the View instance-level information and Edit instance-level information permissions set to Allow, depending on whether you are using the /collection or /server parameter, respectively. For more information, see Security groups and permission reference.

Parameters

Argument Description
GroupIdentity Specifies the group identity. For more information about valid identity specifiers, see Identity specifiers later in this article.
GroupName Specifies the new name of the group.
/collection :CollectionURL Required if /server is not used. Specifies the URL of a project collection in the following format: http:// ServerName : Port / VirtualDirectoryName / CollectionName
/server :ServerURL Required if /collection is not used. Specifies the URL of an application-tier server in the following format: http:// ServerName : Port / VirtualDirectoryName

Remarks

Run this command on an application-tier server for Azure DevOps.

Example: Rename a security group

The following example renames the collection-level group "A. Datum Corporation Testers" to "A. Datum Corporation Test Engineers."

Note

The examples are for illustration only and are fictitious. No real association is intended or inferred.

tfssecurity /gun "A. Datum Corporation Testers" "A. Datum Corporation Test Engineers" /collection:CollectionURL

Identities and membership

/i: Display identity information for a specified group

Use /i to display identity information for a specified group in a deployment of Azure DevOps Server.

tfssecurity /i Identity [/collection:CollectionURL] [/server:ServerURL]

Prerequisites

To use the /i command, you must have the View collection-level information or the View instance -level information permission set to Allow, depending on whether you are using the /collection or /server parameter, respectively. For more information, see Security groups and permission reference.

Parameters

Argument Description
Identity The identity of the user or the application group. For more information about identity specifiers, see Identity specifiers later in this article.
/collection :CollectionURL Required if /server is not used. Specifies the URL of a project collection in the following format: http:// ServerName : Port / VirtualDirectoryName / CollectionName
/server :ServerURL Required if /collection is not used. Specifies the URL of an application-tier server in the following format: http:// ServerName : Port / VirtualDirectoryName

Remarks

Run this command on an application-tier server for Azure DevOps.

The /i command of the TFSSecurity command-line utility displays information about each group within the project collection (/server) or the application-tier server (/instance). It does not display any membership information.

Example: List identity information for a security group

The following example displays identity information for the "Team Foundation Administrators" group.

Note

The examples are for illustration only and are fictitious. No real association is intended or inferred.

tfssecurity /i "Team Foundation Administrators" /server:ServerURL 

Sample output:

    Resolving identity "Team Foundation Administrators"...

    SID: S-1-9-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-0-0-0-0-1

    DN:

    Identity type: Team Foundation Server application group
       Group type: AdministrativeApplicationGroup
    Project scope: Server scope
     Display name: Team Foundation Administrators
      Description: Members of this application group can perform all privileged operations on the server.

Example: Display identity information for a security group

The following example displays identity information for the Project Collection Administrators group using the adm: identity specifier.

tfssecurity /i adm: /collection:CollectionURL 

Sample output:

    Resolving identity "adm:"...

    SID: S-1-9-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-0-0-0-0-1

    DN:

    Identity type: Team Foundation Server application group
       Group type: AdministrativeApplicationGroup
    Project scope: Server scope
     Display name: [DatumOne]\Project Collection Administrators
      Description: Members of this application group can perform all privileged operations on the project collection.

The following example displays identity information for the Project Administrators group for the "Datum" project by using the adm: identity specifier.

tfssecurity /i adm:vstfs:///Classification/TeamProject/ProjectGUID /collection:CollectionURL 

Sample output:

    Resolving identity "adm:vstfs:///Classification/TeamProject/ProjectGUID"...

    SID: S-1-9-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-0-0-0-0-1

    DN:

    Identity type: Team Foundation Server application group
       Group type: AdministrativeApplicationGroup
    Project scope: Datum
     Display name: [Datum]\Project Administrators
      Description: Members of this application group can perform all operations in the project.

/im: Display information about identities that compose direct membership

Use /im to display information about the identities that compose the direct membership of a group that you specify.

tfssecurity /im Identity [/collection:CollectionURL] [/server:ServerURL]

Prerequisites

To use the /im command, you must have the View collection-level information or the View instance-level information permission set to Allow, depending on whether you are using the /collection or /server parameter, respectively. For more information, see Security groups and permission reference.

Parameters

Argument Description
Identity The identity of the user or the group. For more information about identity specifiers, see Identity specifiers later in this article.
/collection :CollectionURL Required if /server is not used. Specifies the URL of a project collection in the following format: http:// ServerName : Port / VirtualDirectoryName / CollectionName
/server :ServerURL Required if /collection is not used. Specifies the URL of an application-tier server in the following format: http:// ServerName : Port / VirtualDirectoryName

Remarks

Run this command on an application-tier server for Azure DevOps.

The /im command of TFSSecurity displays the direct members of the specified group only. This list includes other groups that are members of the specified group. However, the actual members of the member groups are not listed.

Example: Display membership identities for a security group

The following example displays direct membership identity information for the "Team Foundation Administrators" group in the domain "Datum1" at the fictitious company "A. Datum Corporation".

Note

The examples are for illustration only and are fictitious. No real association is intended or inferred.

tfssecurity /im "Team Foundation Administrators" /server:ServerURL

Sample output:

    Resolving identity "Team Foundation Administrators"...

    SID: S-1-9-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-0-0-0-0-1

    DN:

    Identity type: Team Foundation Server application group
    Group type: AdministrativeApplicationGroup
    Project scope: Server scope
    Display name: Team Foundation Administrators
    Description: Members of this application group can perform all privileged operations on the server.

    3 member(s):
      [U] Datum1\hholt (Holt, Holly)
      [G] BUILTIN\Administrators (BUILTIN\Administrators)
    s [A] [InstanceName]\Team Foundation Service Accounts

    Member of 2 group(s):
    a [A] [DatumOne]\Project Collection Administrators ([DatumOne]\Project Collection Administrators)
    e [A] [InstanceName]\Team Foundation Valid Users

    Done.

Example: Display identity information for a security group

The following example displays identity information for the Project Collection Administrators group in the "DatumOne" project collection in the domain "Datum1" at the fictitious company "A. Datum Corporation" by using the adm: identity specifier.

tfssecurity /im adm: /collection:CollectionURL 

Sample output:

    Resolving identity "adm: "...

    SID: S-1-9-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-0-0-0-0-1

    DN:

    Identity type: Team Foundation Server application group
    Group type: AdministrativeApplicationGroup
    Project scope: Server scope
    Display name: [DatumOne]\Project Collection Administrators
    Description: Members of this application group can perform all privileged operations on the project collection.

    5 member(s):
      [U] Datum1\jpeoples (Peoples, John)
      [U] Datum1\hholt (Holt, Holly)
      [G] BUILTIN\Administrators (BUILTIN\Administrators)
    a [A] [InstanceName]\Team Foundation Administrators
    s [A] [DatumOne]\Project Collection Service Accounts ([DatumOne]\Project Collection Service Accounts)

    Member of 1 group(s):
    e [A] [DatumOne]\Project Collection Valid Users ([DatumOne]\Project Colleciton Valid Users)

    Done.

Example: Display identity information for a security group using an identity specifier

The following example displays identity information for the Project Administrators group for the "Datum" project in the "DatumOne" project collection in the domain "Datum1" at the fictitious company "A. Datum Corporation" using the adm: identity specifier.

tfssecurity /im adm:vstfs:///Classification/TeamProject/ProjectGUID /collection:CollectionURL 

Sample output:

    Resolving identity "adm:vstfs:///Classification/TeamProject/ProjectGUID"...

    SID: S-1-9-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-XXXXXXX

    DN:

    Identity type: Team Foundation Server application group
    Group type: AdministrativeApplicationGroup
    Project scope: Datum
    Display name: [Datum]\Project Administrators
    Description: Members of this application group can perform all operations in the project.

    2 member(s):
      [U] Datum1\jpeoples (Peoples, John)
      [U] Datum1\hholt (Holt, Holly)

    Member of 1 group(s):
    e [A] [DatumOne]\Project Collection Valid Users ([DatumOne]\Project Collection Valid Users)

    Done.

/imx: Display information about the identities that the expanded membership

Use /imx to display information about the identities that compose the expanded membership of a specified group.

tfssecurity /imx Identity [/collection:CollectionURL] [/server:ServerURL]

Prerequisites

To use the /imx command, you must have the View collection-level information or the View instance-level information permission set to Allow, depending on whether you are using the /collection or /server parameter, respectively. For more information, see Security groups and permission reference.

Parameters

Argument Description
Identity The identity of the user or the group. For more information about identity specifiers, see Identity specifiers later in this article.
/collection :CollectionURL Required if /server is not used. Specifies the URL of a project collection in the following format: http:// ServerName : Port / VirtualDirectoryName / CollectionName
/server :ServerURL Required if /collection is not used. Specifies the URL of an application-tier server in the following format: http:// ServerName : Port / VirtualDirectoryName

Remarks

Run this command on an application-tier server for Azure DevOps.

The /imx command of TFSSecurity displays the expanded members of the specified group only. This list includes not only other groups that are members of the specified group but also the members of the member groups.

Example: Display expanded membership information for a security group

The following example displays expanded membership identity information for the "Team Foundation Administrators" group in the domain "Datum1" at the fictitious company "A. Datum Corporation".

Note

The examples are for illustration only and are fictitious. No real association is intended or inferred.

tfssecurity /imx "Team Foundation Administrators" /server:ServerURL

Sample output:

    Resolving identity "Team Foundation Administrators"...

    SID: S-1-9-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-0-0-0-0-1

    DN:

    Identity type: Team Foundation Server application group
    Group type: AdministrativeApplicationGroup
    Project scope: Server scope
    Display name: Team Foundation Administrators
    Description: Members of this application group can perform all privileged operations on the server.

    10 member(s):
      [U] Datum1\hholt (Holly Holt)
      [U] Datum1\jpeoples (John Peoples)
      [U] Datum1\tommyh (Tommy Hartono)
      [U] Datum1\henriea (Henriette Andersen)
      [U] Datum1\djayne (Darcy Jayne)
      [U] Datum1\aprilr (April Reagan)
      [G] Datum1\InfoSec Secure Environment
      [U] Datum1\nbento (Nuno Bento)
      [U] Datum1\cristp (Cristian Petculescu)
      [G] BUILTIN\Administrators (BUILTIN\Administrators)
    s [A] [InstanceName]\Team Foundation Service Accounts

    Member of 3 group(s):
    a [A] [DatumOne]\Project Collection Administrators ([DatumOne]\Project Collection Administrators)
    e [A] [DatumOne]\Project Collection Valid Users ([DatumOne]\Project Collection Valid Users)
    e [A] [InstanceName]\Team Foundation Valid Users

    Done.

The following example displays identity information for the Project Collection Administrators group in the "DatumOne" project collection in the domain "Datum1" at the fictitious company "A. Datum Corporation" using the adm: identity specifier.

tfssecurity /imx adm: /collection:CollectionURL 

Sample output:

    Resolving identity "adm: "...

    SID: S-1-9-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-0-0-0-0-1

    DN:

    Identity type: Team Foundation Server application group
    Group type: AdministrativeApplicationGroup
    Project scope: Server scope
    Display name: [DatumOne]\Project Collection Administrators
    Description: Members of this application group can perform all privileged operations on the project collection.

    6 member(s):
      [U] Datum1\jpeoples (Peoples, John)
      [U] Datum1\hholt (Holt, Holly)
      [G] BUILTIN\Administrators (BUILTIN\Administrators)
    a [A] [InstanceName]\Team Foundation Administrators
    s [A] [InstanceName]\Team Foundation Service Accounts
    s [A] [DatumOne]\Project Collection Service Accounts ([DatumOne]\Project Collection Service Accounts)

    Member of 1 group(s):
    e [A] [DatumOne]\Project Collection Valid Users ([DatumOne]\Project Collection Valid Users)

    Done.

Example: Display identity information for a security group using an identity specifier

The following example displays identity information for the Project Administrators group for the "Datum" project in the "DatumOne" project collection in the domain "Datum1" at the fictitious company "A. Datum Corporation" using the adm: identity specifier.

tfssecurity /imx adm:vstfs:///Classification/TeamProject/ProjectGUID /collection:CollectionURL 

Sample output:

    Resolving identity "adm:vstfs:///Classification/TeamProject/ProjectGUID"...

    SID: S-1-9-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-XXXXXXX

    DN:

    Identity type: Team Foundation Server application group
    Group type: AdministrativeApplicationGroup
    Project scope: Datum
    Display name: [Datum]\Project Administrators
    Description: Members of this application group can perform all operations in the project.

    2 member(s):
      [U] Datum1\jpeoples (Peoples, John)
      [U] Datum1\hholt (Holt, Holly)

    Member of 2 group(s):
    e [A] [DatumOne]\Project Collection Valid Users ([DatumOne]\Project Collection Valid Users)
    e [A] [InstanceName]\Team Foundation Valid Users

    Done.

For more information about the output specifiers, such as [G] and [U], see Identity specifiers later in this article.

/m: Check explicit and implicit group membership

Use /m to check explicit and implicit group membership information for a specified group or user.

tfssecurity /m GroupIdentity [MemberIdentity] [/collection:CollectionURL] [/server:ServerURL]

Prerequisites

To use the /m command, you must be a member of the Team Foundation Administrators security group. For more information, see Security groups and permission reference.

Note

Even if you are logged on with administrative credentials, you must open an elevated Command Prompt to perform this function.

Parameters

Argument Description
GroupIdentity Specifies the group identity. For more information on valid identity specifiers, see Identity specifiers later in this article.
MemberIdentity Specifies the member identity. By default, the value of this argument is the identity of the user who is running the command. For more information on valid identity specifiers, see Identity specifiers later in this article.
/collection :CollectionURL Required if /server is not used. Specifies the URL of a project collection in the following format: http:// ServerName : Port / VirtualDirectoryName / CollectionName
/server :ServerURL Required if /collection is not used. Specifies the URL of an application-tier server in the following format: http:// ServerName : Port / VirtualDirectoryName

Remarks

Run this command on the local application-tier computer.

The /m command of the TFSSecurity command-line utility checks both direct and extended memberships.

Example: Verify membership of a user in a security group

The following example verifies whether the user "Datum1\jpeoples" belongs to the Team Foundation Administrators server-level group.

Note

The examples are for illustration only and are fictitious. No real association is intended or inferred.

tfssecurity /m "Team Foundation Administrators" n:Datum1\jpeoples /server:http://ADatumCorporation:8080

Sample output:

    TFSSecurity - Team Foundation Server Security Tool
    Copyright (c) Microsoft Corporation.  All rights reserved.

    The target Team Foundation Server is http://ADatumCorporation:8080/.
    Resolving identity "Team Foundation Administrators"...
    a [A] [INSTANCE]\Team Foundation Administrators
    Resolving identity "n:Datum1\jpeoples"...
      [U] DATUM1\jpeoples (John Peoples)
    Checking group membership...

    John Peoples IS a member of [INSTANCE]\Team Foundation Administrators.

    Done.

Security namespaces

Note

Namespaces and tokens are valid for all versions of Azure DevOps. Namespaces are subject to change over time. To get the latest list of namespaces, exercise one of the command line tools or REST API. Some namespaces have been deprecated. For more information, see Security namespace and permission reference.

Identity specifiers

You can reference an identity by using one of the notations in the following table.

Identity specifier Description Example
sid: Sid. References the identity that has the specified security identifier (SID). sid:S-1-5-21-2127521184-1604012920-1887927527-588340
n:[D omain]Name References the identity that has the specified name. For Windows, Name is the account name. If the referenced identity is in a domain, the domain name is required. For application groups, Name is the group display name, and Domain is the URI or GUID of the containing project. In this context, if Domain is omitted, the scope is assumed to be at the collection level. To reference the identity of the user "John Peoples" in the domain "Datum1" at the fictitious company "A. Datum Corporation:"

n:DATUM1\jpeoples

To reference application groups:

n:"Full-time Employees"

n:00a10d23-7d45-4439-981b-d3b3e0b0b1ee\Vendors
adm:[Scope] References the administrative application group for the scope, such as "Team Foundation Administrators" for the server level or "Project Collection Administrators" at the collection level. The optional parameter Scope is a project URI or URL, including its GUID and connection string. If scope is omitted, the server or collection scope is assumed based on whether the /instance or /server parameter is used. In either case, the colon is still required. adm:vstfs:///Classification/TeamProject/ GUID
srv: References the application group for service accounts. Not applicable
all: References all groups and identities. Not applicable
String References an unqualified string. If String starts with S-1-, it is identified as a SID. If String starts with CN= or LDAP:// it is identified as a distinguished name. Otherwise, String is identified as a name. "Team testers"

Type markers

The following markers are used to identify types of identities and ACEs in output messages.

Identity type markers

Identity type marker Description
U Windows user.
G Windows group.
A Azure DevOps Server application group.
a [ A ] Administrative application group.
s [ A ] Service account application group.
X Identity is not valid.
? Identity is unknown.

Access control entry markers

Access control entry marker Description
+ ALLOW access control entry.
- DENY access control entry.
* [] Inherited access control entry.