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

# Microsoft Entra Workload Identity

> Connect CodeAnt AI to Azure DevOps without a personal access token or client secret.

# Microsoft Entra workload identity for Azure DevOps

If you want a truly secretless alternative to personal access tokens (PATs), use Microsoft Entra workload identity federation. It removes long-lived credentials from the integration, so there is no PAT or client secret to create, store, rotate, or revoke when an employee leaves.

During setup:

1. You provide the UUID of the Microsoft Entra tenant connected to your Azure DevOps organization.
2. A tenant administrator grants consent to the **CodeAnt Azure DevOps Integration** application.
3. Microsoft Entra creates a service principal for CodeAnt in your tenant automatically.
4. An Azure DevOps administrator adds that service principal to the required projects.
5. CodeAnt validates the access before saving the organization.

<Info>
  You do **not** create a separate app registration, client secret, certificate, Azure DevOps service connection, or bot user for this flow. CodeAnt uses its existing multi-tenant application and exchanges its workload identity for short-lived Microsoft Entra access tokens.
</Info>

## Prerequisites

Before you begin, make sure you have:

* An Azure DevOps Services organization, such as `https://dev.azure.com/my-organization`. This flow does not support self-hosted Azure DevOps Server.
* CodeAnt administrator access to **Settings → Add AD org**.
* A Microsoft Entra administrator who can grant tenant-wide admin consent. Depending on the permissions shown in the consent screen, this is typically a **Cloud Application Administrator**, **Application Administrator**, **Privileged Role Administrator**, or an equivalent custom role.
* An Azure DevOps **Organization Owner** or **Project Collection Administrator** who can add organization users and assign project access.
* The names of the Azure DevOps projects that CodeAnt should access.

The Microsoft Entra administrator and Azure DevOps administrator can be different people.

## Step 1: Find the tenant UUID

The UUID requested by CodeAnt is your Microsoft Entra **Directory (tenant) ID**. It has this format:

```text theme={"system"}
00000000-0000-0000-0000-000000000000
```

### From the Azure portal

