Configuring Entra ID and Azure DevOps Integration with Boost Security¶

This guide provides detailed instructions for configuring Microsoft Entra ID and Azure DevOps (ADO) to integrate with Boost Security. Boost Security connects to Azure DevOps through Entra ID with either of two methods:

Microsoft Entra ID — you authorize the Boostsecurity.io application in your tenant. No app registration of your own is needed.
App Registration — you create an Entra ID app registration and give Boost Security its credentials.

With the App Registration method, the configuration establishes a secure connection using your Entra ID app registration, service principal, and associated permissions. By following the steps outlined in this guide, you will:

Create and configure an Entra ID application registration.
Assign the required Azure DevOps API permissions.
Generate and manage client secrets.
Connect Azure DevOps to your Entra ID tenant.
Configure Boost Security to integrate with your ADO environment.
Declare the Azure DevOps organizations Boost Security covers.
Enable webhook installation and Zero Touch Provisioning (ZTP).

This process ensures Boost Security can securely interact with your Azure DevOps organization while adhering to best practices for access control and automation.

Prerequisites¶

An Entra ID admin, to create the app registration (App Registration) or to authorize the Boostsecurity.io application in your tenant (Microsoft Entra ID).
An ADO administrator to add the service principal to each ADO organization.
An ADO user with at least project administrator permission to complete the ADO integration in Boost.
Created a non-empty boost repo in the ADO project from which you want to execute the scans.

Entra ID Configuration¶

Note

This section applies to the App Registration method only. With the Microsoft Entra ID method, the Boostsecurity.io application is added to your tenant during the installation.

In the Azure Portal, navigate to Entra ID → Manage → App Registrations , and create a new app registration.
Assign a descriptive name and configure the Web Redirect URL to:
```
https://api.boostsecurity.io/scm-public/msal/callback
```
After creating the registration, open the Overview page and copy the Client ID. You will need this value in later steps.
Configure API permissions:
- Select Add a permission.
- Under Microsoft APIs, choose Azure DevOps API.
- Add the following delegated permissions:
  - vso.code (read)
  - vso.project (read)
  - vso.profile (read)
Generate a client secret:
- Go to Manage → Certificates & Secrets.
- Create a new client secret with a 1-year expiration period.
- Copy and securely store the secret value, as it cannot be retrieved again after you leave the page.

Azure DevOps Configuration¶

In your Azure DevOps organization settings, confirm that the organization is connected to your Entra ID tenant:
```
https://dev.azure.com/{ORGANIZATION}/_settings/organizationAad
```
Add the Entra ID service principal as a user. With the Microsoft Entra ID method, the service principal to add is BoostSecurity.io, and you add it during the installation, once the wizard has added the application to your tenant:
- Go to https://dev.azure.com/{ORGANIZATION}/_settings/users.
- Search for the service principal by name.
- Add the service principal to the Project Contributors group with Basic access level.
- To ensure seamless integration, it is recommended to assign access to all projects.

Boost Security ADO Account Integration¶

In the Boost Security console, navigate to Settings → Integrations → ADO Account Integration , then follow the tab for the method you use.

Microsoft Entra ID

Make sure each Azure DevOps organization you want covered is connected to your Entra ID tenant, as described in step 1 of the Azure DevOps Configuration.

Select the Microsoft Entra ID tab. On the Create OAuth access step, enter an Integration Name and your Tenant ID (available at: Microsoft Entra ID overview), then click Next.
On the Validate Tenant step, add the Boostsecurity.io application to your tenant and prove that you own the tenant:
- Under PART 1: OAuth flow, click Complete the OAuth flow and complete the authorization in the page that opens. To have someone else authorize it, click Copy Link and send them the link. Click Done once the authorization is complete; PART 2 appears after you do.
- Under PART 2: Validate tenant, go to the Microsoft Entra admin center, navigate to Identity → Applications → Enterprise Applications, find the Boostsecurity.io application, and copy its Object ID. Paste it in the Object ID field, then click Next.
On the Declare organizations step:
- In each Azure DevOps organization Boost Security should cover, add the BoostSecurity.io service principal as a user. Go to https://dev.azure.com/{ORGANIZATION}/_settings/users, select Add users, and give BoostSecurity.io the Basic access level and the Project Contributors group. To ensure seamless integration, it is recommended to add it to all projects. For details, see Microsoft's Use service principals & managed identities in Azure DevOps, which the step's Go to the official documentation button also points to.
- Under Azure DevOps organizations, enter one organization name per row — contoso, not https://dev.azure.com/contoso and not contoso/my-project. Click Add Organization to add a row, and the trash button to remove one.
- Click Next. Boost Security validates every organization against the integration's credentials and saves the list in the same action. Each row then shows a green check when the organization is accepted, or a red warning when it is not. Hover the red warning to see the reason.
- If any organization fails, nothing is saved and the wizard stays on this step. Correct or remove the failing rows, then click Next again.
See Declared Organizations for the naming rules, what each validation result means, and how to change the list later.
On the Install Webhooks step, click Install via OAuth2 and approve the authorization request when prompted.

Note

This must be performed by a user with at least project administrator permissions in the ADO project for the webhook installation to succeed.

App Registration

Complete the Entra ID Configuration and the Azure DevOps Configuration first.

