Ctrlk
BlogSupport
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Onboard Azure DevOps

Connect Azure DevOps repositories to Cortex Cloud and manage the integration.

Prerequisites

Before initiating the onboarding wizard, ensure your environment meets the following requirements:

Cortex Cloud requirements

  • Permissions: Your user must have Data Sources (View/Edit) permissions (available via AppSec Admin or Instance Administrator roles)

  • Scope: Your Scope-Based Access Control (SBAC) must include the assets created from the repositories

  • Egress Path: You must establish an egress path for outbound data transmission from Cortex Cloud. For more information about configuring egress paths, refer to Egress configurations

Azure DevOps / Microsoft Entra ID requirements

  • Authorization scopes: The Cortex Cloud application requires a defined set of authorization scopes. The same scopes apply to every authentication method; only the grant mechanism differs. With a Personal Access Token, select all scopes manually during token creation. With Microsoft Entra ID (user) and Service Principal, review and consent to the full pre-declared set in a single action. Refer to Subscribed events and permission scopes

  • Service Principal: An Entra ID administrator (Global or Privileged Role Admin) to approve the tenant-wide consent. You must have your Tenant ID (Directory ID) in a valid GUID format, and an Azure DevOps user with Project Collection Administrators access to assign a Basic seat to the Cortex app

  • User Authentication/PAT: The user running the wizard must hold the Project Administrator role to create the event subscriptions during onboarding, and membership in Project Collection Administrators to subscribe to CI build events and download the permissions report

NOTE: To retrieve your Tenant ID: using either of the following methods:

  • Method 1: Via the Microsoft Azure Portal: Log into the Azure Portal, navigate to Microsoft Entra ID, and find your ID on the Overview page

  • Method 2: Log into your Azure DevOps organization, navigate to Organization Settings > Microsoft Entra ID

Onboarding steps

Step 1: Initiate setup in Cortex Cloud

  1. Navigate to Settings → Data Sources & Integrations > Add New.

  2. Search for Azure DevOps, hover over it, and select Add (or Add Another Instance).

Step 2: Authorize connection

  1. Select Microsoft Entra ID authentication, and choose Service Principal as the identity type.

  2. Enter your Tenant ID (Directory ID) (see Prerequisites above) and click Authorize. The wizard redirects you to the Microsoft Permissions requested page for your specified tenant.

  3. An Entra ID administrator must review the requested permission scopes (refer to Subscribed events and permission scopes) and click Accept. Once accepted, Microsoft redirects your browser back to the onboarding wizard, and the page automatically advances to Step 2 — Complete Setup.

  4. Note the Cortex Cloud application display name and Client ID displayed in Step 2 of the wizard.

  5. Add users (Service Principal):

    1. Open Azure DevOps, go to Organization Settings → Users → Add users.

    2. In the Users field, search for and select the Cortex Cloud application. NOTE: You can lookup the application using either the display name or the Client ID GUID displayed in the wizard's Complete Setup step.

    3. Set the Access level to Basic.

    4. Click into the Add to projects field and select the specific project (or projects) containing the repositories you want Cortex Cloud to secure.

    5. Assign the app a Basic access level, add it to your target projects, and click Add. Result: The Cortex Cloud application is now a member of the Azure DevOps organization and has the baseline permissions needed to discover your selected projects.

  6. In Azure DevOps, navigate to Organization Settings > Policies, enable Third-party application access via OAuth.

  7. Return to the Cortex wizard and click Validate Connection. Result: Validation succeeds and the wizard advances to Step 3: Configure repositories. If validation fails for any reason, the wizard displays an error message. To troubleshoot Service Principal connections, refer to Instance-scope troubleshooting.

  1. Select Microsoft Entra ID authentication and click Authorize.

    IMPORTANT: When redirected to the Microsoft login screen, do not immediately enter your email.

  2. Select Sign-in options → Sign in to an organization.

  3. Enter the Domain Name of your target tenant and click Next. This forces Azure to bypass cached browser cookies to ensure token issuance for the correct directory.

  4. Enter your email, review the requested scopes (refer to Subscribed events and permission scopes), and click Accept.

  1. In the Cortex Cloud Onboarding wizard, select Personal access tokens as the authentication method.

  2. In Azure DevOps:

    1. Navigate to User Settings → Personal access tokens → + New Token.

    2. Select All accessible organizations.

    3. Manually grant the required custom-defined scopes (refer to Subscribed events and permission scopes) and click Create.

    4. Copy the personal access token.

  3. In the Cortex onboarding wizard, paste the generated token into the Azure Repos Personal Access Token field and click Authorize. NOTE: A PAT is static and bound to a single organization. To onboard a different tenant, sign in to that specific environment to generate a new token.

Step 3: Configure repositories

After authorization, you are redirected to the Select Repositories step.

  1. Select your repository scope:

    • Permit all existing repositories

    • Permit all existing and future repositories (recommended)

    • Choose from repository list

  2. Click Save.

Verify integration

  1. In Cortex Cloud, navigate to Settings > Data Sources & Integrations and locate Azure DevOps.

  2. Select the resulting Azure DevOps entry.

  3. Locate your instance and verify that the instance status is Connected.

  4. Confirm the Authentication column displays the type of authentication such as PAT or Entra ID.

Manage the integration

Instance-level actions

  1. Navigate to Settings → Data Sources & Integrations and search for Azure DevOps.

  2. Select the matching result.

  3. Locate your instance from the displayed list, right-click it, then select an option:

    • Edit instance: Opens the onboarding wizard, where you can change the instance configuration.

    • Delete instance: Deletes the instance and previous scan data.

    • Copy entire row: Copies all row values to the clipboard.

Repository-level actions

Right-click a connected repository to Set Scanned Branches, run a manual scan through Scan Repository, modify the Scan Configuration, or Remove Repository entirely. You can toggle specific scanners and manage PR behavior in Scan Configuration.

  1. Locate your instance. See Verify integration above.

  2. Select the instance. A list of connected repositories appears.

  3. Right-click a repository, select the required action, then click Save.

PreviousAzure DevOps
NextReference A: Subscribed events and permission scopes

Last updated

Was this helpful?