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

Posted on by

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 https://cann0nf0dder.wordpress.com/2020/09/14/app-only-auth-connect-to-sharepoint-online-with-msal-and-azure-keyvault/ 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. https://docs.microsoft.com/en-us/azure/governance/management-groups/overview

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

Manually

  • Go to your Azure Portal https://portal.azure.com
  • 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.

Programatically

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 'https://management.azure.com/providers/Microsoft.Authorization/elevateAccess?api-version=2015-07-01'
#Remove access
$account = username@example.com
az role assignment delete —assignee $account —role 'User Access Administrator' —scope '/'
view raw set-AccessToRootManagementGroup.ps1 hosted with ❤ by GitHub

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": "https://management.azure.com/",
"isShared": false,
"owner": "library"
}
view raw management-group.json hosted with ❤ by GitHub

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.

<#
.SYNOPSIS
Creates a service connection for a ManagementGroup
Please ensure you are already logged to azure using az login
#>
param(
# Azure DevOps Personal Access Token (PAT) for the 'https://dev.azure.com/%5BORG%5D&#39; Azure DevOps tenancy
[Parameter(Mandatory)]
[string]
$PersonalAccessToken,
# The Azure DevOps organisation to create the service connection in, available from System.TeamFoundationCollectionUri if running from pipeline.
[string]
$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
[string]
$TeamProject = $Env:System_TeamProject,
[string]
$AppRegistrationName,
[securestring]
$AppPassword
)
$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 azure–devops
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 service–endpoint 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##', $($ProjectDetails.id) `
-replace '##ProjectName##', $($ProjectDetails.name)
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 service–endpoint create —project "$TeamProject" —service–endpoint–configuration "$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 service–endpoint update —project "$TeamProject" —id "$($ServiceEndpoint.id)" —enable-for–all true | Out-Null
view raw Install-ServiceConnectionManagementGroup.ps1 hosted with ❤ by GitHub

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 = 'https://dev.azure.com/<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 `
–AppPassword:$AppSecurePassword
view raw Run-InstallServiceConnectionManagementGroup.ps1 hosted with ❤ by GitHub

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’