Select the App Registration tab.
Provide the following details:
- Integration name
- Client ID from the Entra ID app registration
- Tenant ID (available at: Microsoft Entra ID overview)
- Client Secret generated during the Entra ID configuration
On the Declare Organizations step, list the Azure DevOps organizations Boost Security should cover under Azure DevOps organizations:
- Enter one organization name per row — contoso, not https://dev.azure.com/contoso and not contoso/my-project. Click Add Organization to add a row, and the trash button to remove one.
- Click Next. Boost Security validates every organization against the credentials you provided and saves the list in the same action. Each row then shows a green check when the organization is accepted, or a red warning when it is not. Hover the red warning to see the reason.
- If any organization fails, nothing is saved and the wizard stays on this step. Correct or remove the failing rows, then click Next again.
See Declared Organizations for the naming rules, what each validation result means, and how to change the list later.
Install the webhook:
- Boost Security will request temporary authorization to act on your behalf in ADO.
  
  Note
  
  This must be performed by a user with at least project administrator permissions in the ADO project for the webhook installation to succeed.
- Approve the authorization request when prompted.

Enable Zero Touch Provisioning¶

Once the integration is installed, enable Zero Touch Provisioning (ZTP):

Go to the Integrations page, select your Azure DevOps integration and click on the configuration tab.
On the ZTP column, you will notice that the ZTP status is set to Not Set. Click on the actions menu next to the status and select Enable.
Follow the Wizard steps.

Declared Organizations¶

Both Entra-backed Azure DevOps integrations — Microsoft Entra ID and App Registration — cover the organizations you declare. Boost Security does not discover Azure DevOps organizations for these integrations: the list you enter is exactly what is covered, and it changes only when you change it. Integrations that use a personal access token discover their organizations automatically.

Projects are not declared. Every project inside a declared organization is discovered automatically.

The list is declared during installation, before the webhooks are installed: on the Declare organizations step of the Microsoft Entra ID wizard, or the Declare Organizations step of the App Registration wizard.

Organization Names¶

An entry is a bare Azure DevOps organization name, such as contoso:

It holds only letters, digits and hyphens, and starts with a letter or a digit.
It is at most 50 characters long.
Spaces around a name are trimmed, and names that differ only by capitalization are the same organization.

A list holds at least one and at most 100 organizations.

An entry or a list that breaks these rules is refused with one of the following messages:

Message	What to do
An organization is declared by its name, not by a URL.	Enter the organization name alone, without `https://dev.azure.com/`.
An organization name holds only letters, digits and hyphens, and starts with a letter or a digit.	Correct the name. A project path such as `contoso/my-project` is not an organization name.
An organization name cannot exceed 50 characters.	Correct the name.
At least one organization must be declared.	Add an organization.
At most 100 organizations can be declared.	Remove organizations until the list holds 100 or fewer.

Boost Security saves each organization under the spelling Azure DevOps holds for it, not the one you typed. Entering CONTOSO for an organization Azure DevOps calls Contoso saves Contoso.

Validation¶

Boost Security reads every organization with the integration's own credentials, and accepts it only if at least one project in it is visible to those credentials. An organization that is readable but holds no project is rejected.

Validation and saving are one action: Next in the installation wizard, Save Organizations after installation. If any organization is rejected, nothing is saved. Each row then shows a green check when its organization is accepted, or a red warning when it is rejected:

The reason for each rejected organization appears when you hover its red warning:

Reason	What to do
Organization not found, or not shared with this installation.	Check the spelling, and that the integration's service principal was added to the organization — for Microsoft Entra ID, the BoostSecurity.io service principal.
Organization is readable, but holds no project.	Create a project in the organization or give the service principal access to one, or remove the organization from the list.

The following reasons mean Boost Security could not get an answer from Azure DevOps. Check the integration's credentials, then click Next or Save Organizations again:

Azure DevOps refused to answer for this organization.
Could not reach Azure DevOps for this organization.
Could not read this organization from Azure DevOps.
Could not read this organization's name from Azure DevOps.
Unable to obtain a token for Azure DevOps.

Changing the List¶

In the Boost Security console, go to Settings → Integrations, select the Azure DevOps Account integration, open Integration details, and select the Configuration tab.
Click the chevron at the right end of the Microsoft Entra ID or App Registration row. The organization editor opens under the row, filled with the organizations the integration declares today.
Add, edit or remove organizations, then click Save Organizations.
- When every organization is accepted, the list is saved and a confirmation appears: The declared organization list was saved. The rows then show the list as saved, with the spelling Azure DevOps holds for each name, and a synchronization starts immediately.
- When any organization is rejected, nothing is saved and a warning appears: The organization list was not saved. Check the result shown for each organization. The rows stay as you typed them; hover the red warning on a row to see its reason.

Saving the list is the only way to change what the integration covers. An integration whose synchronization is in error is edited the same way, which is how you remove an organization Boost Security can no longer read.

Warning

Removing an organization from the list detaches its projects. They stop being scanned and updated, and their webhooks are removed. Their existing findings stay visible.

Declaring the organization again brings its projects back as new projects, and the CI/CD data Boost Security had collected for them is rebuilt from scratch rather than restored.

When an Organization Cannot Be Read¶

If a declared organization can no longer be read after it was accepted, for example because its access was revoked, the synchronization fails and the integration reports:

Could not read the following declared Azure DevOps organizations: <names>. If this persists, grant this installation access to them, or remove them from the declared organizations.

Nothing is detached: the whole synchronization stops instead. Restore the access, or remove the organization through Changing the List if you no longer want it covered.

An integration with no declared organization also fails to synchronize, and reports:

No Azure DevOps organization is declared for this installation, declare at least one to synchronize it.

Existing Integrations¶

Azure DevOps integrations installed before organizations became declarative were seeded with the organizations Boost Security already covered for them, and keep working with no action from you. An integration that did not cover any organization yet was seeded with an empty list, and reports the No Azure DevOps organization is declared error until you declare its organizations.

Note

Review the seeded list once. An organization that Boost Security had already stopped covering was not seeded, so the list may be missing organizations you expect. Add them back through Changing the List.