Skip to content

authentication-guidance.md

Latest commit

 

History

History
182 lines (121 loc) · 11.2 KB

authentication-guidance.md

File metadata and controls

182 lines (121 loc) · 11.2 KB
title Authentication Methods for Azure DevOps
titleSuffix Azure DevOps
description Choose the right authentication method for your Azure DevOps integration, with Microsoft Entra ID as the recommended approach.
ms.assetid 15CCEB1E-F42B-4439-8C35-B8A225F5546C
ms.subservice azure-devops-security
ms.topic concept-article
ms.custom arm2024, pat-reduction, copilot-scenario-highlight
ai-usage ai-assisted
monikerRange <= azure-devops
ms.author chcomley
author chcomley
ms.date 03/18/2026

Authentication methods for Azure DevOps

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

This article describes authentication methods for Azure DevOps integration and helps you choose the best option for your scenario. Modern authentication approaches like Microsoft Entra ID provide enhanced security and are the best approach for new applications.

Use Microsoft Entra ID authentication for new applications that integrate with Azure DevOps Services. Use personal access tokens sparingly, and only when Microsoft Entra ID isn't available.

[!INCLUDE use-microsoft-entra-reduce-pats]

OAuth 2.0 and Microsoft Entra ID authentication are available for Azure DevOps Services only, not Azure DevOps Server.

For on-premises scenarios, use .NET client libraries, Windows authentication, or personal access tokens.

[!INCLUDE ai-assistance-mcp-server-tip]

Authentication methods by scenario

Choose the appropriate authentication method based on your application type and requirements.

Application type Description Example Recommended method Code samples
Web/desktop apps Interactive applications using current frameworks React app, .NET desktop app Microsoft Entra OAuth with the Microsoft Authentication Library (MSAL) Managed client console app
Service/background apps Applications running without user interaction Azure Functions, background services Service principals and managed identities Service principals
Legacy client apps Existing applications using client libraries Console apps with Azure DevOps .NET libraries .NET client libraries with OAuth Client library console app
Headless/CLI apps Noninteractive command-line tools Build scripts, automation tools Device authorization grant flow Device profile
Azure DevOps extensions Extensions running within Azure DevOps Custom dashboard widgets and work item forms Azure DevOps web extension SDK Add a dashboard widget
Azure DevOps Server apps On-premises Azure DevOps Server integrations Custom server extensions .NET client libraries or Windows Auth Client library console app
Personal/ad hoc scripts Quick scripts for personal use PowerShell scripts, curl commands Personal access tokens Get started with the REST APIs

Suggestions for getting started

The following sections provide recommendations for getting started in different scenarios.

New applications

Existing applications

  • Plan migration from personal access tokens to Microsoft Entra ID authentication.
  • Consider the authentication migration timeline for Azure DevOps improvements and reducing the use of personal access tokens.
  • Review your current authentication approach against security best practices.

Azure DevOps Server

  • Use .NET client libraries with Windows Authentication when possible.
  • Use personal access tokens for Azure DevOps Server scenarios when they're acceptable.
  • Plan for future Azure DevOps Services migration to take advantage of modern authentication.

Frequently asked questions (FAQ)

Should I use Microsoft Entra ID OAuth or personal access tokens?

Use Microsoft Entra ID OAuth in the following scenarios:

  • New applications and integrations.
  • Production workloads that require robust security.
  • Applications that need enterprise identity integration.
  • Long-term projects with compliance requirements.

Use personal access tokens only in the following scenarios:

  • Personal scripts and ad hoc tasks.
  • Legacy applications during migration planning.
  • Azure DevOps Server scenarios where modern authentication isn't available.

Should I use service principals or user delegation for authentication?

Use service principals or managed identities in the following scenarios:

  • Build applications that operate independently (background services, automation).
  • Create apps that don't require user interaction.
  • Implement service-to-service communication.
  • Build continuous integration and continuous delivery (CI/CD) pipelines or automated workflows.

Use user delegation (OAuth with user consent) in the following scenarios:

  • Build applications that act for human users.
  • Create interactive apps where users sign in with their own credentials.
  • Implement features that require user-specific permissions.
  • Build apps that respect users' individual access rights.

How do I authenticate with both Azure DevOps Services and Azure DevOps Server?

Create separate authentication paths for each service:

  • Azure DevOps Services: Use Microsoft Entra ID OAuth.
  • Azure DevOps Server: Use .NET client libraries with Windows Authentication or personal access tokens.

Use the requestContext method to detect the service type, and apply the appropriate authentication method.

Why can't my service account access Azure DevOps APIs?

Here are some common issues that affect service account access:

  • Service account not "materialized": Use the correct sign-in method. Service accounts need interactive sign-in permissions or proper Microsoft Entra ID registration.
  • Insufficient permissions: Ensure that the service account has appropriate Azure DevOps permissions.
  • Authentication method: Use service principals or managed identities instead of trying to authenticate as a service account.

How do I migrate from personal access tokens to modern authentication?

Follow these steps:

  1. Identify current personal access token usage in your applications.

  2. Choose an alternate authentication method:

    • Microsoft Entra ID OAuth for user-delegated scenarios
    • Service principals for service-to-service scenarios

  3. Update the authentication code by using the Azure DevOps migration authentication samples.

  4. Test the changes thoroughly before you remove any personal access token dependencies.

  5. Monitor and validate the new authentication method.

Why shouldn't I decode or read claims from authentication tokens?

Authentication tokens exist solely to prove who the caller is and what they're authorized to do. They're not a stable data interface or a schema you can depend on.

Token claims are never publicly documented, and Azure DevOps reserves the right to change, rename, remove, or encrypt them at any time without notice. Starting summer 2025, Azure DevOps is further encrypting authentication tokens, which means clients can't read token payloads. Any application that decodes tokens to extract claims breaks.

Instead of reading token claims, follow these practices:

  • Treat tokens as opaque — pass them in authorization headers, but don't decode or inspect them.
  • Use supported REST APIs — retrieve user or organization data from Azure DevOps REST APIs, which provide stable contracts and documentation.
  • Assume any claim can change — if you find yourself parsing token contents to read values, put that logic in an API call instead.

These changes don't affect applications that already treat tokens as opaque.

Implementation procedures

After you choose the authentication method for your scenario, finish the implementation steps:

Use AI to choose an authentication method

If you connect the Azure DevOps MCP Server to your AI agent in agent mode, you can use natural language prompts to get authentication recommendations for your scenario.

Task Example prompt
Choose auth for a background service Which authentication method should I use for a background Azure Function that needs to access Azure DevOps APIs?
Compare auth options Help me choose between service principals, managed identities, and personal access tokens for my Azure DevOps integration
Auth for a web app I'm building a React web app that needs to access Azure DevOps on behalf of signed-in users — what authentication approach should I use?
Migrate from PATs Help me plan a migration from personal access tokens to Microsoft Entra ID authentication for my Azure DevOps integrations
Auth for CI/CD What's the most secure way to authenticate Azure DevOps REST API calls from a GitHub Actions workflow?
Troubleshoot auth failures I'm getting 401 errors when calling the Azure DevOps REST API with my token — help me diagnose the issue

Note

Agent mode and the MCP Server use natural language, so you can adjust these prompts or ask follow-up questions to refine the results.

Related content