Azure DevOps : Creation of custom security groups using ADO Rest API

Depending on organizational structure and security requirements, there can be a need for custom security group(s) at the project level. For example, a project level group that has access only to repos. Now this can be a standard requirement as well, where all projects getting created in the org should have this custom security group created as part of it – this post will focus on explaining how custom security groups can be created using Azure DevOps rest apis.

If you are looking to create a custom security group in all your projects,(existing and the ones getting created) please take a look at this public git repository. This repository consists of an azure function, the way which we used to automate the creation of custom security group. The azure function which  runs daily to check for new projects and created the security group.

Pre-requisites:

1.       Collection admin privileges on Azure DevOps org.
2.       Knowledge on ADO Rest APIs and Access Control Entries.

Create the security group

         Create the security group using the ADO rest API.

For this we need:

Ø  the project id and

Ø  the scope descriptor.

To get the project id use the Projects – List API:

GET https://dev.azure.com/{organization}/_apis/projects?api-version=5.1

Example: GET https://dev.azure.com/arunvarriardevops/_apis/projects?api-version=5.1

Response:

Once you get the project id, use it to find the scope descriptor using Descriptors - Get:

GET https://vssps.dev.azure.com/{organization}/_apis/graph/descriptors/{storageKey}?api-version=5.1-preview.1

Example: From the above response my project id is 123456789. Use this as storage key:

GET https://vssps.dev.azure.com/arunvarriardevops/_apis/graph/descriptors/123456789?api-version=5.1-preview.1

Response:

Here storageKey refers to the project Id.

Once you get the descriptor create the security group in the project using Groups - Create, by providing the group name and group description in the request body.

POST https://vssps.dev.azure.com/{organization}/_apis/graph/groups?scopeDescriptor={scopeDescriptor}&groupDescriptors={groupDescriptors}&api-version=5.1-preview.1

Example: POST https://vssps.dev.azure.com/arunvarriardevops/_apis/graph/groups?scopeDescriptor=scp.ODcyMTc5ZGUtZDU3Yy00MmI1LWFjZmEtYzhmYjFjNDExZTdh&api-version=5.1-preview.1

Use the below json as body for post:

Response:

Here display name is the group name, I have given it as “MyGroup” - once you post this you will find a new group getting  created in this project.

The group being created will have the below permissions:

Make sure that view project-level information is enabled. Else you will have to follow the below same steps to enable the “view project-level information”. Here for me view project -level information is enabled. So below I am going to explain how you can enable the view for repos for this group.

Assign permissions to the newly created security group

Once you create the group you need to set the permissions for this group. For this we should get the list of Namespace IDs, with Security Namespaces – Query :

GET https://dev.azure.com/fabrikam/_apis/securitynamespaces?api-version=5.1

Example: GET https://dev.azure.com/arunvarriardevops/_apis/securitynamespaces?api-version=5.1

You will find around 50 plus namespaces with its key permission and bit value as shown below. For example, if you take repo level namespace, it may look like as shown below. Here the namespace id for repo level permissions is 2e9eb7ed-3c0a-47d4-87c1-0ffdd275fd87. In order to set the permissions for the group, we should identify:

• the correct namespace
• the actions to allow/deny

Now here we must understand that the permissions/ Access control entries in ADO are controlled by its bit value. For example at repo level if you want to give only Generic Read permission then the “allow” bit value for ACE should be 2 and if you want to give Both Generic read and contribute permission then we have to take sum of both the bits i.e. 2+4=6. In case you need to deny permissions, add up the “deny” bit values for the namespace. Once you get the required, set the group’s permissions using  Access Control Entries - Set Access Control Entries:

POST https://dev.azure.com/{organization}/_apis/accesscontrolentries/{securityNamespaceId}?api-version=5.1

Here one tricky thing could be that, we may have to decode the base descriptor using base64.We get the base descriptor in create group step.

Separate the descriptor from vssgp and decode it. Once decoded use this to append with descriptor using in namespace update/ACE update. Here Uy0xLTktMTU1MTM3NDI0NS0zNzMyNDgwMzkxLTIwOTQzODAzNTQtMjkwMjExNjYwMy00NzQwMjk2OTAtMS0zNzI1Njg1NDI4LTI5ODA4NTQ4NTgtMjE3MjE5MTIzNS0zMzMzODgxMDg4, can be decoded to S-1-9-1551374245-3732480391-2094380354-2902116603-474029690-1-3725685428-2980854858-2172191235-3333881088.

Important thing to note here is we need to validate that the descriptor length can be divided by 4.If its length is not divided by four then add “=” at the end of the descriptor until the length becomes divided by 4.

So, the whole body for POST request should look like below:

Now if you check the permissions at the repo level, you will be able to see that both GenericContribute and GenericRead add will be enabled for MyGroup, since allow bit is 6.

GenericContribute=4 + GenericRead=2 = 6

Once POST is successful navigate to ADO repository permissions to see the access to MyGroup:

Hope this helps!