1. Sign in to the [Azure portal](https://portal.azure.com).
2. Open **Microsoft Entra ID**.
3. Select **Properties**.
4. Copy the value labeled **Tenant ID**.

You can also find it in the [Microsoft Entra admin center](https://entra.microsoft.com) under **Entra ID → Overview → Properties → Tenant ID**.

### From Azure CLI

```bash theme={"system"}
az login
az account tenant list --output table
```

Copy the `tenantId` for the directory connected to your Azure DevOps organization.

<Warning>
  Do not enter an Azure subscription ID, application/client ID, service-principal object ID, or Azure DevOps organization ID. CodeAnt requires the **Directory (tenant) ID**.
</Warning>

## Step 2: Start the connection in CodeAnt

1. Sign in to [CodeAnt AI](https://app.codeant.ai).
2. Open **Settings → Add AD org**.
3. Select **Add AD org**.
4. Enter the following values:

| Field                         | Value                                              |
| ----------------------------- | -------------------------------------------------- |
| **Base URL**                  | `https://dev.azure.com`                            |
| **Organization name**         | The name in `https://dev.azure.com/<organization>` |
| **Authentication**            | **Microsoft Entra**                                |
| **Microsoft Entra tenant ID** | The UUID copied in Step 1                          |

5. Select **Grant admin consent**.

CodeAnt redirects the administrator to Microsoft. Confirm that the tenant shown by Microsoft is the tenant entered in CodeAnt, review the requested permissions, and accept the consent prompt.

After consent, Microsoft redirects you to CodeAnt and reopens the organization setup. Keep this page open while completing the Azure DevOps access step.

<Note>
  If the consent prompt says that administrator approval is required, send the setup to one of the Microsoft Entra administrators listed in the prerequisites. A regular Azure DevOps administrator might not have permission to grant tenant consent.
</Note>

## Step 3: Verify the service principal in Microsoft Entra

Granting consent creates the customer-tenant service principal automatically. Microsoft calls this local service-principal instance an **Enterprise application**.

To verify it:

1. Open the [Microsoft Entra admin center](https://entra.microsoft.com).
2. Go to **Entra ID → Enterprise apps → All applications**.
3. Search for **CodeAnt Azure DevOps Integration**.
4. Open the application and confirm that it is in the tenant from Step 1.

You can copy the enterprise application's **Object ID** as a fallback for the Azure DevOps user search in the next step.

<Warning>
  Do not create another application under **App registrations**, and do not add a client secret or certificate. A duplicate application will not be the identity that CodeAnt uses.
</Warning>

## Step 4: Add the service principal to Azure DevOps

Admin consent lets Microsoft Entra issue tokens, but it does not grant access to an Azure DevOps organization. The service principal must also be added as an Azure DevOps user.

1. Open your Azure DevOps organization:

   ```text theme={"system"}
   https://dev.azure.com/<organization>
   ```

2. Select **Organization settings → Users**.

3. Select **Add users**.

4. Search for **CodeAnt Azure DevOps Integration**. If the name is not found, paste the enterprise application's **Object ID** from Step 3.

5. Configure the user:

| Setting                | Recommended value                                |
| ---------------------- | ------------------------------------------------ |
| **Access level**       | **Basic**                                        |
| **Add to projects**    | Only the projects CodeAnt should scan and review |
| **Azure DevOps group** | **Project Readers** for each selected project    |

6. Select **Add**.

Repeat this step in every Azure DevOps organization that CodeAnt needs to access.

### Repository permissions

The project **Readers** group is the recommended least-privilege starting point. It can read repository contents and participate in pull requests, including creating comments.

If your organization overrides the built-in group permissions, open **Project settings → Repositories → Security**, select **CodeAnt Azure DevOps Integration**, and confirm that these permissions are not denied:

* **Read**
* **Contribute to pull requests**

Use **Project Contributors** only if you deliberately want CodeAnt to create branches, push code, or perform another write operation beyond pull-request review. CodeAnt does not require repository-administrator, policy-bypass, force-push, or project-administrator permissions for standard scans and reviews.

<Note>
  Microsoft Entra and Azure DevOps identity changes can take a few minutes to propagate. If the service principal is not searchable immediately, wait briefly, refresh the page, and try its Object ID.
</Note>

## Step 5: Validate and save in CodeAnt

Return to the open CodeAnt dialog and select **Validate access & Add**.

CodeAnt requests a short-lived Microsoft Entra token and checks that the service principal can access at least one project in the Azure DevOps organization. The organization is saved only after this validation succeeds.

<Info>
  No PAT or customer-managed client secret is saved. CodeAnt stores the tenant association needed to request short-lived access tokens for this organization.
</Info>

If CodeAnt says that it does not have Azure DevOps project access, verify all of the following before retrying:

* The tenant ID belongs to the directory connected to the Azure DevOps organization.
* **CodeAnt Azure DevOps Integration** exists under **Enterprise applications** in that tenant.
* The same service principal is present in **Organization settings → Users**.
* Its access level is **Basic**.
* It has access to at least one selected project and repository.
* No inherited or explicit **Deny** overrides its repository permissions.

## Step 6: Verify the integration end to end

1. In CodeAnt, confirm that the Azure DevOps organization shows **Configured**.
2. Start a scan for a repository in one of the selected projects.
3. Create a new pull request in that repository.
4. Confirm that CodeAnt posts its status and review comments.
5. Confirm that new automated activity is attributed to **CodeAnt Azure DevOps Integration**, not to a person's Azure DevOps account.

Test with a new pull request after changing authentication. Comments already created with an older PAT keep the original person's identity in their audit history.

## Change an existing organization from PAT to Microsoft Entra

1. In CodeAnt, open **Settings → Add AD org**.
2. Find the existing organization and select **Update credentials**.
3. Select **Microsoft Entra**.
4. Enter the tenant ID and select **Grant admin consent**.
5. Complete Steps 3 and 4 above if the service principal is not already configured.
6. Return to CodeAnt and select **Validate access & Update**.

The existing PAT remains active for that CodeAnt organization until the Microsoft Entra validation succeeds and the update is saved.

## Remove the integration

To revoke access completely:

1. Remove **CodeAnt Azure DevOps Integration** from **Azure DevOps → Organization settings → Users** in every connected organization.
2. Remove or replace the organization credentials in CodeAnt.
3. If no CodeAnt Azure DevOps organization in the tenant uses the integration, remove the enterprise application or revoke its consent in **Microsoft Entra ID → Enterprise apps**.

Removing only the enterprise application stops new token issuance, while removing only the Azure DevOps user stops the identity from accessing that Azure DevOps organization.

## Troubleshooting

<AccordionGroup>
  <Accordion title="I cannot find the tenant UUID">
    In the Azure portal, open **Microsoft Entra ID → Properties** and copy **Tenant ID**. Do not copy the subscription ID shown on a subscription page. See [Microsoft's tenant ID guide](https://learn.microsoft.com/en-us/entra/fundamentals/how-to-find-tenant) for portal, PowerShell, and CLI options.
  </Accordion>

  <Accordion title="The service principal does not appear in Azure DevOps">
    First confirm that **CodeAnt Azure DevOps Integration** exists under **Microsoft Entra ID → Enterprise apps**. Then search for its Object ID in **Azure DevOps → Organization settings → Users → Add users**. Confirm that Azure DevOps is connected to the same tenant and allow time for identity propagation.
  </Accordion>

  <Accordion title="Admin consent succeeded, but validation fails">
    Consent and Azure DevOps authorization are separate. Add the service principal to the Azure DevOps organization with **Basic** access, select at least one project, and grant repository **Read** and **Contribute to pull requests** access. Then retry validation.
  </Accordion>

  <Accordion title="Microsoft returns a tenant mismatch error">
    The Microsoft account used for consent selected a different directory. Switch directories in the Microsoft sign-in flow, or restart setup with the Directory (tenant) ID that backs the Azure DevOps organization.
  </Accordion>

  <Accordion title="Review comments still show a person's name">
    Existing comments keep their original author. Create a new pull request after **Validate access & Update** succeeds. New CodeAnt activity should be attributed to **CodeAnt Azure DevOps Integration**. If it is not, confirm that you updated the intended Azure DevOps organization in CodeAnt.
  </Accordion>
</AccordionGroup>

## Microsoft references

* [Find your Microsoft Entra tenant ID](https://learn.microsoft.com/en-us/entra/fundamentals/how-to-find-tenant)
* [Grant tenant-wide admin consent](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/grant-admin-consent)
* [Add a service principal to Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/pipelines/library/add-devops-entra-service-connection?view=azure-devops#add-the-service-principal-to-your-organization)
* [Set Azure Repos Git permissions](https://learn.microsoft.com/en-us/azure/devops/repos/git/set-git-repository-permissions?view=azure-devops)