Access Azure DevOps with Microsoft Entra workload identity

Azure DevOps Services

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

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:

• Check that the service connection name in your pipeline YAML matches the name you created.
• Check that the service principal has appropriate permissions for the resources you're accessing.
• Check Azure DevOps audit logs for authentication failures.
• Refer to frequently asked questions for service principals and managed identities.
• For Microsoft Entra AADSTS status codes, review the list of error messages.

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

Microsoft Entra ID error messages

The following table lists common Microsoft Entra ID error codes and possible issues related to workload identity service connections:

Is the AADSTS error you see not listed above? Check Microsoft Entra authentication and authorization error codes.

Next steps

• Use service connections in your pipeline.
• Manage service connections.
• Learn about workload identity federation.