Manually set an Azure Resource Manager workload identity service connection

Article
08/30/2024

When you troubleshoot an Azure Resource Manager workload identity service connection, you might need to manually configure the connection instead of using the automated tool that's available in Azure DevOps.

We recommend that you try the automated approach before you begin a manual configuration.

There are two options for authentication: use a managed identity or use a service principal with an app registration. The advantage of the managed identity option is that you can use it if you don't have permissions to create service principals or if you're using a different Microsoft Entra tenant than your Azure DevOps user.

Managed identity
Service principal

Set a workload identity service connection to use managed identity authentication

To manually set up managed identity authentication for your Azure DevOps pipelines, follow these steps to create a managed identity in the Azure portal, establish a service connection in Azure DevOps, add federated credentials, and grant the necessary permissions. You'll need to follow these steps in this order:

Create the managed identity in Azure portal.
Create the service connection in Azure DevOps and save as a draft.
Add a federated credential to your managed identity in Azure portal.
Grant permissions to the managed identity in Azure portal.
Save your service connection in Azure DevOps.

You can also use the REST API for this process.

Create a managed identity in Azure portal

Sign in to the Azure portal.
In the search box, enter Managed Identities.
Select Create.
In the Create User Assigned Managed Identity pane, enter or select values for the following items:
- Subscription: Select the subscription in which to create the user-assigned managed identity.
- Resource group: Select a resource group to create the user-assigned managed identity in, or select Create new to create a new resource group.
- Region: Select a region to deploy the user-assigned managed identity (example: East US).
- Name: Enter the name for your user-assigned managed identity (example: UADEVOPS).
Select Review + create to create a new managed identity. When your deployment is complete, select Go to resource.
Copy the Subscription, Subscription ID, and Client ID values for your managed identity to use later.
Within your managed identity in Azure portal, go to Settings > Properties.
Copy the Tenant Id value to use later.

Create a service connection for managed identity authentication in Azure DevOps

In Azure DevOps, open your project and go to > Pipelines > Service connections.
Select New service connection.
Select Azure Resource Manager, and then select Next.
Select Workload Identity federation (manual), and then select Next.
For Service connection name, enter a value such as uamanagedidentity. You'll use this value in your federated credential subject identifier.
For Subscription ID and Subscription Name, enter the values for the subscription in your Azure portal account.
In the authentication section:
1. For Service Principal Id, enter the value of Client Id from your managed identity.
2. For Tenant ID, enter the value of Tenant Id from your managed identity.
In Azure DevOps, copy the generated values for Issuer and Subject identifier.
Select Keep as draft to save a draft credential. You can't complete setup until your managed identity has a federated credential in Azure portal.

Add a federated credential in Azure portal

In a new browser window, within your managed identity in Azure portal, go to Settings > Federated credentials.
Select Add credentials.
Select the Other issuer scenario.
Paste the values for Issuer and Subject identifier that you copied from your Azure DevOps project into your federated credentials in the Azure portal.
Enter the Name of your federated credential.
Select Add.

Grant permissions to the managed identity in Azure portal

In Azure portal, go to the Azure resource that you want to grant permissions for (for example, a resource group).
Select Access control (IAM).
Select Add role assignment. Assign the required role to your managed identity (for example, Contributor).
Select Review and assign.

Save your Azure DevOps service connection

In Azure DevOps, return to your draft service connection.
Select Finish setup.
Select Verify and save. Once this step successfully completes, your managed identity is fully configured.

Set a workload identity service connection to use service principal authentication

This section guides you through setting up an app registration and federated credentials in the Azure portal, creating a service connection for service principal authentication in Azure DevOps, adding federated credentials to your app registration, and granting the necessary permissions. The app registration uses service principal authentication. You'll need to complete these steps in the following order:

Create the app registration with service principal authentication in Azure portal.
Create the service connection in Azure DevOps and save as a draft.
Add a federated credential to your app registration in Azure portal.
Grant permissions to the app registration in Azure portal.
Save your service connection in Azure DevOps.

You can also use the REST API for this process.

Create an app registration and federated credentials in Azure portal

In the Azure portal, search for app registrations.
Select New registration.
For Name, enter a name for your app registration, and then select Who can use this application or access this API.
Select Register.
When your new app registration loads, copy the values for Application (client) ID and Directory (tenant) ID to use later.

Create a service connection for service principal authentication in Azure DevOps

Open a new browser window.
In Azure DevOps, open your project and go to > Pipelines > Service connections.
Select New service connection.
Select Azure Resource Manager, and then select Next.
Select Workload Identity federation (manual), and then select Next.
For Service connection name, enter a value such as uaappregistration. You'll use this value in your federated credential subject identifier.
For Subscription ID and Subscription Name, enter the values for the subscription in your Azure portal account.
In the authentication section:
1. For Service Principal Id, enter the value of Application (client) ID from your app registration.
2. For Tenant Id, enter the value of Directory (tenant) ID from your app registration.
Copy the generated values for Issuer and Subject identifier.
Select Keep as draft to save a draft credential. You can't complete setup until your app registration has a federated credential in Azure portal.

Add a federated credential to your app registration in Azure portal

In Azure portal, open your app registration and go to Manage > Certificates & secrets.
Select Federated credentials.
Select Add credentials.
Select the Other issuer scenario.
Paste the values for Issuer and Subject identifier that you copied from your Azure DevOps project into your federated credentials in the Azure portal.
Select Save.

Grant permissions to the app registration in Azure portal

In the Azure portal, go to the Azure resource that you want to grant permissions for (for example, a resource group).
Select Access control (IAM).
Select Add role assignment. Assign the required role to the app registration (for example, Contributor).
Select Review and assign.

Save your app registration Azure DevOps service connection

In Azure DevOps, return to your draft service connection.
Select Finish setup.
Select Verify and save. When this step successfully finishes, your Azure Resource Manager service connection is fully configured.

Share via