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.
|
| /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.
|
| /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. |