Connect to Microsoft Azure with an ARM service connection

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019 | TFS 2018

You can use an Azure Resource Manager (ARM) service connection to connect to Azure resources with Service Principal Authentication (SPA) or an Azure-Managed Service Identity. With an Azure Resource Manager service connection, you can use a pipeline to deploy to Azure resources like an App Service app without needing to reauthenticate each time.

There are multiple options for connecting to Azure with Azure Resource Manager service connections:

• service principal or managed identity with workload identity federation

• service principal with secret
• agent-assigned managed identity

For other types of connection, and general information about creating and using connections, see Service connections for builds and releases.

Create an Azure Resource Manager service connection using workload identity federation

Important

Workload identity federation for Azure Resource Manager is currently in public preview. See the Supplemental Terms of Use for Microsoft Azure Previews for legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.

This feature is in public preview and may not be available in your organization. To request early access, go to https://aka.ms/azdo-rm-workload-identity-preview.

Workload identity federation uses OpenID Connect to authenticate with Microsoft Entra protected resources without needing to manage secrets.

We recommend this approach if:

• You have the Owner role for your Azure subscription.
• You're not connecting to Azure Stack or an Azure Government Cloud.
• You're not connecting from Azure DevOps Server 2019 or earlier versions of TFS.
• Any Marketplace extensions tasks used have been updated to support workload identity federation.

Create a new workload identity federation service connection

1. In Azure DevOps, open the Service connections page from the project settings page.

2. Choose + New service connection and select Azure Resource Manager.

   

3. Select Workload identity federation (automatic).

   

4. Specify the following parameters.

   Parameter	Description
   Subscription	Select an existing Azure subscription. If you don't see any Azure subscriptions or instances, see Troubleshoot Azure Resource Manager service connections.
   Resource Group	Leave empty to allow users to access all resources defined within the subscription, or select a resource group to which you want to restrict users' access (users will be able to access only the resources defined within that group).
   Service connection name	Required. The name you will use to refer to this service connection in task properties. This is not the name of your Azure subscription.

5. After the new service connection is created, copy the connection name into your code as the azureSubscription value.

6. To deploy to a specific Azure resource, the task will need additional data about that resource. Go to the resource in the Azure portal, and then copy the data into your code. For example, to deploy a web app, you would copy the name of the App Service into the WebAppName value.

Convert an existing ARM service connection to use workload identity federation

1. In Azure DevOps, open the Service connections page from the project settings page.

2. Go to Pipelines > Service connections and open an existing service connection.

3. Select the service connection you want to convert to use workload identity.

4. Select Convert.

   

5. Select Convert again to confirm that you want to create a new service connection. You will have seven days to revert the connection. The conversion may take a few minutes to process. Once the process completes, you'll be able to use the new service connection.

Revert an existing ARM service connection to use a service principal secret

You can revert a converted service connection with its secret for seven days. After seven days, you'll need to manually create a new secret.

To revert a connection:

1. In Azure DevOps, open the Service connections page from the project settings page.

2. Go to Pipelines > Service connections and open an existing service connection.

3. Select the service connection you want to revert.

4. Select Revert conversion to the original scheme.

   

5. Select Revert again to confirm your choice.

Create an Azure Resource Manager service connection using a service principal secret

We recommend this simple approach if:

• You're signed in as the owner of the Azure Pipelines organization and the Azure subscription.
• You don't need to further limit the permissions for Azure resources accessed through the service connection.
• You're not connecting to Azure Stack or an Azure Government Cloud.
• You're not connecting from Azure DevOps Server 2019 or earlier versions of TFS

1. In Azure DevOps, open the Service connections page from the project settings page. In TFS, open the Services page from the "settings" icon in the top menu bar.

2. Choose + New service connection and select Azure Resource Manager.

   

3. Specify the following parameters.

   Parameter	Description
   Connection Name	Required. The name you will use to refer to this service connection in task properties. This is not the name of your Azure subscription.
   Scope level	Select Subscription or Management Group. Management groups are containers that help you manage access, policy, and compliance across multiple subscriptions.
   Subscription	If you selected Subscription for the scope, select an existing Azure subscription. If you don't see any Azure subscriptions or instances, see Troubleshoot Azure Resource Manager service connections.
   Management Group	If you selected Management Group for the scope, select an existing Azure management group. See Create management groups.
   Resource Group	Leave empty to allow users to access all resources defined within the subscription, or select a resource group to which you want to restrict users' access (users will be able to access only the resources defined within that group).

4. After the new service connection is created:

   • If you're using the classic editor, select the connection name you assigned in the Azure subscription setting of your pipeline.
   • If you're using YAML, copy the connection name into your code as the azureSubscription value.

5. To deploy to a specific Azure resource, the task will need additional data about that resource.

   • If you're using the classic editor, select data you need. For example, the App Service name.
   • If you're using YAML, then go to the resource in the Azure portal, and then copy the data into your code. For example, to deploy a web app, you would copy the name of the App Service into the WebAppName value.

Note

