> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/application-security/application-security/onboard-data-sources/onboard-version-control-systems/azure-devops/reference-d-azure-devops-onboarding-system-architecture.md). # Reference D: Azure DevOps onboarding system architecture This reference explains the authentication mechanisms, identity models, and multi-tenant data structures Cortex Cloud uses to integrate with Azure DevOps. #### Authentication architecture **Supported methods** * **Microsoft Entra ID (OAuth 2.0):** The recommended standard for Cortex Cloud integrations, using dynamic delegated tokens. Microsoft has announced the deprecation of legacy OAuth methods, making Entra ID the required standard for long-term support * **Personal Access Token (PAT):** A static token model in which authentication is handled by a token generated directly within Azure DevOps. A PAT is cryptographically bound to the specific organization and user account active at the time of creation **Global configuration** * **Ownership:** The Azure application used for OAuth is verified and owned by Cortex Cloud. The Azure application is registered in a fixed Cortex Cloud Microsoft Entra ID tenant that never changes * **Regional specificity:** To ensure regional compliance and performance, each Cortex Cloud region (such as US or EU) uses its own dedicated Azure application registration #### The delegated execution and identity model For the user-identity methods (Microsoft Entra ID user authentication and PAT), Cortex Cloud operates under a delegated access model, distinguishing those methods from the application-identity model used by the Service Principal method. **Secure conduit principles** The Azure application registered by Cortex Cloud serves as the OAuth client and trusted identity, acting solely as a secure conduit to authenticate the user, obtain delegated access tokens, and call Azure DevOps APIs on behalf of that user. **Comparison: Cortex Cloud and GitHub Apps** Unlike GitHub Apps, where the application becomes a first-class principal (an autonomous actor) inside the customer environment, the Cortex Cloud Azure application never operates independently of a user's delegated identity under the OAuth model. **Security and auditability** * **Permissions enforcement:** Under the delegated model, every API call is evaluated using the user's existing permissions. Cortex Cloud cannot exceed or bypass the access rights of the authenticated user. If a user lacks permission for an operation, the request is denied * **Audit trail:** In Azure DevOps audit logs, all activity under the delegated model appears as originating from the individual user's identity, not a Cortex Cloud-owned service account **Multi-tenant and multi-domain logic** Cortex Cloud uses a composite identifier, **\[User Email] + \[Microsoft Entra ID Tenant ID]**, to support complex organizational structures. * **One email, multiple integrations:** A single user identity (email) can own multiple distinct integrations if they target different tenants (such as a Production tenant and a Sandbox tenant) * **Uniqueness constraint:** You cannot create two integrations for the same email on the same tenant * **Organization mapping:** Multiple Azure DevOps organizations can map to a single integration if they reside under the same Entra ID tenant. Organizations in different tenants require separate integration instances * **PAT requirement:** Because a PAT is tied to a specific organization, users must provide a separate PAT for each organization they wish to onboard **Operational comparison: dynamic vs. manual** * **Entra ID (dynamic discovery):** Because OAuth uses a dynamic tenant selection flow, a single authentication session can discover and connect multiple organizations tied to that tenant automatically * **PAT (static, manual onboarding):** A PAT lacks cross-organization visibility; it is strictly limited to the specific organization selected during its creation. Multi-tenant or multi-org onboarding via PAT is a strictly manual process, requiring a unique PAT for every individual organization **Architecture example** The following scenario illustrates how Cortex Cloud maps users, tenants, and organizations. In this example, two Cortex Cloud integrations are created — one per email + tenant combination — even though the same user email is used across all environments. * **User email:** * **Microsoft Entra ID tenants:** Tenant A (company.onmicrosoft.com), Tenant B (subsidiary.onmicrosoft.com) * **Azure DevOps organizations:** Org-1 → Tenant A, Org-2 → Tenant A, Org-3 → Tenant B | Cortex Cloud integration | Email | Entra ID tenant | Azure DevOps organizations | | ------------------------ | ---------------------- | --------------- | -------------------------- | | Integration #1 | | Tenant A | Org-1, Org-2 | | Integration #2 | | Tenant B | Org-3 | **User authorization and session handling** When using the recommended Microsoft Entra ID flow, Cortex Cloud redirects the user to the Microsoft identity platform at `https://login.microsoftonline.com/common/oauth2/v2.0/authorize`. To ensure security and multi-tenant accuracy, the architecture bypasses standard browser session defaults. * **The problem:** Without architectural enforcement, Azure may automatically sign a user into their Home or Last Used directory, leading to token issuance for the wrong tenant * **The mechanism (explicit bypass):** Users are directed to use the **Sign-in options → Sign in to an organization** workflow. By entering a specific Tenant ID or Domain, the user overrides cached browser credentials * **Result:** The authorization token is issued for the intended directory After the explicit tenant selection and successful authentication, Microsoft prompts the user to consent to the requested scopes specifically for that tenant. This consent grant allows Cortex Cloud to act as a delegated agent, performing actions on the user's behalf. **OAuth request internals** Both Entra ID methods request the scope `499b84ac-1321-427f-aa17-267ca6975798/.default`, where `499b84ac-1321-427f-aa17-267ca6975798` is the fixed, Microsoft-assigned resource Application ID of the Azure DevOps first-party application (identical in every tenant) and `/.default` is the reserved Microsoft Entra keyword that requests a token carrying all permissions already consented for the Cortex Cloud application. The Entra ID user flow appends `offline_access` to obtain a refresh token; the Service Principal client-credentials flow omits `offline_access` because that grant does not return a refresh token. **Event subscription (webhooks)** Cortex Cloud subscribes to real-time events (such as `git.push` and `build.complete`) to trigger automated scans. * **Functional dependency:** There is no single webhook permission in Azure DevOps. The ability to create subscriptions derives from standard scopes * **Required scopes:** `vso.code_write` (required for code-related events) and `vso.build` (required for build-related events) IMPORTANT: Without the `vso.code_write` and `vso.build` scopes, the event-driven architecture cannot function, and Cortex Cloud reverts to scheduled (polling) synchronization only. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://cortex-docs.paloaltonetworks.com/application-security/application-security/onboard-data-sources/onboard-version-control-systems/azure-devops/reference-d-azure-devops-onboarding-system-architecture.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.