Skip to content

Latest commit

 

History

History
285 lines (174 loc) · 16.3 KB

connect-to-azure.md

File metadata and controls

285 lines (174 loc) · 16.3 KB
title ms.custom description ms.assetid ms.topic ms.author author ms.date monikerRange
Connect to Microsoft Azure with an ARM service connection
seodec18, devx-track-arm-template
Use an ARM service connection to connect Azure Pipelines or TFS to Microsoft Azure
4CC6002E-9EF6-448C-AD48-5C618C103950
conceptual
ronai
RoopeshNair
08/15/2023
<= azure-devops

Connect to Microsoft Azure with an ARM service connection

[!INCLUDE version-lt-eq-azure-devops]

[!INCLUDE temp]

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:

::: moniker range="azure-devops"

  • service principal or managed identity with workload identity federation ::: moniker-end
  • 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.

::: moniker range="azure-devops"

Create an Azure Resource Manager service connection using workload identity federation

[!INCLUDE 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.

    Screenshot of choosing a workload identity service connection type.

  3. Select Workload identity federation (automatic).

    Screenshot of selecting a workload identity service connection type.

  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.

    :::image type="content" source="media/federated-convert-credential.png" alt-text="Screenshot of selecting convert for federated credential.":::

  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.

    :::image type="content" source="media/federated-revert-credential.png" alt-text="Screenshot of selecting revert for federated credential.":::

  5. Select Revert again to confirm your choice.

::: moniker-end

::: moniker range=">=azure-devops-2020"

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.

    Choosing a service connection type

  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.

::: moniker-end

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:

  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.

    Choosing a service connection type

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

    Opening the full version of the service dialog

  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:

  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.

    Choosing a service connection type

  3. Select the Managed Identity Authentication option.

    Opening the managed service identity settings

  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:

Connect to Azure Stack

For information about connecting to Azure Stack, see:

[!INCLUDE rm-help-support-shared]