I've been looking for an way to automate branch security in order to enforce branch naming conventions and to control who can create release branches. Although the Azure DevOps documentation illustrates how to do this using the tfssecurity.exe command, the documentation also suggests that the tfssecurity.exe command is now deprecated.
This post will walk through how to apply branch security to your Azure DevOps repository using the Azure DevOps CLI.
Table of Contents The Azure DevOps Security API is quite interesting as security can be applied to various areas of the platform, including permissions for the project, build pipeline, service-connection, git repositories, etc. Each of these areas support the ability to assign permissions for groups or individuals to a security token. In some cases these tokens are hierarchical, so changes made at the root are inherited on children nodes. The areas that define the permissions are defined as Security Namespaces, and each token has a Security Access Control List that contains Access Control Entries.
We can obtain a complete list of security namespaces by querying https://dev.azure.com/<organization>/_apis/securitynamespaces, or by querying them using the az devops cli:
az devops security permission namespace list
Each security namespace contains a list of actions, which are defined as bit flags. The following shows the "Git Repositories" security namespace:
az devops security permission namespace list `
--query "[?contains(name,'Git Repositories')] | [0]"
{
"namespaceId": "2e9eb7ed-3c0a-47d4-87c1-0ffdd275fd87",
"name": "Git Repositories",
"displayName": "Git Repositories",
"separatorValue": "/",
"elementLength": -1,
"writePermission": 8192,
"readPermission": 2,
"dataspaceCategory": "Git",
"actions": [
{
"bit": 1,
"name": "Administer",
"displayName": "Administer",
"namespaceId": "2e9eb7ed-3c0a-47d4-87c1-0ffdd275fd87"
},
{
"bit": 2,
"name": "GenericRead",
"displayName": "Read",
"namespaceId": "2e9eb7ed-3c0a-47d4-87c1-0ffdd275fd87"
},
{
"bit": 4,
"name": "GenericContribute",
"displayName": "Contribute",
"namespaceId": "2e9eb7ed-3c0a-47d4-87c1-0ffdd275fd87"
},
{
"bit": 8,
"name": "ForcePush",
"displayName": "Force push (rewrite history, delete branches and tags)",
"namespaceId": "2e9eb7ed-3c0a-47d4-87c1-0ffdd275fd87"
},
{
"bit": 16,
"name": "CreateBranch",
"displayName": "Create branch",
"namespaceId": "2e9eb7ed-3c0a-47d4-87c1-0ffdd275fd87"
},
{
"bit": 32,
"name": "CreateTag",
"displayName": "Create tag",
"namespaceId": "2e9eb7ed-3c0a-47d4-87c1-0ffdd275fd87"
},
{
"bit": 64,
"name": "ManageNote",
"displayName": "Manage notes",
"namespaceId": "2e9eb7ed-3c0a-47d4-87c1-0ffdd275fd87"
},
{
"bit": 128,
"name": "PolicyExempt",
"displayName": "Bypass policies when pushing",
"namespaceId": "2e9eb7ed-3c0a-47d4-87c1-0ffdd275fd87"
},
{
"bit": 256,
"name": "CreateRepository",
"displayName": "Create repository",
"namespaceId": "2e9eb7ed-3c0a-47d4-87c1-0ffdd275fd87"
},
{
"bit": 512,
"name": "DeleteRepository",
"displayName": "Delete repository",
"namespaceId": "2e9eb7ed-3c0a-47d4-87c1-0ffdd275fd87"
},
{
"bit": 1024,
"name": "RenameRepository",
"displayName": "Rename repository",
"namespaceId": "2e9eb7ed-3c0a-47d4-87c1-0ffdd275fd87"
},
{
"bit": 2048,
"name": "EditPolicies",
"displayName": "Edit policies",
"namespaceId": "2e9eb7ed-3c0a-47d4-87c1-0ffdd275fd87"
},
{
"bit": 4096,
"name": "RemoveOthersLocks",
"displayName": "Remove others' locks",
"namespaceId": "2e9eb7ed-3c0a-47d4-87c1-0ffdd275fd87"
},
{
"bit": 8192,
"name": "ManagePermissions",
"displayName": "Manage permissions",
"namespaceId": "2e9eb7ed-3c0a-47d4-87c1-0ffdd275fd87"
},
{
"bit": 16384,
"name": "PullRequestContribute",
"displayName": "Contribute to pull requests",
"namespaceId": "2e9eb7ed-3c0a-47d4-87c1-0ffdd275fd87"
},
{
"bit": 32768,
"name": "PullRequestBypassPolicy",
"displayName": "Bypass policies when completing pull requests",
"namespaceId": "2e9eb7ed-3c0a-47d4-87c1-0ffdd275fd87"
}
],
"structureValue": 1,
"extensionType": "Microsoft.TeamFoundation.Git.Server.Plugins.GitSecurityNamespaceExtension",
"isRemotable": true,
"useTokenTranslator": true,
"systemBitMask": 0
}
The tokens within the Git Repositories Security Namespace follow the naming convention repoV2/<projectId>/<repositoryId>/<branch>. As this is a hierarchical security namespace, you can target very specific and granular permissions by adding parameters from left to right.
Examples:
- All repositories within the organization: repoV2/
- All repositories within a project: repoV2/<projectId>
- All branches within a repository: repoV2/<projectId>/<repositoryId>
- Specific branch: repoV2/<projectId>/<repositoryId>/<branch>
As the tokens are hierarchial, a really cool feature is that we can define patterns for branches that do not exist yet.
While the project and repository elements are relatively self-explanatory, the git branch convention is case sensitive and expressed in a hex format. Both Jesse Houwing and the Azure DevOps blog have some good write-ups on understanding this format.
The following PowerShell script can produce a security token for your project, repository or branch.
function Get-RepoSecurityToken( [string]$projectId, [string]$repositoryId, [string]$branchName) {
$builder = "repoV2/"
if ( ![string]::IsNullOrEmpty($projectId) ) {
$builder += $projectId
$builder += "/"
if ( ![string]::IsNullOrEmpty($repositoryId) ) {
$builder += $repositoryId
$builder += "/"
if ( ![string]::IsNullOrEmpty( $branchName) ) {
$builder += "refs/heads/"
# remove extra values if provided
if ( $branchName.StartsWith("/refs/heads/") ) {
$branchName = $branchName.Replace("/refs/heads/", "")
}
if ( $branchName.EndsWith("/")) {
$branchName = $branchName.TrimEnd("/")
}
$builder += (($branchName.Split('/')) | ForEach-Object { ConvertTo-HexFormat $_ }) -join '/'
}
}
}
return $builder
}
function ConvertTo-HexFormat([string]$branchName) {
return ($branchName | Format-Hex -Encoding Unicode | Select-Object -Expand Bytes | ForEach-Object { '{0:x2}' -f $_ }) -join ''
}
If you're working with query results and would like to see the actual name of the branches you've assigned, this function can reverse the hex format into a human readable string.
function ConvertFrom-GitSecurityToken([string]$token) {
$refHeads = "/refs/heads/"
$normalized = $token
if ($token.Contains($refHeads)) {
$indexOf = $token.IndexOf($refHeads) + $refHeads.Length
$firstHalf = $token.Substring(0, $indexOf)
$secondHalf = $token.Substring($indexOf)
$normalized = $firstHalf
$normalized += (($secondHalf.Split('/')) | ForEach-Object { ConvertFrom-HexFormat $_ }) -join '/'
}
return $normalized
}
function ConvertFrom-HexFormat([string]$hexString) {
$bytes = [byte[]]::new($hexString.Length/2)
for($i = 0; $i -lt $hexString.Length; $i += 2) {
$bytes[$i/2] = [convert]::ToByte($hexString.Substring($i,2), 16)
}
return [Text.Encoding]::Unicode.GetString($bytes)
}
Although it's incredibly easy to fetch security permissions for individual users, obtaining the permissions for user groups requires a special descriptor. To make them easier to work with, I'll grab all the security groups in the organization and map them into a simple lookup table:
function Get-SecurityDescriptors() {
$lookup = @{}
$decriptors = az devops security group list --scope organization --query "graphGroups[]" | ConvertFrom-Json
$descriptors | ForEach-Object { $lookup.Add( $_.principalName, $_.descriptor) }
return $descriptors
}
Given that we'll call the function several times, we'll wrap it in a method to make it easier to use.
$namespaceId = "2e9eb7ed-3c0a-47d4-87c1-0ffdd275fd87"
function Set-BranchSecurity( $descriptor, $token, $allow = 0 , $deny = 0) {
$result = az devops security permission update `
--id $namespaceId `
--subject $descriptor `
--token $token `
--allow-bit $allow `
--deny-bit $deny `
--only-show-errors | ConvertFrom-Json
}
This crude example shows how to apply the guidance laid out in the Require branches to be created in folders article, to a specific repository:
$project = "projectName"
$projectId = az devops project list --query "value[?name=='$project'].id | [0]" | ConvertFrom-Json
# grab the first repo in the project
$repoId = az repos list --project $project --query [0].id | ConvertFrom-Json
$groups = Get-SecurityDescriptors
$administrators = $groups[ "[$project]\\Project Administrators" ]
$contributors = $groups[ "[$project]\\Contributors" ]
# a simple array of tokens we can refer to
$tokens = @(
Get-RepoSecurityToken( $projectId, $repoId ), # repo - 0
Get-RepoSecurityToken( $projectId, $repoId, "main" ), # main - 1
Get-RepoSecurityToken( $projectId, $repoId, "releases"), # releases/* - 2
Get-RepoSecurityToken( $projectId, $repoId, "feature"), # feature/* - 3
Get-RepoSecurityToken( $projectId, $repoId, "users") # users/* - 4
)
$CreateBranch = 16
# prevent contributors from creating branches at the root of the repository
Set-BranchSecurity $contributors, $tokens[0], -deny $CreateBranch
# limit users to only create feature and user branches
Set-BranchSecurity $contributors, $tokens[3], -allow $CreateBranch
Set-BranchSecurity $contributors, $tokens[4], -allow $CreateBranch
# restrict who can create a release
Set-BranchSecurity $admins, $token[2], -allow $CreateBranch
# allow admins to recreate master/main
Set-BranchSecurity $admins, $token[1], -allow $CreateBranch
To improve upon this, you could describe each of these expressions as a ruleset in a JSON format and apply them to all the repositories in a project.
Some considerations:
- Granting Build Service accounts permissions to create Tags
- Empowering the Project Collection Administrators with the ability to override branch policy
- Empowering certain Teams or Groups with the ability to delete feature or user branches
Happy coding!
