Skip to content

add-devops-entra-service-connection.md

Latest commit

 

History

History
257 lines (179 loc) · 13.1 KB

add-devops-entra-service-connection.md

File metadata and controls

257 lines (179 loc) · 13.1 KB
title Access Azure DevOps with Microsoft Entra workload identity
description Learn how to create an Azure DevOps service connection using Microsoft Entra federated credentials to enable PAT-free pipelines.
ms.topic how-to
ms.date 03/23/2026

Access Azure DevOps with Microsoft Entra workload identity

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

[!INCLUDE feature-rollout]

An Azure DevOps service connection lets your pipelines authenticate to Azure DevOps without Personal Access Tokens (PATs) by using Microsoft Entra workload identities. Service principals and managed identities access Azure DevOps through workload identity federation, a zero-secret method that eliminates the need to manage and rotate secrets.

Benefits

  • PAT-free authentication: Eliminate the need to create, store, and rotate Personal Access Tokens.
  • Least privilege: Use per-pipeline permissions instead of shared build service account permissions.
  • Improved security: Use Entra federated credentials with automatic token rotation.
  • Cross-organization access: Access Azure DevOps resources in different organizations by using a single service connection.
  • Audit trail: All authentication attempts are logged in Azure DevOps audit logs.

Supported scenarios

The Azure DevOps service connection supports these scenarios:

  • Repository resources: Check out code from repositories in different Azure DevOps organizations.
  • Artifact feeds: Access Azure Artifacts feeds (NuGet, npm, Maven, Python, Cargo, Conda) across organizations without PATs.
  • REST API calls: Authenticate to Azure DevOps REST APIs from inline scripts.
  • Extension publishing: Publish extensions to Visual Studio Marketplace.

Prerequisites

To create an Azure DevOps service connection, you need:

  • An Azure DevOps organization
  • An Entra service principal or managed identity to use for authentication
  • Creator or Administrator role for service connections in the Azure DevOps project where you create the service connection. By default, members of the Endpoint Creators group have the Creator role. For more information, see Set service connection security.
  • If accessing resources across organizations, the service principal or managed identity must be added as a user to each target organization

Step 1: Create a service connection within the same organization

If your service principal is in the same Azure DevOps organization as the service connection:

Add the service principal to your organization

  1. In your Azure DevOps organization, go to Organization Settings > Users.

  2. Select Add users.

  3. Enter the service principal details:

    • Name: The service principal or managed identity name or object ID
    • Access level: Select the appropriate access level. Use Basic for standard access

  4. Assign the service principal or managed identity to the project where you'll create the service connection e.g. by adding it to the Readers group

  5. Select Add to confirm.

  6. Assign any additional resource level permissions to the service principal or managed identity

Step 2: Create the service connection

  1. In your Azure DevOps project, go to Project Settings > Service connections.

  2. Select New service connection.

  3. Select Azure DevOps as the service connection type.

  4. Complete the form:

    • Identity: Select the service principal you added to your organization
    • Service connection name: Enter a descriptive name for the connection (for example, my-azdo-connection)
    • Description (optional): Add details about the connection's purpose

  5. Select Save to create the service connection.

Create a service connection for cross-organization access

To access resources in a different Azure DevOps organization joined to the same Entra ID tenant:

  1. Follow the steps in Create a service connection within the same organization, but select Different organization when creating the service connection.

  2. Enter the name of the target Azure DevOps organization.

  3. You must also add the service principal as a user in the target organization.

Use the service connection in your pipeline

Check out repositories from different organizations

pool:
  vmImage: 'ubuntu-latest'

resources:
  repositories:
  - repository: external-repo
    type: git
    endpoint: my-azdo-connection
    name: 'external-project/external-repo'
    ref: 'refs/heads/main'

steps:
- checkout: self
- checkout: external-repo

Reference a template from a different organization

resources:
  repositories:
    - repository: templates 
      type: git
      endpoint: my-azdo-connection
      name: 'external-project/external-repo'
      ref: "refs/heads/main"    
      
steps:
- template: azdosc-template.yml@templates

Access artifact feeds

Use the service connection with artifact authentication tasks:

- task: NuGetAuthenticate@1
  inputs:
    nuGetServiceConnections: 'my-azdo-connection'

- task: DotNetCoreCLI@2
  inputs:
    command: 'restore'
    projects: '**/*.csproj'

Call Azure DevOps from script

