Programmatically connecting to Azure DevOps with a Service Principal (Management Group)

Continuing from my last post of programmatically connecting to Azure DevOps with a Service Principal at subscription level, I also wanted to show how you can create a DevOps service connection programmatically at a Management Group level.

Unlike the subscription level, you cannot just uses Az DevOps command with a management group parameter. This does not appear to be available, the answer is to pass in a json template.

You will need a few things already configured:

* See code in the powershell folder from the post on to see how you can create this programatically.

Management Groups Enabled

  • Click on Start using management groups. This will create your “Tenant Root Group” and apply your subscriptions to the management group.

The above will set you up to walk through this demo, however, please ensure you understand what Management groups are, and how to use.

‘User Access Administrator’ access.

On the above picture, you can see next to the words Tenant Root Group a link (details). You probably do not have the details link clickable at this time. This is because although you have been able to create the initial Tenant Root Group – Management Group, you need to promote your account access to it.

Note: You can only do this as a Global Administrator.


  • Go to your Azure Portal
  • Go to Azure Active Directory
  • In the left hand navigation under Manage, click Properties
  • Under Access management for Azure resources switch the button to Yes.

Now if you go back to the Tenant Root Group – Management Group, you will be able to click the details link and have access to the Management group, see deployments made at that level, modify access for others etc.

Switching the button to No will then remove your access.


Using Az Cli, log in with you account first az login. The below snippet, on line 2 shows how to give yourself access. Where line 5 & 6 would remove the account.

#Give access
az rest method post uri ''
#Remove access
$account =
az role assignment delete assignee $account role 'User Access Administrator' scope '/'

The Code

Running of this code, will create a DevOps project if it doesn’t exist, and then create a Management Group level Service Connection to the Tenant Root Management Group. To apply to a different level management group would require modification to the code to grab the name and ID of the management group you wish to use and pass into the JSON template.

Your account is now set up to run, you will need to first be logged into AZ Cli.

Note: This can be a Service Principal, as long as the account being used is able to list App Registrations, and has ‘User Access Administrator’ RBAC on the Tenant Root Group – Management Group.

You will need to create a ‘management-group.json’ file which is used as a template, and key tokens will be replaced within the script.

