> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oleria.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Azure DevOps

> Connect your Azure DevOps organization so Oleria can discover users, groups, projects, repositories, pipelines, non-human identities, and who can access what.

Connect Azure DevOps to Oleria to see who can reach every project, repository, pipeline, and service connection in your organization, and which non-human identities - personal access tokens, service connections, pipelines, agents, and more - hold that access. Oleria computes effective permissions from Azure DevOps security settings, including inheritance, flags administrators and dormant accounts, and lets you remediate access directly from Oleria.

<Note>One connection covers one Azure DevOps Services organization (`https://dev.azure.com/{organization}`). Connect each organization separately. Azure DevOps Server (on-premises) is not supported.</Note>

## What Oleria discovers

| Area | Detail |
| :- | :- |
| **Users** | Every user entitled in the organization, with access level, status, and last access date. Microsoft Entra users carry their Entra object ID, so they link to the same people in the Microsoft Entra ID integration. |
| **Groups** | Organization and project security groups, including built-in groups such as Project Collection Administrators, Project Administrators, Contributors, and Readers, with nested membership. |
| **Roles** | Access levels (Basic, Stakeholder, and others), resource security roles (Reader, User, and Administrator on variable groups, secure files, service connections, environments, and agent pools), and Artifacts feed roles, with the users and groups that hold each one and what each role allows on its kind of resource. |
| **Resources** | The organization, projects, Git repositories, pipelines, service connections, variable groups, secure files, environments, agent pools, and Artifacts feeds. The person who created a service connection, library item, environment, or agent pool holds the Administrator role Azure DevOps gives the creator, so their access to it is shown as owner-level. |
| **Access** | Effective permissions computed from each security namespace's access control entries, with allow, deny, and inheritance applied. Members of Project Collection Administrators are flagged as administrators. Public projects add an anonymous account with read access. |
| **Non-human identities** | Personal access tokens, SSH keys, service connections, pipelines, secret pipeline and variable-group variables, secure files, self-hosted agents, service hooks, installed extensions, and Entra service principals and managed identities. Each NHI shows its owner or creator and the identity it acts as. Secret values are never read. |
| **Authentication** | MFA status, registered authentication methods, and last password change for Microsoft Entra users, read from Microsoft Graph (Entra service principal connections with the optional Graph permissions below). |
| **Activity** | Audit log events, pipeline runs, and Git pushes. |

## Prerequisites

* Project Collection Administrator access to the Azure DevOps organization.
* For the Microsoft Entra methods: permission to register an app (or grant admin consent) in the Microsoft Entra tenant that backs the organization.

## Choose an authentication method

| Method | Use when |
| :- | :- |
| **Authenticate via Microsoft (OAuth)** (recommended) | Your organization is backed by Microsoft Entra ID and you prefer not to manage a credential. MFA and authentication methods aren't available with this method, because Oleria's app requests no Microsoft Graph permissions. To see them, use Client Secret or Client Certificate Authentication with the Graph permissions below. |
| **Personal access token** | The quickest setup. The token belongs to a Project Collection Administrator. MFA and authentication methods aren't available with this method. |
| **Client Secret Authentication** | Your organization is backed by Microsoft Entra ID and you want to use your own app registration. |
| **Client Certificate Authentication** | As above, authenticating with a certificate instead of a secret. |

## Set up the integration