- task: AzureCLI@3
  displayName: Secret-less
  inputs:
    connectionType: 'azureDevOps'
    azureDevOpsServiceConnection: 'my-azdo-connection'
    scriptType: 'pscore'
    scriptLocation: 'inlineScript'
    inlineScript: |
      az rest --method get `
              --url "https://status.dev.azure.com/_apis/status/health?api-version=7.1-preview.1" `
              --resource 499b84ac-1321-427f-aa17-267ca6975798 `
              --query "sort_by(services[?id=='Pipelines'].geographies | [], &name)" `
              -o table

      az devops configure -l

      az devops project list --query "value[].{Name:name, Id:id}" `
                            -o table

      az pipelines pool list --query "[].{Id:id, Name:name}" `
                            -o table

- task: AzureCLI@3
  displayName: Use Entra access token
  inputs:
    connectionType: 'azureDevOps'
    azureDevOpsServiceConnection: 'my-azdo-connection'
    scriptType: 'pscore'
    scriptLocation: 'inlineScript'
    inlineScript: |
      # Get access token for Azure DevOps
      $token = az account get-access-token --resource "499b84ac-1321-427f-aa17-267ca6975798" `
                                           --query "accessToken" `
                                           --output tsv
      
      # Use token in REST API call
      $headers = @{
        Authorization = "Bearer $token"
        "Content-Type" = "application/json"
      }
      
      $body = @{
        name = "Test Build"
      } | ConvertTo-Json
      
      Invoke-RestMethod -Uri "$(System.CollectionUri)$(System.TeamProject)/_apis/build/definitions?api-version=7.1" `
                        -Method POST `
                        -Headers $headers `
                        -Body $body

The AzureCLI@3 task uses the Azure DevOps CLI, which is preinstalled on Microsoft-hosted agents. On self-hosted agents, you need the Azure CLI with the azure-devops extension. If the azure-devops extension isn't installed, the AzureCLI@3 task installs it at run time.

Security best practices

  • Minimal permissions: Assign the service principal only the permissions it needs for your specific pipeline tasks.
  • Audit access: Regularly review audit logs to monitor service connection usage.
  • Scope usage: Use separate service connections for different projects or organizations to limit shared permissions.

Troubleshooting

Tip

For better security, assign the service principal only the permissions it needs, review audit logs regularly, and use separate service connections for different projects or organizations.

Service connection creation fails

Cause: The service principal isn't added to your organization, or you lack the required permissions.

Fix:

  • Check that you added the service principal as a user to your organization.
  • Check that you have the appropriate permissions to create service connections.
  • Make sure the service principal has the required access level in the organization.

Pipeline fails to authenticate

Cause: The service connection name doesn't match the YAML reference, or the service principal lacks permissions for the target resources.

Fix:

Cross-organization access not working

Cause: You didn't add the service principal as a user in both organizations, or you misspelled the target organization name.

Fix:

  • Add the service principal as a user in both organizations.
  • Check that the target organization name is spelled correctly in the service connection configuration.
  • Check that the service principal has the required permissions in the target organization.

Common error messages

Message Meaning & mitigation
ERROR: TF401444: Please sign-in at least once as 72f988bf-86f1-41af-91ab-2d7cd011db47\72f988bf-86f1-41af-91ab-2d7cd011db47\115c3ab3-943b-4e0c-96ed-1a1763fbaa44 in a web browser to enable access to the service. Check that you added the service principal as a user to your organization.
The Managed Identity / Service Principal <sp/msi name> does not have access to Azure DevOps organization <org>. Please make sure the identity has been added to the organization. See https://aka.ms/azdosc#prerequisites Add the service principal as a user to the target organization and assign it to the required project.
You don't have permission to the selected identity. Service connection is saved as draft. To complete the configuration, contact the owner of the identity to create a federated credential in the Azure portal using the Issuer and Subject Identifier below. The signed-in user doesn't have sufficient permissions to create federated credentials. Follow the instructions displayed to create federated credentials directly on the identity.
VS800075: The project with id 'vstfs:///Classification/TeamProject/00000000-0000-00000000-000000000000' does not exist, or you do not have permission to access it. The service connection identity isn't added to the project. Go to service connection details page > View access in the current organization > Member of > Select a group to add the identity to, for example, the Readers group. Alternatively, go to Organization Settings > Users > The identity used for the service connection > Manage access > select the projects the identity needs to access.

Microsoft Entra ID error messages

[!INCLUDE errors-workload-identity]

Next steps