Troubleshoot Azure Resource Manager service connections

Azure Pipelines | Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018 - TFS 2015

Note

In Microsoft Team Foundation Server (TFS) 2018 and previous versions, build 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.

This topic will help you resolve issues you may encounter when creating a connection to Microsoft Azure using an Azure Resource Manager ARM service connection for your Azure DevOps CI/CD processes.

What happens when you create a Resource Manager service 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 the type of service connection you need.

  3. In the Add Azure Resource Manager service connection dialog, provide a connection name, and select a subscription from drop-down list of your subscriptions.

The Add Azure Resource Manager service connection dialog

When you select OK, the system:

  1. Connects to the Azure Active Directory (Azure AD) tenant for to the selected subscription.
  2. Creates an application in Azure AD on behalf of the user.
  3. After the application has been successfully created, assigns the application as a contributor to the selected subscription.
  4. Creates an Azure Resource Manager service connection using this application's details.

How to troubleshoot errors that may occur while creating a connection?

Errors that may occur when the system attempts to create the service connection include:

Insufficient privileges to complete the operation

This typically occurs when the system attempts to create an application in Azure AD on your behalf.

This is a permission issue that may be due to the following causes:

The user has only guest permission in the directory

The best approach to resolve this issue, while granting only the minimum additional permissions to the user, is to increase the Guest user permissions as follows.

  1. Sign in to the Azure portal using an administrator account. The account should be an owner, global administrator, or user account administrator.

  2. Select Azure Active Directory in the left navigation bar.

  3. Ensure you are editing the appropriate directory corresponding to the user subscription. If not, select Switch directory and log in using the appropriate credentials if required.

  4. In the MANAGE section select Users.

  5. Select User settings.

  6. In the External users section, select Manage external collaboration settings.

  7. The External collaboration settings blade opens.

  8. Change Guest user permissions are limited to No.

Alternatively, if you are prepared to give the user additional permissions (administrator-level), you can make the user a member of the Global administrator role. To do so follow the steps below:

Warning

Users who are assigned to the Global administrator role can read and modify every administrative setting in your Azure AD organization. As a best practice, we recommend that you assign this role to fewer than five people in your organization.

  1. Sign in to the Azure portal using an administrator account. The account should be an owner, global administrator, or user account administrator.

  2. Select Azure Active Directory in the left navigation bar.

  3. Ensure you are editing the appropriate directory corresponding to the user subscription. If not, select Switch directory and log in using the appropriate credentials if required.

  4. In the MANAGE section select Users.

  5. Use the search box to filter the list and then select the user you want to manage.

  6. In the MANAGE section select Directory role and change the role to Global administrator.

  7. Save the change.

It typically takes 15 to 20 minutes to apply the changes globally. After this period has elapsed, the user can retry creating the service connection.

The user is not authorized to add applications in the directory

You must have permissions to add integrated applications in the directory. The directory administrator has permissions to change this setting.

  1. Select Azure Active Directory in the left navigation bar.

  2. Ensure you are editing the appropriate directory corresponding to the user subscription. If not, select Switch directory and log in using the appropriate credentials if required.

  3. In the MANAGE section select Users.

  4. Select User settings.

  5. In the App registrations section, change Users can register applications to Yes.

Create the service principal manually with the user already having required permissions in Azure Active Directory

You can also create the service principal with an existing user who already has the required permissions in Azure Active Directory. For more information, see Create an Azure Resource Manager service connection with an existing service principal.

Failed to obtain an access token or a valid refresh token was not found

These errors typically occur when your session has expired.

To resolve these issues:

  1. Sign out of Azure Pipelines or TFS.
  2. Open an InPrivate or incognito browser window and navigate to https://visualstudio.microsoft.com/team-services/.
  3. If you are prompted to sign out, do so.
  4. Sign in using the appropriate credentials.
  5. Choose the organization you want to use from the list.
  6. Select the project you want to add the service connection to.
  7. Create the service connection you need by opening the Settings page. Then, select Services > New service connection > Azure Resource Manager.

