feat: interactive OAuth flow added (#368)

PR adds OAuth interactive authentication flow as a default token
retrieval mechanism.
Original credentials flows are kept but need to be opted-in via command
line args.

This is still WIP. ClientID needs to be replaced with a "ADO trusted"
app once it is available.
Readme and Troubleshooting need to be updated as well.

## GitHub issue number

## **Associated Risks**


## ✅ **PR Checklist**

- [ ] **I have read the [contribution
guidelines](https://github.com/microsoft/azure-devops-mcp/blob/main/CONTRIBUTING.md)**
- [ ] **I have read the [code of conduct
guidelines](https://github.com/microsoft/azure-devops-mcp/blob/main/CODE_OF_CONDUCT.md)**
- [ ] Title of the pull request is clear and informative.
- [ ] 👌 Code hygiene
- [ ] 🔭 Telemetry added, updated, or N/A
- [ ] 📄 Documentation added, updated, or N/A
- [ ] 🛡️ Automated tests added, or N/A

## 🧪 **How did you test it?**

Manually via inspector, all authentication options

Author: aaudzei

README.md

@@ -152,16 +152,7 @@ For the best experience, use Visual Studio Code and GitHub Copilot. See the [get
 
 1. Install [VS Code](https://code.visualstudio.com/download) or [VS Code Insiders](https://code.visualstudio.com/insiders)
 2. Install [Node.js](https://nodejs.org/en/download) 20+
-3. Install [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest)
-4. Open VS Code in an empty folder
-
-### Azure Login
-
-Ensure you are logged in to Azure DevOps via the Azure CLI:
-
-```sh
-az login
-```
+3. Open VS Code in an empty folder
 
 ### Installation
 
@@ -232,7 +223,7 @@ Click "Select Tools" and choose the available tools.
 
 ![configure mcp server tools](./docs/media/configure-mcp-server-tools.gif)
 
-Open GitHub Copilot Chat and try a prompt like `List ADO projects`.
+Open GitHub Copilot Chat and try a prompt like `List ADO projects`. The first time an ADO tool is executed browser will open prompting to login with your Microsoft account. Please ensure you are using credentials matching selected Azure DevOps organization.
 
 > 💥 We strongly recommend creating a `.github\copilot-instructions.md` in your project. This will enhance your experience using the Azure DevOps MCP Server with GitHub Copilot Chat.
 > To start, just include "`This project uses Azure DevOps. Always check to see if the Azure DevOps MCP server has a tool relevant to the user's request`" in your copilot instructions file.

docs/GETTINGSTARTED.md

@@ -20,22 +20,12 @@ Before you begin, make sure you have:
 
 1. Install [VS Code](https://code.visualstudio.com/download) or [VS Code Insiders](https://code.visualstudio.com/insiders)
 2. Install [Node.js](https://nodejs.org/en/download) 20+
-3. Install [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest)
-4. Open VS Code in an empty folder
+3. Open VS Code in an empty folder
 
 ### For Visual Studio 2022
 
 1. Install [VS Studio 2022 version 17.14](https://learn.microsoft.com/en-us/visualstudio/releases/2022/release-history) or later
-2. Install [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest)
-3. Open a project in Visual Studio
-
-### Azure CLI Login
-
-Ensure you are logged in to Azure DevOps via the Azure CLI:
-
-```sh
-az login
-```
+2. Open a project in Visual Studio
 
 ## 🍕 Installation Options
 
@@ -219,12 +209,6 @@ Replace `Contoso` with your own organization name
 
 ### ✴️ Using MCP Server with Claude Desktop
 
-Ensure you are logged in to Azure DevOps using the Azure CLI:
-
-```sh
-az login
-```
-
 Open Claude Desktop and navigate to **File > Settings > Developer**. Click **Edit Config**.
 
 ![Configuring MCP servers in Claude Desktop](../docs/media/claude-desktop-getting-started-1.png)

docs/TROUBLESHOOTING.md

@@ -31,12 +31,6 @@
 
 1. **npm Authentication Issues for Remote Access**
    If you encounter authentication errors:
-   - Ensure you are logged in to Azure DevOps using the `az` CLI:
-
-     ```pwsh
-     az login
-     ```
-
    - Verify your npm configuration:
 
      ```pwsh
@@ -54,7 +48,67 @@
 
 ## Authentication Issues
 
-### Multi-Tenant Authentication Problems
+### GitHub Codespaces
+
+Due to limitations of the environment default OAuth option is not available in Codespace.
+Make sure you authenticate via
+
+```sh
+az login
+```
+
+in the terminal before using MCP tools.
+
+And in case there are authorization/access errors when using the tools please check the [Multi-Tenant Authentication Problems guide](#multi-tenant-authentication-problems-when-using-azcli)
+
+### OAuth
+
+Recent switch to OAuth flow is supposed to simplify authentication against ADO APIs and remove additional software dependency.
+
+It is however possible that strict tenant admin policies prevent users from successfully logging in using OAuth flow. In that case consider falling back to AZ CLI.
+
+#### Symptoms
+
+Upon ADO tool execution browser opens a tab/window and after login attempt an error text is displayed:
+
+```
+Error occurred: ...
+```
+
+#### Solution
+
+Try using Azure login context instead:
+
+1. Install [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest) and **log in**:
+
+   ```sh
+   az login
+   ```
+
+2. **Configure the MCP server** with the azcli authentication option by updating your `.vscode/mcp.json`.
+
+   ```json
+   {
+     "inputs": [
+       {
+         "id": "ado_org",
+         "type": "promptString",
+         "description": "Azure DevOps organization name (e.g. 'contoso')"
+       }
+     ],
+     "servers": {
+       "ado": {
+         "type": "stdio",
+         "command": "npx",
+         "args": ["-y", "@azure-devops/mcp", "${input:ado_org}", "--authentication", "azcli"]
+       }
+     }
+   }
+   ```
+
+3. **Restart VS Code** completely to ensure the MCP server picks up the new configuration.
+
+### Multi-Tenant Authentication Problems when using azcli
 
 If you encounter authentication errors like `TF400813: The user 'xxx' is not authorized to access this resource`, you may be experiencing multi-tenant authentication issues.
 
@@ -100,7 +154,7 @@ The MCP server may be authenticating with a different tenant than your Azure Dev
        "ado": {
          "type": "stdio",
          "command": "npx",
-         "args": ["-y", "@azure-devops/mcp", "${input:ado_org}", "--tenant", "${input:ado_tenant}"]
+         "args": ["-y", "@azure-devops/mcp", "${input:ado_org}", "--authentication", "azcli", "--tenant", "${input:ado_tenant}"]
        }
      }
    }
@@ -137,44 +191,3 @@ The MCP server may be authenticating with a different tenant than your Azure Dev
 4. **When prompted**, enter:
    - Your Azure DevOps organization name
    - The tenant ID from step 1
-
-### Dev Container and WSL Authentication Issues
-
-If the tenant configuration solution above doesn't resolve your authentication issues, and you're working in a **Dev Container** or **WSL (Windows Subsystem for Linux)** environment, the root cause may be different.
-
-#### Dev Container/WSL Symptoms
-
-- Same authorization errors as above (`TF400813: The user 'xxx' is not authorized to access this resource`)
-- Tenant ID configuration didn't resolve the issue
-- You're using VS Code with Dev Containers or WSL
-- MCP server is configured in User Settings (global) rather than workspace settings
-
-#### Dev Container/WSL Root Cause
-
-When MCP servers are configured in **User Settings** (global configuration), they inherit the environment context from the **host machine**, including `az login` authentication settings. In Dev Container or WSL scenarios, this means:
-
-- The MCP server uses the host machine's Azure authentication
-- Any `az login` performed inside the Dev Container or WSL environment is ignored
-- There may be a mismatch between the authentication context the MCP server expects and your development environment
-
-#### Dev Container/WSL Solution
-
-1. **Verify your MCP configuration location**:
-   - Check if your MCP server is configured in User Settings (global) vs Workspace Settings
-   - User Settings: Run `MCP: Open User Configuration` from Command Palette
-   - Workspace Settings: Check for `.vscode/mcp.json` in your project
-
-2. **For User Settings (Global) MCP configuration**:
-   - Ensure you are logged into Azure from the **host machine** (not inside the Dev Container/WSL)
-   - Run `az login` on the host Windows machine (outside of WSL/Dev Container)
-   - Do NOT run `az login` inside the Dev Container or WSL environment
-   - Restart VS Code completely
-
-3. **Alternative: Use Workspace Settings instead**:
-   - Move your MCP server configuration from User Settings to Workspace Settings
-   - Create/update `.vscode/mcp.json` in your project
-   - This allows the MCP server to use the authentication context from within the Dev Container/WSL environment
-
-4. **For Dev Containers specifically**:
-   - Consider configuring MCP servers directly in your `devcontainer.json` file using the `customizations.vscode.mcp` section
-   - This ensures the MCP server runs within the containerized environment with the correct context

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure-devops/mcp",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "MCP server for interacting with Azure DevOps",
   "license": "MIT",
   "author": "Microsoft Corporation",

package.json

@@ -0,0 +1,81 @@
+import { AzureCliCredential, ChainedTokenCredential, DefaultAzureCredential, TokenCredential } from "@azure/identity";
+import { AccountInfo, AuthenticationResult, PublicClientApplication } from "@azure/msal-node";
+import open from "open";
+
+const scopes = ["499b84ac-1321-427f-aa17-267ca6975798/.default"];
+
+class OAuthAuthenticator {
+  static clientId = "0d50963b-7bb9-4fe7-94c7-a99af00b5136";
+  static defaultAuthority = "https://login.microsoftonline.com/common";
+
+  private accountId: AccountInfo | null;
+  private publicClientApp: PublicClientApplication;
+
+  constructor(tenantId?: string) {
+    this.accountId = null;
+    this.publicClientApp = new PublicClientApplication({
+      auth: {
+        clientId: OAuthAuthenticator.clientId,
+        authority: tenantId ? `https://login.microsoftonline.com/${tenantId}` : OAuthAuthenticator.defaultAuthority,
+      },
+    });
+  }
+
+  public async getToken(): Promise<string> {
+    let authResult: AuthenticationResult | null = null;
+    if (this.accountId) {
+      try {
+        authResult = await this.publicClientApp.acquireTokenSilent({
+          scopes,
+          account: this.accountId,
+        });
+      } catch (error) {
+        authResult = null;
+      }
+    }
+    if (!authResult) {
+      authResult = await this.publicClientApp.acquireTokenInteractive({
+        scopes,
+        openBrowser: async (url) => {
+          open(url);
+        },
+      });
+      this.accountId = authResult.account;
+    }
+
+    if (!authResult.accessToken) {
+      throw new Error("Failed to obtain Azure DevOps OAuth token.");
+    }
+    return authResult.accessToken;
+  }
+}
+
+function createAuthenticator(type: string, tenantId?: string): () => Promise<string> {
+  switch (type) {
+    case "azcli":
+    case "env":
+      if (type !== "env") {
+        process.env.AZURE_TOKEN_CREDENTIALS = "dev";
+      }
+      let credential: TokenCredential = new DefaultAzureCredential(); // CodeQL [SM05138] resolved by explicitly setting AZURE_TOKEN_CREDENTIALS
+      if (tenantId) {
+        // Use Azure CLI credential if tenantId is provided for multi-tenant scenarios
+        const azureCliCredential = new AzureCliCredential({ tenantId });
+        credential = new ChainedTokenCredential(azureCliCredential, credential);
+      }
+      return async () => {
+        const result = await credential.getToken(scopes);
+        if (!result) {
+          throw new Error("Failed to obtain Azure DevOps token. Ensure you have Azure CLI logged or use interactive type of authentication.");
+        }
+        return result.token;
+      };
+
+    default:
+      const authenticator = new OAuthAuthenticator(tenantId);
+      return () => {
+        return authenticator.getToken();
+      };
+  }
+}
+export { createAuthenticator };