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: [e-mail]
• 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	[e-mail]	Tenant A	Org-1, Org-2
Integration #2	[e-mail]	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.