Permissions and security

  • Article

TFS 2017 | TFS 2015 | TFS 2013

Note

Looking for REST APIS that support TFS 2018 or later versions? See the Azure DevOps REST API Reference.

api-version = 1.0

Evaluate permissions

Use this API to evaluate whether the calling identity has the requested permissions to a token or set of tokens. If the alwaysAllowAdministrators flag is set, then members of the Administrators group for the service host containing the namespace (i.e. 'Project Collection Administrators' or 'Organization Administrators') will always pass the security check.

Evaluate permissions on a single token

GET https://{instance}/_apis/permissions/{securitynamespace}/{permissions}/?api-version={version}&token={string}&alwaysAllowAdministrators={bool}
Parameter Type Default Notes
URL
instance string TFS server name ({server:port}).
securitynamespace guid ID of the security namespace.
permissions int The permission bits to demand.
Query
api-version string Version of the API to use.
token string The token on which to check permissions.
alwaysAllowAdministrators bool True if members of the Administrators group should always pass the security check.

AlwaysAllowAdministrators set to false

Sample request

GET https://mytfsserver/DefaultCollection/_apis/permissions/5a27515b-ccd7-42c9-84f1-54c998f03866/8/?token=token1&alwaysAllowAdministrators=False&api-version=1.0

AlwaysAllowAdministrators set to true

Sample request

GET https://mytfsserver/DefaultCollection/_apis/permissions/5a27515b-ccd7-42c9-84f1-54c998f03866/8/?token=token1&alwaysAllowAdministrators=True&api-version=1.0

Sample response

true

Evaluate permissions on a list of tokens

Permissions evaluation on a list of tokens does not aggregate the results, nor does it short-circuit if one of the evaluations yields a false result.

There are two versions of this API.

Plural version

This version of the API is just the plural version of permission check on a single token.

GET https://{instance}/_apis/permissions/{securitynamespace}/{permissions}/?api-version={version}&tokens={string}&alwaysAllowAdministrators={bool}&delimiter={char}
Parameter Type Default Notes
URL
instance string TFS server name ({server:port}).
securitynamespace guid ID of the security namespace.
permissions int The permission bits to demand.
Query
api-version string Version of the API to use. Works with Version 2.2 and above.
tokens string String containing a list of tokens (separated by the delimiter) on which to check permissions.
alwaysAllowAdministrators bool True if members of the Administrators group should always pass the security check.
delimiter char , The delimiter to use when encoding the list of tokens on the wire as a single string.

Sample request

GET https://mytfsserver/DefaultCollection/_apis/permissions/5a27515b-ccd7-42c9-84f1-54c998f03866/8/?api-version=2.2&tokens=token1,token2,token3&alwaysAllowAdministrators=False

Sample response

{
  "count": 3,
  "value": [
    false,
    false,
    true
  ]
}

Batch version

This version of the API performs a batch of "has permission" checks.

POST https://{instance}/_apis/security/permissionevaluationbatch/?api-version={version}
Parameter Type Default Notes
URL
instance string TFS server name ({server:port}).
Query
api-version string Version of the API to use. Works with Version 3.0 and above.
Body
alwaysAllowAdministrators bool True if members of the Administrators group should always pass the security check.
evaluations PermissionEvaluation[] Array of evaluation requests.

Each PermissionEvaluation contains:

Parameter Type Notes
securitynamespace guid Security namespace identifier for this permission evaluation.
token string Security namespace-specific token for this permission evaluation.
permissions int The permission bits to demand.
value bool [Out] The result of the security evaluation.

Sample request

POST https://mytfsserver/DefaultCollection/_apis/security/permissionevaluationbatch/?api-version=3.0-preview

{
  "alwaysallowadministrators": false,
  "evaluations": [
    {
      "securitynamespaceid": "5a27515b-ccd7-42c9-84f1-54c998f03866",
      "token": "token1",
      "permissions": 8
    },
    {
      "securitynamespaceid": "5a27515b-ccd7-42c9-84f1-54c998f03866",
      "token": "token2",
      "permissions": 8
    },
    {
      "securitynamespaceid": "5a27515b-ccd7-42c9-84f1-54c998f03866",
      "token": "token3",
      "permissions": 8
    }
  ]
}

Sample response

{
  "evaluations": [
    {
      "securityNamespaceId": "5a27515b-ccd7-42c9-84f1-54c998f03866",
      "token": "token1",
      "permissions": 8,
      "value": false
    },
    {
      "securityNamespaceId": "5a27515b-ccd7-42c9-84f1-54c998f03866",
      "token": "token2",
      "permissions": 8,
      "value": false
    },
    {
      "securityNamespaceId": "5a27515b-ccd7-42c9-84f1-54c998f03866",
      "token": "token3",
      "permissions": 8,
      "value": true
    }
  ]
}

Remove permissions

Removes the specified bits from the allow and deny values for the ACE with the given identity descriptor in the ACL for the given token. If no ACE for the given identity descriptor is found, no change is made.

DELETE https://{instance}/_apis/permissions/{securitynamespace}/{permissions}/?token={string}&descriptor={IdentityDescriptor}
Parameter Type Default Notes
URL
instance string TFS server name ({server:port}).
securitynamespace guid ID of the security namespace.
permissions int The permission bits to remove from the ACE's allow and deny bitmasks.
Query
token string The token whose ACL contains the ACE to be modified.
descriptor IdentityDescriptor The descriptor of the ACE to be modified.

Sample request

DELETE https://mytfsserver/DefaultCollection/_apis/permissions/5a27515b-ccd7-42c9-84f1-54c998f03866/4/?token=token1&descriptor=Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-1&api-version=1.0

Sample response

{
  "descriptor": "Microsoft.TeamFoundation.Identity;S-1-9-1551374245-1204400969-2402986413-2179408616-0-0-0-0-1",
  "allow": 1,
  "deny": 0
}