Manually set an Azure Resource Manager workload identity service connection

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.

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

Set a workload identity service connection

Managed identity

To manually set up managed identity authentication for your Azure 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:

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

You can also use the REST API for this process.

Prerequisites for managed identity authentication

• To create a user-assigned managed identity, your Azure account needs the Managed Identity Contributor or higher role assignment.
• To use a managed identity to access Azure resources in your pipeline, assign the managed identity access to the resource.

Create a managed identity in Azure portal

1. Sign in to the Azure portal.

2. In the search box, enter Managed Identities.

3. Select Create.

4. 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).

5. Select Review + create to create a new managed identity. When your deployment is complete, select Go to resource.

6. Copy the Subscription, Subscription ID, and Client ID values for your managed identity to use later.

7. Within your managed identity in Azure portal, go to Settings > Properties.

8. Copy the Tenant Id value to use later.

Create a service connection for managed identity authentication in Azure DevOps

1. In Azure DevOps, open your project and go to > Pipelines > Service connections.

2. Select New service connection.

3. Select Azure Resource Manager.

4. Select identity type App registration or Managed identity (manual) the Workload identity federation credential.

   

5. For Service connection name, enter a value such as uamanagedidentity. You'll use this value in your federated credential subject identifier.

6. Select Next.

7. In Step 2: App registration details:

   Step 2: App registration details contains the following parameters. You can enter or select the following parameters:

   Parameter	Description
   Issuer	Required. DevOps automatically creates the issuer URL.
   Subject identifier	Required. DevOps automatically creates the subject identifier.
   Environment	Required. Choose a cloud environment to connect to. If you select Azure Stack, enter the environment URL, which is something like https://management.local.azurestack.external.

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

      • For the Machine Learning Workspace scope, enter the following parameters:

        Parameter	Description
        Subscription Id	Required. Enter the Azure subscription ID.
        Subscription Name	Required. Enter the Azure subscription name.
        Resource Group	Required. Select the resource group containing the workspace.
        ML Workspace Name	Required. Enter the name of the existing Azure Machine Learning workspace.
        ML Workspace Location	Required. Enter the location of the existing Azure Machine Learning workspace.

   2. In the Authentication section, enter or select the following parameters:

      Parameter	Description
      Application (client) ID	Required. Enter the Client ID for your managed identity.
      Directory (tenant) ID	Required. Enter the Tenant ID from your managed identity.

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

8. In Azure DevOps, copy the generated values for Issuer and Subject identifier.

   

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

1. In a new browser window, within your managed identity in Azure portal, go to Settings > Federated credentials.

2. Select Add credentials.

3. Select the Other issuer scenario.

4. Paste the values for Issuer and Subject identifier that you copied from your Azure DevOps project into your federated credentials in the Azure portal.

   

5. Enter the Name of your federated credential.

6. Select Add.

Grant permissions to the managed identity in Azure portal

1. In Azure portal, go to the Azure resource that you want to grant permissions for (for example, a resource group).

2. Select Access control (IAM).

   

3. Select Add role assignment. Assign the required role to your managed identity (for example, Contributor).

4. Select Review and assign.

Save your Azure DevOps service connection

1. In Azure DevOps, return to your draft service connection.

2. Select Finish setup.

3. Select Verify and save. Once this step successfully completes, your managed identity is fully configured.

App registration

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:

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

You can also use the REST API for this process.

Prerequisites for app registration authentication

• To create a service connection, your Azure account needs to be able to create app registrations.
  • If creating app registrations is disabled in your tenant, then you need to have the Application Developer role to create application registrations.

Create an app registration and federated credentials in Azure portal

1. In the Azure portal, search for app registrations.

2. Select New registration.

   

3. For Name, enter a name for your app registration, and then select Who can use this application or access this API.

4. Select Register.

5. 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 app registration authentication in Azure DevOps

1. In Azure DevOps, open your project and go to > Pipelines > Service connections.

2. Select New service connection.

3. Select Azure Resource Manager.

4. Select identity type App registration or Managed identity (manual) the Workload identity federation credential.

   

5. For Service connection name, enter a value such as uaappregistration. You'll use this value in your federated credential subject identifier.

6. Select Next.

7. In Step 2: App registration details:

   Step 2: App registration details contains the following parameters. You can enter or select the following parameters:

   Parameter	Description
   Issuer	Required. DevOps automatically creates the issuer URL.
   Subject identifier	Required. DevOps automatically creates the subject identifier.
   Environment	Required. Choose a cloud environment to connect to. If you select Azure Stack, enter the environment URL, which is something like https://management.local.azurestack.external.

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

      • For the Machine Learning Workspace scope, enter the following parameters:

        Parameter	Description
        Subscription Id	Required. Enter the Azure subscription ID.
        Subscription Name	Required. Enter the Azure subscription name.
        Resource Group	Required. Select the resource group containing the workspace.
        ML Workspace Name	Required. Enter the name of the existing Azure Machine Learning workspace.
        ML Workspace Location	Required. Enter the location of the existing Azure Machine Learning workspace.

   2. In the Authentication section, enter or select the following parameters:

      Parameter	Description
      Application (client) ID	Required. Enter the Application (client) ID for your app registration.
      Directory (tenant) ID	Required. Enter the Directory (tenant) ID for your app registration.

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

8. In Azure DevOps, copy the generated values for Issuer and Subject identifier.

9. 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 to your app registration in Azure portal

1. In Azure portal, open your app registration and go to Manage > Certificates & secrets.

2. Select Federated credentials.

   

3. Select Add credentials.

4. Select the Other issuer scenario.

   

5. Paste the values for Issuer and Subject identifier that you copied from your Azure DevOps project into your federated credentials in the Azure portal.

   

6. Select Save.

Grant permissions to the app registration in Azure portal

1. In the Azure portal, go to the Azure resource that you want to grant permissions for (for example, a resource group).

2. Select Access control (IAM).

   

3. Select Add role assignment. Assign the required role to the app registration (for example, Contributor).

4. Select Review and assign.

Save your app registration Azure DevOps service connection

1. In Azure DevOps, return to your draft service connection.

2. Select Finish setup.

3. Select Verify and save. When this step successfully finishes, your Azure Resource Manager service connection is fully configured.