Events
Take the Microsoft Learn Challenge
Nov 19, 11 PM - Jan 10, 11 PM
Ignite Edition - Build skills in Microsoft Azure and earn a digital badge by January 10!
Register nowThis browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
Note
We are rolling out the new Azure service connection creation experience. Receiving it in your organization depends on various factors, and you may still see the older user experience.
An Azure Resource Manager service connection allows you to connect to Azure resources like Azure Key Vault from your pipeline. This connection lets you use a pipeline to deploy to Azure resources, such as an Azure App Service app, without needing to authenticate each time.
You have multiple authentication options for connecting to Azure with an Azure Resource Manager service connection. We recommend using workload identity federation with either an app registration or managed identity. Workload identity federation eliminates the need for secrets and secret management.
Recommended options:
Note
There are other Azure Resource Manager service connection authentication options that don't use workload identity federation. These options are available for backwards compatibility and edge cases and not recommended. If you're setting up a service connection for the first time, use workload identity federation. If you have an existing service connection, try converting your service connection to use workload identity federation first.
You can use this approach if all the following items are true for your scenario:
With this selection, Azure DevOps automatically queries for the subscription, management group, or Machine Learning workspace that you want to connect to and creates a workload identity federation for authentication.
In the Azure DevOps project, go to Project settings > Service connections.
For more information, see Open project settings.
Select New service connection, then select Azure Resource Manager and Next.
Select App registration (automatic) with the credential Workload identity federation.
Select a Scope level. Select Subscription, Management Group, or Machine Learning Workspace. Management groups are containers that help you manage access, policy, and compliance across multiple subscriptions. A Machine Learning Workspace is place to create machine learning artifacts.
For the Subscription scope, enter the following parameters:
Parameter | Description |
---|---|
Subscription | Required. Select the Azure subscription. |
Resource group | Optional. Select the Azure resource group. |
For the Management Group scope, select the Azure management group.
For the Machine Learning Workspace scope, enter the following parameters:
Parameter | Description |
---|---|
Subscription | Required. Select the Azure subscription. |
Resource Group | Required. Select the resource group containing the workspace. |
Machine Learning Workspace | Required. Select the Azure Machine Learning workspace. |
Enter a Service connection name.
Optionally, enter a description for the service connection.
Select Grant access permission to all pipelines to allow all pipelines to use this service connection. If you don't select this option, you must manually grant access to each pipeline that uses this service connection.
Select Save.
Use this option to automatically create a workload identity credential for an existing user-assigned managed identity. You need to have an existing user-assigned managed identity before you start.
In the Azure DevOps project, go to Project settings > Service connections.
For more information, see Open project settings.
Select New service connection, then select Azure Resource Manager and Next.
Select Managed identity.
In Step 1: Managed identity details:
In Step 2: Azure Scope:
Select the Scope Level. Select Subscription, Management Group, or Machine Learning Workspace. Management groups are containers that help you manage access, policy, and compliance across multiple subscriptions. A Machine Learning Workspace is place to create machine learning artifacts.
For the Subscription scope, enter the following parameters:
Parameter | Description |
---|---|
Subscription for service connection | Required. Select the Azure subscription name your managed identity will access. |
Resource group for service connection | Optional. Enter to limit managed identity access to one resource group. |
For the Management Group scope, enter the following parameters:
Parameter | Description |
---|---|
Management Group | Required. Select the Azure management group. |
For the Machine Learning Workspace scope, enter the following parameters:
Parameter | Description |
---|---|
Subscription | Required. Select the Azure subscription name. |
Resource group for service connection | Optional. Select the resource group containing the workspace. |
ML Workspace workspace | Required. Enter the name of the existing Azure Machine Learning workspace. |
In the Step 3: Service connection details: section, enter or select the following parameters:
Parameter | Description |
---|---|
Service Connection Name | Required. The name that you use to refer to this service connection in task properties. Not the name of your Azure subscription. |
Service Management Reference | Optional. Context information from an ITSM database. |
Description | Optional. Enter a description of the service connection. |
In the Security section, select Grant access permission to all pipelines to allow all pipelines to use this service connection. If you don't select this option, you must manually grant access to each pipeline that uses this service connection.
Select Save to validate and create the service connection.
You can quickly convert an existing Azure Resource Manager service connection to use workload identity federation for authentication instead of a secret. You can use the service connection conversion tool in Azure DevOps if your service connection meets these requirements:
To convert a service connection:
In the Azure DevOps project, go to Project settings > Service connections.
For more information, see Open project settings.
Select the service connection that you want to convert to use workload identity.
Select Convert.
If you have an existing credential with an expired secret, you see a different option to convert.
Select Convert again to confirm that you want to create a new service connection.
The conversion might take a few minutes. If you want to revert the connection, you must revert it within seven days.
Use a script to update multiple service connections at once to now use workload identity federation for authentication.
This example PowerShell script requires two parameters: Azure DevOps organization (example: https://dev.azure.com/fabrikam-tailspin
) and Azure DevOps project (example: Space game web agent
). The script then retrieves the associated service connections for your Azure DevOps project and organization.
When converting service connections to use workload identity federation, you're prompted to confirm the update for each connection not already using it. Upon confirmation, the script updates these service connections via the Azure DevOps REST API to utilize workload identity federation.
The script requires PowerShell 7.3 or newer and Azure CLI to run. Save the script to a .ps1
file and run it using PowerShell 7.
#!/usr/bin/env pwsh
<#
.SYNOPSIS
Convert multiple Azure Resource Manager service connection(s) to use Workload identity federation
.LINK
https://aka.ms/azdo-rm-workload-identity-conversion
.EXAMPLE
./convert_azurerm_service_connection_to_oidc_simple.ps1 -Project <project> -OrganizationUrl https://dev.azure.com/<organization>
#>
#Requires -Version 7.3
param (
[parameter(Mandatory=$true,HelpMessage="Name of the Azure DevOps Project")]
[string]
[ValidateNotNullOrEmpty()]
$Project,
[parameter(Mandatory=$true,HelpMessage="Url of the Azure DevOps Organization")]
[uri]
[ValidateNotNullOrEmpty()]
$OrganizationUrl
)
$apiVersion = "7.1"
$PSNativeCommandArgumentPassing = "Standard"
#-----------------------------------------------------------
# Log in to Azure
$azdoResource = "499b84ac-1321-427f-aa17-267ca6975798" # application id of Azure DevOps
az login --allow-no-subscriptions --scope ${azdoResource}/.default
$OrganizationUrl = $OrganizationUrl.ToString().Trim('/')
#-----------------------------------------------------------
# Retrieve the service connection
$getApiUrl = "${OrganizationUrl}/${Project}/_apis/serviceendpoint/endpoints?authSchemes=ServicePrincipal&type=azurerm&includeFailed=false&includeDetails=true&api-version=${apiVersion}"
az rest --resource $azdoResource -u "${getApiUrl} " -m GET --query "sort_by(value[?authorization.scheme=='ServicePrincipal' && data.creationMode=='Automatic' && !(isShared && serviceEndpointProjectReferences[0].projectReference.name!='${Project}')],&name)" -o json `
| Tee-Object -Variable rawResponse | ConvertFrom-Json | Tee-Object -Variable serviceEndpoints | Format-List | Out-String | Write-Debug
if (!$serviceEndpoints -or ($serviceEndpoints.count-eq 0)) {
Write-Warning "No convertible service connections found"
exit 1
}
foreach ($serviceEndpoint in $serviceEndpoints) {
# Prompt user to confirm conversion
$choices = @(
[System.Management.Automation.Host.ChoiceDescription]::new("&Convert", "Converting service connection '$($serviceEndpoint.name)'...")
[System.Management.Automation.Host.ChoiceDescription]::new("&Skip", "Skipping service connection '$($serviceEndpoint.name)'...")
[System.Management.Automation.Host.ChoiceDescription]::new("&Exit", "Exit script")
)
$prompt = $serviceEndpoint.isShared ? "Convert shared service connection '$($serviceEndpoint.name)'?" : "Convert service connection '$($serviceEndpoint.name)'?"
$decision = $Host.UI.PromptForChoice([string]::Empty, $prompt, $choices, $serviceEndpoint.isShared ? 1 : 0)
if ($decision -eq 0) {
Write-Host "$($choices[$decision].HelpMessage)"
} elseif ($decision -eq 1) {
Write-Host "$($PSStyle.Formatting.Warning)$($choices[$decision].HelpMessage)$($PSStyle.Reset)"
continue
} elseif ($decision -ge 2) {
Write-Host "$($PSStyle.Formatting.Warning)$($choices[$decision].HelpMessage)$($PSStyle.Reset)"
exit
}
# Prepare request body
$serviceEndpoint.authorization.scheme = "WorkloadIdentityFederation"
$serviceEndpoint.data.PSObject.Properties.Remove('revertSchemeDeadline')
$serviceEndpoint | ConvertTo-Json -Depth 4 | Write-Debug
$serviceEndpoint | ConvertTo-Json -Depth 4 -Compress | Set-Variable serviceEndpointRequest
$putApiUrl = "${OrganizationUrl}/${Project}/_apis/serviceendpoint/endpoints/$($serviceEndpoint.id)?operation=ConvertAuthenticationScheme&api-version=${apiVersion}"
# Convert service connection
az rest -u "${putApiUrl} " -m PUT -b $serviceEndpointRequest --headers content-type=application/json --resource $azdoResource -o json `
| ConvertFrom-Json | Set-Variable updatedServiceEndpoint
$updatedServiceEndpoint | ConvertTo-Json -Depth 4 | Write-Debug
if (!$updatedServiceEndpoint) {
Write-Debug "Empty response"
Write-Error "Failed to convert service connection '$($serviceEndpoint.name)'"
exit 1
}
Write-Host "Successfully converted service connection '$($serviceEndpoint.name)'"
}
You can revert a converted automatic service connection with its secret for seven days. After seven days, manually create a new secret.
If you manually create and convert your service connection, you can't revert the service connection by using the service connection conversion tool because Azure DevOps doesn't have permissions to modify its own credentials.
To revert a service connection:
In the Azure DevOps project, go to Pipelines > Service connections.
Select an existing service connection to revert.
Select Revert conversion to the original scheme.
Select Revert again to confirm your choice.
If you want to use a predefined set of access permissions and you don't already have a service principal defined for this purpose, follow one of these tutorials to create a new service principal:
To create a service connection that uses an existing service principal:
In the Azure DevOps project, go to Project settings > Service connections.
For more information, see Open project settings.
Select New service connection, then select Azure Resource Manager and Next.
Select Service principal (manual) and Next.
From the New Azure service connection dialog, select the Environment. If you select Azure Stack, enter the environment URL, which is something like https://management.local.azurestack.external
.
Select the Scope Level. Select Subscription or Management Group. Management groups are containers that help you manage access, policy, and compliance across multiple subscriptions.
For the Subscription scope, enter the following parameters:
Parameter | Description |
---|---|
Subscription Id | Required. Enter the Azure subscription ID. |
Subscription Name | Required. Enter the Azure subscription name. |
For the Management Group scope, enter the following parameters:
Parameter | Description |
---|---|
Management Group Id | Required. Enter the Azure management group ID. |
Management Group Name | Required. Enter the Azure management group name. |
In the Authentication section, enter or select the following parameters:
Parameter | Description |
---|---|
Service Principal Id | Required. Enter the service principal ID. |
Credential | Select Service Principal Key or Certificate. If you selected Service Principal Key, enter the key (password). If you selected Certificate, enter the certificate. |
Tenant Id | Required. Enter the tenant ID. |
Verify | Select to validate the settings you entered. |
In the Details section, enter the following parameters:
Parameter | Description |
---|---|
Connection Name | Required. The name that you use to refer to this service connection in task properties. Not the name of your Azure subscription. |
Description | Optional. Enter a description of the service connection. |
Security | Select Grant access permission to all pipelines to allow all pipelines to use this service connection. If you don't select this option, you must manually grant access to each pipeline that uses this service connection. |
Select Verify and save to validate and create the service connection.
In the Azure DevOps project, go to Project settings > Service connections.
For more information, see Open project settings.
Select New service connection, then select Azure Resource Manager.
On the Add an Azure Resource Manager service connection dialog, fill in the fields as follows:
Enter the Connection name.
Select the Environment. If you select Azure Stack, enter the environment URL, which is something like https://management.local.azurestack.external
.
Select the Scope level, **Subscription, or Management Group. Management groups are containers that help you manage access, policy, and compliance across multiple subscriptions.
For the Subscription scope, enter the following parameters:
Parameter | Description |
---|---|
Subscription Id | Required. Enter the Azure subscription ID. |
Subscription Name | Required. Enter the Azure subscription name. |
For the Management Group scope, enter the following parameters:
Parameter | Description |
---|---|
Management Group Id | Required. Enter the Azure management group ID. |
Management Group Name | Required. Enter the Azure management group name. |
Enter the Service principal Id.
Select the credential type:
Enter the Tenant Id.
Select Verify connection to validate the service connection.
Optionally, select Allow all pipelines to use this connection. If you don't select this option, you must manually grant access to each pipeline that uses this service connection.
Select Save to create the service connection.
After the new service connection is created:
azureSubscription
.If necessary, modify the service principal to expose the appropriate permissions.
For more information about authenticating by using a service principal, see Use role-based access control to manage access to your Azure subscription resources or the blog post Automate an Azure resource group deployment by using a service principal in Visual Studio.
For more information, see Troubleshoot Azure Resource Manager service connections.
Events
Take the Microsoft Learn Challenge
Nov 19, 11 PM - Jan 10, 11 PM
Ignite Edition - Build skills in Microsoft Azure and earn a digital badge by January 10!
Register nowTraining
Module
Authenticate your Azure deployment pipeline by using service principals - Training
Learn how to create, manage, and grant permissions to service principals, which enable your deployment pipelines to securely authenticate to Azure.
Certification
Microsoft Certified: Identity and Access Administrator Associate - Certifications
Demonstrate the features of Microsoft Entra ID to modernize identity solutions, implement hybrid solutions, and implement identity governance.