Failed to assign Contributor role

This error typically occurs when you do not have Write permission for the selected Azure subscription when the system attempts to assign the Contributor role.

To resolve this issue, ask the subscription administrator to assign you the appropriate role.

Some subscriptions are missing from the list of subscriptions

To fix this issue you will need to modify the supported account types and who can use your application. To do so, follow the steps below:

  1. Sign in to the Azure portal.

  2. If you have access to multiple tenants, use the Directory + subscription filter in the top menu to select the tenant in which you want to register an application.

  3. Search for and select Azure Active Directory.

  4. Under Manage, select App registrations.

  5. Select you application from the list of registered applications.

  6. Under Essentials, select Supported account types.

  7. Under Supported account types, Who can use this application or access this API? select Accounts in any organizational directory.

  8. Select Save.

Subscription isn't listed when creating a service connection

A maximum of 50 Azure subscriptions are listed in the various Azure subscription drop-down menus (billing, service connection, etc.). If you're setting up a service connection and you have more than 50 Azure subscriptions, some of your subscriptions won't be listed. In this scenario, complete these steps:

  1. Create a new, native Azure AD user in the Azure AD instance for the Azure subcription.

  2. Set up the Azure AD user so that it has the proper permissions in the Azure subcription to set up Azure DevOps billing or a service connection. For more information, see Add a user who can set up billing for Azure DevOps.

  3. Add the Azure AD user to the Azure DevOps org with the access level of Stakeholder and add them to the Project Collection Administrators group (for billing), or ensure that the user has sufficient permissions in the Team Project to create service connections.

  4. Log in to Azure DevOps as this user and set up a billing service connection. You'll only see one Azure subcription in the list.

Automatically created service principal client secret has expired

An issue that often arises with service principals that are automatically created is that the service principal's token expires and needs to be renewed. If you run into issues with refreshing the token, check out our other troubleshooting resolutions.

To renew the token for an automatically created service principal:

  1. Go to the Azure Resource Manager service connection that was created by using the Automatic method.

  2. In the upper-right corner, click Edit.

  3. Click Verify on the service connection page.

  4. Click Save. The client secret for that service principal has now been renewed for two years.

Failed to obtain the JWT by using the service principal client ID

This issue occurs when you try to verify a service connection that has an expired secret.

To resolve this issue:

  1. Go to the Azure Resource Manager service connection you want to update.

  2. Make a change to the service connection. The easiest and recommended change is to add a description.

  3. Save the service connection.

    Note

    Select Save. Don't try to verify at this step.

  4. Exit the service connection, and then refresh the service connections page.

  5. Edit the service connection again.

  6. Click Verify.

  7. Save the service connection.

Can't create a service connection manually by using PowerShell scripts and Azure Cloud Shell

To learn how to manually create an Azure Resource Manager service connection, see Create an Azure service principal to use with an Azure Resource Manager service connection.

Azure subscription not taken directly from previous task output

When you set an Azure subscription dynamically for the release pipeline and the subscription is an output variable from a preceding task, you might encounter this issue.

To resolve the issue, ensure that the values are defined within the pipeline variables section, which can be used in the subscription name or the service connection.

What authentication mechanisms are supported? How do Managed Identities work?

Azure Resource Manager service connection can connect to a Microsoft Azure subscription using Service Principal Authentication (SPA) or Managed Identity Authentication. Managed identities for Azure resources provides Azure services with an automatically managed identity in Azure Active Directory. You can use this identity to authenticate to any service that supports Azure AD authentication, without persisting credentials in code or in the service connection. See Assigning roles to learn about managed identities for virtual machines.

Note

Managed identities are not supported in Microsoft Hosted Agents. You will have to set-up a self hosted agent on an Azure VM and configure managed identity for the virtual machine.

Help and support