<Tabs>
  <Tab title="Microsoft OAuth (recommended)">
    <Steps>
      <Step title="Grant consent">
        In the Oleria connection form (see [Connect Azure DevOps to Oleria](#connect-azure-devops-to-oleria)), keep **Authenticate via Microsoft (OAuth)** and select **Authenticate**. Sign in as an administrator of the tenant that backs your organization and grant consent. Note the app name Microsoft shows on the consent screen. Oleria then reports that the organization rejected the token. That's expected, because the app isn't a member of the organization yet.
      </Step>

      <Step title="Add Oleria's service principal to Azure DevOps">
        In Azure DevOps, open **Organization settings** -> **Users** -> **Add users**, search for the app you consented to, add it with **Basic** access, and add it to the **Project Collection Administrators** group. This is Oleria's Azure DevOps app, not the app the Microsoft Entra ID integration uses. Then return to Oleria and select **Authenticate** again.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Personal access token">
    <Steps>
      <Step title="Create the token">
        Sign in to Azure DevOps as a Project Collection Administrator, open **User settings** -> **Personal access tokens**, and select **New Token**. Choose the longest expiry your policy allows, and update the integration in Oleria before the token expires. Choose your organization and choose **Full access**. If your organization restricts full-scoped tokens (the **Restrict full-scoped personal access token creation** policy under **Organization settings** -> **Microsoft Entra**), use the scopes below instead.

        For a least-privilege token instead of **Full access**, Oleria reads with these scopes: `vso.project vso.code vso.graph vso.identity vso.memberentitlementmanagement vso.security_manage vso.build vso.serviceendpoint vso.variablegroups_read vso.securefiles_read vso.environment_manage vso.agentpools vso.hooks vso.extension vso.packaging vso.auditlog vso.tokenadministration`. Remediation actions also need `vso.graph_manage vso.memberentitlementmanagement_write vso.project_manage vso.packaging_manage vso.serviceendpoint_manage vso.build_execute vso.agentpools_manage vso.hooks_write`.

        <Note>When you connect, Oleria checks that the token can read projects, repositories, groups, user entitlements, and permissions. If another area is unreadable, now or later, Oleria skips it, keeps everything else, and marks that sync as partial instead of failing it. Listing personal access tokens requires the token owner to be a Project Collection Administrator.</Note>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Entra service principal">
    <Steps>
      <Step title="Register an app">
        In the Microsoft Entra admin center, register an application in the tenant that backs your Azure DevOps organization. Create a client secret, or upload a certificate. Choose the longest expiry your policy allows, and update the integration in Oleria before it expires. Note the tenant ID and application (client) ID.
      </Step>

      <Step title="Add the service principal to Azure DevOps">
        In Azure DevOps, open **Organization settings** -> **Users** -> **Add users**, add the app's service principal with **Basic** access, and add it to the **Project Collection Administrators** group.

        <Warning>Azure DevOps ignores Entra API permissions for its own data: the service principal must be a member of the organization. A 401 error when you connect almost always means this step was skipped.</Warning>
      </Step>

      <Step title="Grant Microsoft Graph permissions (optional)">
        To see each Entra user's MFA status, authentication methods, and last password change, grant the same app the Microsoft Graph **application** permissions `User.Read.All`, `AuditLog.Read.All`, and `UserAuthenticationMethod.Read.All`, then grant admin consent. Without them, those fields show as unavailable and the sync continues.
      </Step>
    </Steps>
  </Tab>
</Tabs>

### Enable audit logging for activity (optional)

Audit log events are available for organizations backed by Microsoft Entra ID with auditing turned on. In Azure DevOps, open **Organization settings** -> **Policies** and turn on **Log Audit Events**. Azure DevOps keeps audit events for 90 days. Pipeline runs and Git pushes are collected for every organization, with or without the audit log.

## Connect Azure DevOps to Oleria

<Steps>
  <Step title="Open the integration">
    Go to your Oleria workspace, select **Integrations** -> select **Azure DevOps**.
  </Step>

  <Step title="Complete the connection form">
    | Field | Notes |
    | :- | :- |
    | Organization | Required. Your organization name, for example `contoso`, or its URL, `https://dev.azure.com/contoso`. Can't be changed after the integration is created. |
    | Authentication Method | Required. Authenticate via Microsoft (OAuth) (default), Personal access token, Client Secret Authentication, or Client Certificate Authentication. |
    | Personal Access Token | Personal access token method only. |
    | Tenant Id | Client secret and client certificate methods only. |
    | Client Id | Client secret and client certificate methods only. |
    | Client Secret | Client secret method only. |
    | Private Key | Client certificate method only. The certificate and private key in one PEM file, base64-encoded. |
    | I authorize Oleria to perform write actions in Azure DevOps | Optional. Stored with the connection. [Remediation actions](#remediation-actions) currently run with the credential's Azure DevOps permissions whether or not this is selected. |
  </Step>

  <Step title="Authenticate">
    Select **Authenticate**. Oleria checks the credential against your organization before saving it. With admin consent, you are redirected to Microsoft first.
  </Step>
</Steps>

## Verify the integration

Confirm the Azure DevOps instance appears on the **Connected** tab of your Oleria **Integrations** page with a status of **Healthy**. After the first sync completes, you can review users, groups, projects, repositories, pipelines, and non-human identities in your Oleria workspace.

## Remediation actions

Remediation actions need a credential with write access (see the scopes above) whose identity is a Project Collection Administrator.

<Warning>
  Azure DevOps has no disabled state for users or service principals. Disabling a user or a service principal in Oleria removes it from the organization, and that can't be reverted: re-adding it can't restore its project and group memberships.

  Access that comes through a Microsoft Entra group added to the organization isn't removed. Remove the user from that group in Entra ID as well.
</Warning>

| Action | Reversible? |
| :- | :- |
| Disable a user (Azure DevOps has no disabled state, so Oleria removes the user from the organization) | No - re-adding a user can't restore their project and group memberships. Access through a Microsoft Entra group isn't removed. |
| Add user to group | Yes - reversed by removing the user from the group. |
| Remove user from group | Yes - reversed by adding the user back to the group. Access through a Microsoft Entra group isn't removed. |
| Disable a service connection, pipeline, self-hosted agent, or service hook | Yes - reversed by re-enabling it. Secret variables, secure files, installed extensions, and build service identities can't be disabled from Oleria; remove them in Azure DevOps. |
| Add user to an access level | Yes - reversed by restoring the previous access level. Refused when the user already holds a higher level, when the level comes from a Visual Studio subscription or a group rule (change it there), or when the target is a Visual Studio subscription level. |
| Remove user from an access level | Yes - the user moves to Stakeholder; reversed by restoring the previous level. A Stakeholder is already at the lowest level, so Oleria refuses this for them, as it does for a level that comes from a Visual Studio subscription or a group rule. |
| Remove a user or group from a security role or feed role | Yes - their direct assignments of that role are removed and reversed by adding them back. Inherited assignments come from a group and are changed there. |
| Add a user to the organization | Yes - reversed by removing the user. The user joins at Stakeholder, the free access level. If the user is already in the organization, nothing changes, and the action fails if you also chose groups; add them with Add user to group. |
| Create a group | Yes - reversed by deleting the group. An existing group with the same name is reused, and it isn't deleted on revert. |
| Revoke a user's or group's permission on a resource | Yes - their direct permissions on the project, repository, pipeline, service connection, library item, environment, agent pool, or feed are removed and reversed by restoring them exactly. Explicit denies are kept. Access inherited from a group or a parent is changed there. |
| Revoke anonymous access | Yes - the public project is made private, and reversed by making it public again. Run on a repository, it makes the repository's whole project private, including every other repository in it. |
| Remove user from the organization | No - re-adding a user can't restore their project and group memberships. Access through a Microsoft Entra group isn't removed. |
| Disable or remove a service principal (removes it from the organization) | No - for the same reason. |
| Revoke a personal access token, or all of a user's personal access tokens | No - revocation is permanent. SSH keys aren't revoked, and revocation can take up to an hour to take effect. |

Oleria never removes, demotes, or revokes the identity or tokens the integration itself uses, and refuses to remove build service identities (Azure DevOps owns them) or groups from the organization. Microsoft Entra groups are managed in Entra, so membership changes to them are refused. Security and feed roles are granted per resource in Azure DevOps, so Oleria removes them but doesn't add them.

## Known limitations

* **Organization owner.** Azure DevOps doesn't expose the organization owner to a token or service principal. Oleria shows an "Organization Owner (synthesized)" group with full organization permissions and no members, so the owner's access is visible as a path even though the person isn't named.
* **MFA and authentication methods come from Microsoft Entra ID.** Azure DevOps has no MFA setting of its own - Entra Conditional Access enforces it. Oleria reads MFA status, methods, and last password change from Microsoft Graph for client secret and client certificate connections with the optional permissions; OAuth and personal access token connections show them as unavailable. Sign-in events are reported by the Microsoft Entra ID integration.
* **Token and secret last use.** Azure DevOps doesn't record when a personal access token or secret was last used.
* **Audit log availability.** The audit log exists only for Entra-backed organizations with **Log Audit Events** turned on, and keeps 90 days of events.
* **Not yet covered:** classic release pipelines, organization policies, and branch-level permissions.

## Contact us

For questions about this integration, contact us at [support@oleria.com](mailto:support@oleria.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.