"administratorsGroup": null,
"authorization": {
"scheme": "ServicePrincipal",
"parameters": {
"serviceprincipalid": "##ServicePrincipalId##",
"authenticationType": "spnKey",
"serviceprincipalkey": "##ServicePrincipalKey##",
"tenantid": "##TenantId##"
"createdBy": null,
"data": {
"environment": "AzureCloud",
"scopeLevel": "ManagementGroup",
"managementGroupId": "##ManagementGroupId##",
"managementGroupName": "##ManagementGroupName##"
"description": "Management Group Service Connection",
"groupScopeId": null,
"name": "##Name##",
"operationStatus": null,
"readersGroup": null,
"serviceEndpointProjectReferences": [
"description": "Management Group Service Connection",
"name": "##Name##",
"projectReference": {
"id": "##ProjectId##",
"name": "##ProjectName##"
"type": "azurerm",
"url": "",
"isShared": false,
"owner": "library"

In the code below important parts to note:

(Line 32) – How the authentication works with DevOps. The Personal Access Token is added to the $Env: variable “AZURE_DEVOPS_EXT_PAT”

(Line 61 – 74) – Updating the json template, saving the file as a temp file, and then creating the Service Connection passing in the json template. The json template is the same template used by Azure DevOps when you set up the Management Group Service connection manually, you can see this by watching the network traffic.

Creates a service connection for a ManagementGroup
Please ensure you are already logged to azure using az login
# Azure DevOps Personal Access Token (PAT) for the '; Azure DevOps tenancy
# The Azure DevOps organisation to create the service connection in, available from System.TeamFoundationCollectionUri if running from pipeline.
$TeamFoundationCollectionUri = $($Env:System_TeamFoundationCollectionUri -replace '%20', ' '),
# The name of the project to which this build or release belongs, available from $(System.TeamProject) if running from pipeline
$TeamProject = $Env:System_TeamProject,
$ErrorActionPreference = 'Stop'
$InformationPreference = 'Continue'
#Clearing default.
az configure defaults group=
$account = az account show | ConvertFrom-Json
$Env:AZURE_DEVOPS_EXT_PAT = $PersonalAccessToken
Write-Information MessageData:"Adding Azure DevOps Extension…"
az extension add name azuredevops
Write-Information MessageData "Configure defaults Organization:$TeamFoundationCollectionUri"
az devops configure defaults organization="$TeamFoundationCollectionUri"
Write-Information MessageData "Getting App Registration: $AppRegistrationName"
$AppReg = az ad app list all query "[?displayName == '$AppRegistrationName']" | ConvertFrom-Json
Write-Information MessageData "Give App Registration access to Management Group Root…"
az role assignment create role "Owner" assignee $($AppReg.appId) scope "/"
Write-Information MessageData "Checking if $TeamProject project exists…"
$ProjectDetails = az devops project list query "value[?name == '$TeamProject']" | Select-Object First 1 | ConvertFrom-Json
if(-not $ProjectDetails){
Write-Information MessageData "Creating $TeamProject project…"
$ProjectDetails = az devops project create name $TeamProject
Write-Information MessageData "Checking if service endpoint already exists…"
$ServiceEndpoint = az devops serviceendpoint list project "$TeamProject" query "[?name == '$($AppReg.DisplayName)-Mg']" | Select-Object First 1 | ConvertFrom-Json
if (-not $ServiceEndpoint) {
Write-Information MessageData "Getting Json file for Management Group…"
$managementGroupJson = Get-Content Raw Path "$PSScriptRoot/management-group.json"
$configFilePath = "$PSScriptRoot/temp-managementGroup.json"
$managementGroupJson = $managementGroupJson -replace '##TenantId##', $($Account.homeTenantId) `
-replace '##ManagementGroupId##', $($Account.homeTenantId) `
-replace '##ManagementGroupName##', "Tenant Root Group" `
-replace '##ServicePrincipalId##', $($AppReg.appId) `
-replace '##ServicePrincipalKey##', $(ConvertFrom-SecureString SecureString:$AppPassword AsPlainText) `
-replace '##Name##', "$($AppReg.DisplayName)-Mg" `
-replace '##ProjectId##', $($ `
-replace '##ProjectName##', $($
Write-Information MessageData "Saving management json file…"
Set-Content Value:$managementGroupJson Path:$configFilePath
Write-Information MessageData "Creating Service Connection name:$($AppReg.DisplayName)-Mg for project $TeamProject"
$ServiceEndpoint = az devops serviceendpoint create project "$TeamProject" serviceendpointconfiguration "$configFilePath" | ConvertFrom-Json
Write-Information MessageData "Clean up temp files"
Remove-Item Path $configFilePath
Write-Information MessageData "Updating Service Connection to be enabled for all pipelines…"
az devops serviceendpoint update project "$TeamProject" id "$($" enable-forall true | Out-Null

To run the above code, you will need to put in your parameters. Replace with your values then run the below script, this will call the script above.

$PersonalAccessToken = "<PAT TOKEN>"
$TeamProject = '<PROJECT NAME>'
$TeamFoundationCollectionUri = '<organizationName >'
$AppRegistrationName = '<Service Principal Name>'
$AppPassword = '<Service Principal Secret>'
$AppSecurePassword = ConvertTo-SecureString String:$AppPassword AsPlainText Force
.\Install-ServiceConnectionManagementGroup.ps1 PersonalAccessToken $PersonalAccessToken `
TeamFoundationCollectionUri:$TeamFoundationCollectionUri `
TeamProject:$TeamProject `
AppRegistrationName:$AppRegistrationName `

My team project is called AutomateDevOpsMG, and I used an App Registration called DevOps.

Running Script

Service Principal with Owner access on Management Group Level

Project ‘AutomateDevOpsMG’ and Service connection ‘DevOps-Mg’