docs(azure-devops): Add minimum OAuth permissions guidance#57
docs(azure-devops): Add minimum OAuth permissions guidance#57paigealleman-sketch wants to merge 1 commit intomainfrom
Conversation
📝 WalkthroughWalkthroughReplaces a single static permissions list with capability-based permission blocks: "For sync-only (read) access" and "For full provisioning (read/write) access". Both require Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches
🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
baton/azure-devops.mdx (1)
1-8:⚠️ Potential issue | 🟡 MinorAdd the required Editor Refresh comment.
This MDX file is missing the
{/* Editor Refresh: YYYY-MM-DD */}comment. Please add it right after the frontmatter.🛠️ Suggested change
--- title: "Set up an Azure DevOps connector" og:title: "Set up an Azure DevOps connector" description: "ConductorOne provides identity governance and just-in-time provisioning for Microsoft Azure DevOps. Integrate your Azure DevOps instance with ConductorOne to run user access reviews (UARs) and enable just-in-time access requests." og:description: "ConductorOne provides identity governance and just-in-time provisioning for Microsoft Azure DevOps. Integrate your Azure DevOps instance with ConductorOne to run user access reviews (UARs) and enable just-in-time access requests." sidebarTitle: "Microsoft Azure DevOps" --- +{/* Editor Refresh: 2026-02-04 */}As per coding guidelines, Add editor refresh comment in format
{/* Editor Refresh: YYYY-MM-DD */}to MDX documentation files.
🤖 Fix all issues with AI agents
In `@baton/azure-devops.mdx`:
- Around line 61-72: Update the Azure DevOps scopes section to include an
authoritative citation to Microsoft Learn
(https://learn.microsoft.com/vsts/integrate/get-started/auth/oauth) and clarify
the permissions model: state that the listed scopes (user_impersonation,
vso.profile, vso.graph, vso.graph_manage, vso.memberentitlementmanagement_write)
are OAuth delegated scopes per the Microsoft Learn doc, that Azure DevOps does
not support Entra "application permissions" for these REST APIs, and add a short
note advising that for non-interactive automation you must use service
principals or managed identities authorized in the Azure DevOps organization (or
the documented service connection patterns) rather than Entra application
permissions.
baton/azure-devops.mdx
Outdated
| Give the app the relevant permissions based on your use case: | ||
|
|
||
| **Required for all configurations:** | ||
| - **user\_impersonation** - Required for all delegated permissions (Azure DevOps only allows delegated permissions) | ||
| - **vso.profile** - Read user profile information | ||
|
|
||
| **For sync-only (read) access:** | ||
| - **vso.graph** - Read access to users, groups, service principals, and memberships | ||
|
|
||
| **For sync and provisioning (read/write) access:** | ||
| - **vso.graph\_manage** - Read and write access to users, groups, service principals, and memberships | ||
| - **vso.memberentitlementmanagement\_write** - Create and update user entitlements and licenses |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
Microsoft Azure DevOps OAuth scopes documentation user_impersonation vso.profile vso.graph
💡 Result:
The official Microsoft documentation for Azure DevOps OAuth scopes (including user_impersonation, vso.profile, and vso.graph) is on Microsoft Learn → “OAuth 2.0 authentication for Azure DevOps REST APIs”, in the “OAuth scopes” section/table. (learn.microsoft.com)
Key scope meanings (per that table):
vso.profile(User profile – read): read your profile plus “accounts, collections, projects, teams, and other top-level organizational artifacts.” (learn.microsoft.com)vso.graph(Graph – read): read “user, group, scope, and group membership information.” (learn.microsoft.com)user_impersonation(User impersonation): full access to Azure DevOps REST APIs; “request/consent with caution because it’s very powerful.” (learn.microsoft.com)
If you’re using Microsoft Entra ID (Microsoft Identity platform) delegated OAuth, Azure DevOps now supports these more granular scopes (historically, Entra ID apps only had user_impersonation). (devblogs.microsoft.com)
Citations:
- 1: https://learn.microsoft.com/vsts/integrate/get-started/auth/oauth
- 2: https://learn.microsoft.com/vsts/integrate/get-started/auth/oauth
- 3: https://learn.microsoft.com/vsts/integrate/get-started/auth/oauth
- 4: https://learn.microsoft.com/vsts/integrate/get-started/auth/oauth
- 5: https://devblogs.microsoft.com/devops/new-azure-devops-scopes-now-available-for-microsoft-identity-oauth-delegated-flow-apps/?utm_source=openai
🌐 Web query:
Azure DevOps vso.graph_manage vso.memberentitlementmanagement_write OAuth scopes
💡 Result:
-
vso.graph_manage— Azure DevOps Graph (manage): lets an app read users/groups/scopes/memberships and add users/groups and manage group memberships. (Listed under Security → oauth2 → Scopes on Graph REST API pages such as “Memberships - Add”.) [1] -
vso.memberentitlementmanagement_write— Member Entitlement Management (write): lets an app manage users/service principals and their entitlements, including licenses, and the projects/extensions they can access. (Listed under Security → oauth2 → Scopes on Member Entitlement Management REST API pages such as “Update Service Principal Entitlement”.) [2]
These same granular scopes are also available for Microsoft Entra ID (Azure AD) OAuth delegated apps that call Azure DevOps APIs. [3]
Sources: [1] [2] [3]
🌐 Web query:
Azure DevOps REST API application permissions vs delegated permissions authentication
💡 Result:
What “delegated” vs “application” permissions mean (in Entra ID tokens)
- Delegated permissions: your app gets a token on behalf of a signed-in user (authorization code / device code / OBO, etc.). Permissions appear in the token’s
scpclaim. - Application permissions: your app gets a token as itself (client credentials grant). Permissions appear in the token’s
rolesclaim. [1]
How this maps to Azure DevOps REST APIs
Delegated permissions (supported for Azure DevOps REST APIs)
- Azure DevOps’ Entra OAuth integration is designed around delegated user flows (the user signs in/consents; the app calls Azure DevOps as that user). [2]
- Azure DevOps added granular Azure DevOps scopes for delegated flows, and explicitly notes these do not exist as application permissions for app-only flows. [3]
Application permissions (Entra “app-only”) for Azure DevOps REST APIs
- In practice, you generally can’t grant a classic Entra Application permission to call Azure DevOps REST APIs the way you would for Microsoft Graph (i.e., no supported “app role” that lights up Azure DevOps REST with pure client-credentials +
roles). Microsoft guidance is to use other non-interactive options instead. [4]
So how do you do non-interactive / automation access?
Use an identity that Azure DevOps recognizes as an identity in the org, then authorize it in Azure DevOps:
- Service Principal (app registration) or Managed Identity: Azure DevOps supports these for authenticating to Azure DevOps (a PAT alternative). You add the SP/MI to the Azure DevOps org and grant permissions (project/repo/etc.) like a user. [5]
- You then obtain an Entra access token for the Azure DevOps resource (often referenced by app/resource ID
499b84ac-1321-427f-aa17-267ca6975798) and call the REST API withAuthorization: Bearer <token>. [6]
Related note: Azure DevOps “OAuth app platform” deprecation
- Microsoft’s legacy Azure DevOps OAuth app platform stopped accepting new registrations in April 2025, and Microsoft recommends using Microsoft Entra ID OAuth for new apps. [2], [7]
Rule of thumb
- If you need “run as the user” → delegated OAuth.
- If you need “run as the app/service” → service principal or managed identity, authorized inside Azure DevOps (not Entra “application permissions” to Azure DevOps REST). [4], [5]
Sources
[1] https://learn.microsoft.com/en-us/troubleshoot/entra/entra-id/app-integration/application-delegated-permission-access-tokens-identity-platform
[2] https://learn.microsoft.com/vsts/integrate/get-started/auth/oauth
[3] https://devblogs.microsoft.com/devops/new-azure-devops-scopes-now-available-for-microsoft-identity-oauth-delegated-flow-apps/
[4] https://learn.microsoft.com/en-au/answers/questions/5542159/cant-give-application-permission-to-azure-devops-w
[5] https://devblogs.microsoft.com/devops/introducing-service-principal-and-managed-identity-support-on-azure-devops/
[6] https://learn.microsoft.com/en-us/answers/questions/769153/authenticate-azure-devops-build-rest-api-through-a
[7] https://devblogs.microsoft.com/devops/no-new-azure-devops-oauth-apps/
Add authoritative citations for the OAuth scopes and clarify the permissions model.
The scope descriptions are vague and lack citations. Per documentation requirements, reference Microsoft Learn: OAuth 2.0 authentication for Azure DevOps REST APIs for official scope definitions.
Additionally, the claim "Azure DevOps only allows delegated permissions" oversimplifies the authentication model. Azure DevOps supports delegated OAuth flows (user signs in, app acts on behalf of user) but not classic Entra "application permissions" (client credentials). For automation/non-interactive access, use service principals or managed identities authorized in the Azure DevOps organization, not Entra application permissions.
🤖 Prompt for AI Agents
In `@baton/azure-devops.mdx` around lines 61 - 72, Update the Azure DevOps scopes
section to include an authoritative citation to Microsoft Learn
(https://learn.microsoft.com/vsts/integrate/get-started/auth/oauth) and clarify
the permissions model: state that the listed scopes (user_impersonation,
vso.profile, vso.graph, vso.graph_manage, vso.memberentitlementmanagement_write)
are OAuth delegated scopes per the Microsoft Learn doc, that Azure DevOps does
not support Entra "application permissions" for these REST APIs, and add a short
note advising that for non-interactive automation you must use service
principals or managed identities authorized in the Azure DevOps organization (or
the documented service connection patterns) rather than Entra application
permissions.
paigealleman-sketch
force-pushed
the
docs/azure-devops-minimum-permissions
branch
from
dd4d762 to
8ca2eee
Compare
Update Step 9 in OAuth setup to distinguish between sync-only and provisioning permission requirements, following principle of least privilege. Closes CXH-1082 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
paigealleman-sketch
force-pushed
the
docs/azure-devops-minimum-permissions
branch
from
8ca2eee to
dee58c8
Compare
2 participants
Summary
Clarifies minimum required OAuth permissions for Azure DevOps connector, separating sync-only vs provisioning requirements.
Closes CXH-1082
Changes
Updates Step 9 in "Option 1: Register a web application" to show:
user_impersonation,vso.profile,vso.graphuser_impersonation,vso.profile,vso.graph_manage,vso.memberentitlementmanagement_writeThis allows customers to follow the principle of least privilege by only requesting write permissions when provisioning is needed.
Test plan
🤖 Generated with Claude Code