When you follow this approach, Azure DevOps connects with Microsoft Entra ID and creates an app registration with a secret that's valid for two years. When the service connection is close to two years old, Microsoft Entra ID displays this prompt: A certificate or secret is expiring soon. Create a new one. In this scenario, you must refresh the service connection.

To refresh a service connection, in the Azure DevOps portal, edit the connection and select Verify. After you save the edit, the service connection is valid for another two years.

See also: Troubleshoot Azure Resource Manager service connection.

If you have problems using this approach (such as no subscriptions being shown in the drop-down list), or if you want to further limit users' permissions, you can instead use a service principal or a VM with a managed service identity.

Create an Azure Resource Manager service connection with an existing service principal

1. If you want to use a predefined set of access permissions, and you don't already have a suitable service principal defined, follow one of these tutorials to create a new service principal:

   • Use the portal to create a Microsoft Entra application and a service principal that can access resources
   • Use Azure PowerShell to create an Azure service principal with a certificate

2. In Azure DevOps, open the Service connections page from the project settings page. In TFS, open the Services page from the "settings" icon in the top menu bar.

3. Choose + New service connection and select Azure Resource Manager.

   

4. Choose Service Principal (manual) option and enter the Service Principal details.

   

5. Enter a user-friendly Connection name to use when referring to this service connection.

6. Select the Environment name (such as Azure Cloud, Azure Stack, or an Azure Government Cloud).

7. If you do not select Azure Cloud, enter the Environment URL. For Azure Stack, this will be something like https://management.local.azurestack.external

8. Select the Scope level you require:

   • If you choose Subscription, select an existing Azure subscription. If you don't see any Azure subscriptions or instances, see Troubleshoot Azure Resource Manager service connections. |
   • If you choose Management Group, select an existing Azure management group. See Create management groups. |

9. Enter the information about your service principal into the Azure subscription dialog textboxes:

   • Subscription ID
   • Subscription name
   • Service principal ID
   • Either the service principal client key or, if you have selected Certificate, enter the contents of both the certificate and private key sections of the *.pem file.
   • Tenant ID

   You can obtain this information if you don't have it to hand by downloading and running this PowerShell script in an Azure PowerShell window. When prompted, enter your subscription name, password, role (optional), and the type of cloud such as Azure Cloud (the default), Azure Stack, or an Azure Government Cloud.

10. Choose Verify connection to validate the settings you entered.

11. After the new service connection is created:

    • If you are using it in the UI, select the connection name you assigned in the Azure subscription setting of your pipeline.
    • If you are using it in YAML, copy the connection name into your code as the azureSubscription value.

12. If required, modify the service principal to expose the appropriate permissions. For more details, see Use Role-Based Access Control to manage access to your Azure subscription resources. This blog post also contains more information about using service principal authentication.

See also: Troubleshoot Azure Resource Manager service connections.

Create an Azure Resource Manager service connection to a VM with a managed service identity

Note

You are required to use a self-hosted agent on an Azure VM in order to use managed service identity

You can configure Azure Virtual Machines (VM)-based agents with an Azure Managed Service Identity in Microsoft Entra ID. This lets you use the system assigned identity (Service Principal) to grant the Azure VM-based agents access to any Azure resource that supports Microsoft Entra ID, such as Key Vault, instead of persisting credentials in Azure DevOps for the connection.

1. In Azure DevOps, open the Service connections page from the project settings page. In TFS, open the Services page from the "settings" icon in the top menu bar.

2. Choose + New service connection and select Azure Resource Manager.

   

3. Select the Managed Identity Authentication option.

   

4. Enter a user-friendly Connection name to use when referring to this service connection.

5. Select the Environment name (such as Azure Cloud, Azure Stack, or an Azure Government Cloud).

6. Enter the values for your subscription into these fields of the connection dialog:

   • Subscription ID
   • Subscription name
   • Tenant ID

7. After the new service connection is created:

   • If you are using it in the UI, select the connection name you assigned in the Azure subscription setting of your pipeline.
   • If you are using it in YAML, copy the connection name into your code as the azureSubscription value.

8. Ensure that the VM (agent) has the appropriate permissions. For example, if your code needs to call Azure Resource Manager, assign the VM the appropriate role using Role-Based Access Control (RBAC) in Microsoft Entra ID. For more details, see How can I use managed identities for Azure resources? and Use Role-Based Access Control to manage access to your Azure subscription resources.

See also: Troubleshoot Azure Resource Manager service connections.

Connect to an Azure Government Cloud

For information about connecting to an Azure Government Cloud, see:

• Connecting from Azure Pipelines (Azure Government Cloud)

Connect to Azure Stack

For information about connecting to Azure Stack, see:

• Connect to Azure Stack
• Connect Azure Stack to Azure using VPN
• Connect Azure Stack to Azure using ExpressRoute

Help and support

• See our troubleshooting page
• Get advice on Stack Overflow, and feel free to post your questions, search for answers, or suggest a feature on our Azure DevOps Developer Community. Support page.