Connect to Microsoft Azure

Azure Pipelines | Azure DevOps Server 2019 | TFS 2018 | TFS 2017

Note

In Microsoft Team Foundation Server (TFS) 2018 and previous versions, run and release pipelines are called definitions, runs are called builds, service connections are called service endpoints, stages are called environments, and jobs are called phases.

To deploy your app to an Azure resource (to an app service or to a virtual machine), you need an Azure Resource Manager service connection.

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 automated security

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.

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 pre-defined 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. Switch from the simplified version of the dialog to the full version using the link in the dialog.

    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

You can configure Azure Virtual Machines (VM)-based agents with an Azure Managed Service Identity in Azure Active Directory (Azure AD). This lets you use the system assigned identity (Service Principal) to grant the Azure VM-based agents access to any Azure resource that supports Azure AD, 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 Azure AD. 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:

Help and support