# Microsoft Entra ID Integration

Connect Microsoft Entra ID to Capsule Security to enrich agents, resources, and activity with directory identities - who a user is, which groups they belong to, and who they report to.

## Overview

This integration connects to the Microsoft Graph API to read your organization's Entra ID directory. It is an **identity provider (IdP) integration**: rather than discovering AI agents or conversations, it supplies the identity layer that other integrations are attributed against. An agent, resource, or session that arrives from another connector carries an email address; Entra ID turns that address into a named person with a job title, a department, a manager, and group memberships.

The integration syncs:

- **Users** - Enabled directory accounts with their profile attributes (display name, user principal name, mail, job title, department, employee type, creation date)
- **Group memberships** - The groups each user belongs to, used for team and ownership attribution
- **Manager** - The email address of each user's manager
- **Agent identities** - Microsoft Entra Agent ID identities, linked to the agents your other integrations discover (optional, see [Agent identities](#agent-identities))


This is an **enrichment** integration. It does not create inventory items of its own; it resolves and annotates the identities behind items your other integrations discover, so it is most valuable alongside platform connectors such as Microsoft 365 Copilot, Claude Code, or GitHub Copilot.

> **This is not SSO.** This integration reads your directory for identity enrichment. To let your users *sign in* to Capsule with their Entra credentials, see [SSO - Microsoft Entra ID](/guides/ms-entra-id-sso-config). The two are independent and can be used together or separately.


## Prerequisites

Before you begin, ensure you have:

- A **Microsoft Entra ID** tenant
- An account with the **Global Administrator** or **Privileged Role Administrator** role, or a custom role that can grant application permissions (to consent for the whole tenant)
> Application Administrator and Cloud Application Administrator are **not** sufficient here. Those roles can consent to most APIs, but Microsoft excludes Microsoft Graph application permissions, which is exactly what this integration requests.
- A **Capsule Security** account with admin access


## Step 1: Configure the Integration in Capsule

1. Log in to the **Capsule Security** portal
2. Click **Integrations** in the left sidebar
3. Find the **Microsoft Entra ID** card and click **Set up Integration**
4. Give the integration a name and confirm
5. The installation card lists the Microsoft Graph permissions Capsule will request. Review them, then click **Connect**
6. You'll be redirected to Microsoft's sign-in page


## Step 2: Grant Admin Consent

Authorize the Capsule application to read your directory.

### Steps

1. Sign in with your Microsoft Entra ID account that has the required administrator role (see Prerequisites)
2. Review the permissions requested by the Capsule application
3. Click **Accept** to grant admin consent for your organization


You'll be returned to Capsule, which verifies the consent by making a live Graph API call before marking the integration as connected.

### Permissions

The Capsule application requires the following **application-level** permissions on the **Microsoft Graph** API. All of them are read-only.

| Permission | Type | Description | Required |
|  --- | --- | --- | --- |
| `User.Read.All` | Application | Read user profiles across the directory | Yes |
| `Directory.Read.All` | Application | Read group membership and manager relationships | Yes |
| `AgentIdentity.Read.All` | Application | Read Entra Agent ID identities and their owners | Optional |
| `AgentIdentityBlueprintPrincipal.Read.All` | Application | Read the blueprint an agent identity was created from | Optional |


The two agent identity permissions are optional. Decline them and user sync still runs; only the agent identity layer is skipped.

Because these are Microsoft Graph application permissions, admin consent must be granted by a Global Administrator or Privileged Role Administrator (or a custom role with permission to grant application permissions). Once granted, the permissions apply tenant-wide.

Capsule requests no write permissions and cannot modify users, groups, or any other directory object.

## Step 3: Automatic Discovery and Sync

After you grant consent, Capsule begins reading the directory. No manual configuration is needed.

### What happens

- Capsule enumerates **enabled** user accounts and their profile attributes, paginating through the directory
- For each user, Capsule reads the groups the user is a member of and the user's manager
- Directory attributes are reconciled against Capsule's unified identities by email address, so activity from your other connected platforms is attributed to the right person and team
- A full directory read runs on a recurring schedule, so joiners, leavers, role changes, and group changes are picked up on the next sync


### Agent identities

If you granted `AgentIdentity.Read.All` and `AgentIdentityBlueprintPrincipal.Read.All`, Capsule also reads the Microsoft Entra Agent ID directory: each agent identity's object ID, display name, account status, tags, creation date, the application that created it, its owners, and the blueprint it was created from.

This part of the sync is optional. Without those permissions, user and group sync runs exactly as described above and agent identities are simply skipped.

Capsule links an agent identity to an agent in your inventory in one of two ways:

- **By object ID.** When the agent's own platform reports the Entra object ID it authenticates as, Capsule matches on that ID. This is an exact match.
- **By display name.** When the platform reports no object ID, Capsule falls back to matching the agent's name against the identity's display name. The portal labels these matches **Inferred by name**, because a display name is not a unique key and two agents can legitimately share one.


A linked identity appears in the portal under **Inventory > agent > Configuration > Identity**. From there, **Open in Entra admin center** takes you to the [Agent ID list](https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/AllAgents.MenuView/~/allAgentIds) in Entra.

### Granting the agent identity permissions on an existing connection

The agent identity permissions were added after this integration first shipped. A tenant that connected before then holds consent for the original two permissions only, and consent is not extended retroactively - you have to grant it again. Either:

- In the Entra admin center, open **Identity > Applications > Enterprise applications**, find the Capsule application, open **Security > Permissions**, and click **Grant admin consent**, or
- Reconnect the integration from **Integrations** in Capsule and accept the updated consent screen


Agent identities appear on the next sync after consent is granted.

## After Setup

Once the integration is configured:

- Initial sync begins automatically. It can take several minutes on large directories, because group membership and manager are read per user.
- Directory identities appear as owner information on agents and resources in **Inventory**
- Job title, department, manager, and group membership become available for attribution and reporting
- Agent identities, when the optional permissions were granted, appear on the **Configuration** tab of the matching agent in **Inventory**


## Troubleshooting

### Common Issues

1. **"Admin consent was denied or the authorization failed."**
  - The consent screen was dismissed, or the signed-in account cannot consent on behalf of the organization
  - Verify the account has **Global Administrator** or **Privileged Role Administrator** and retry from the installation card. An Application Administrator cannot consent to Microsoft Graph application permissions, so consent will fail with that role even though it works for many other apps.
2. **"Connection test failed. Ensure User.Read.All and Directory.Read.All permissions are granted."**
  - Consent completed, but Graph rejected Capsule's first call with a permissions error
  - In the Entra admin center, open **Identity > Applications > Enterprise applications**, find the Capsule application, and confirm both permissions are listed with admin consent granted
  - If consent was granted in a different Entra tenant than the one you intended to connect, remove the enterprise application there and reinstall
3. **"Invalid callback (state mismatch). Please restart the connection from the integrations page."**
  - The callback did not match the pending installation, which happens with a bookmarked or reused callback URL, or when the install was started in a different browser session
  - Start the installation again from **Integrations**
4. **No users appear after installation**
  - Capsule syncs only accounts where **Account enabled** is true; disabled accounts are skipped by design
  - Allow a few minutes for the first pass to finish on a large directory
5. **Group memberships or manager missing for a user**
  - Capsule records direct group memberships only; membership inherited through nested groups is not expanded
  - Groups without a display name, and users with no manager set in Entra, produce no value
  - Confirm the expected values in the Entra admin center under **Identity > Users**, then trigger a re-sync
6. **No identity shown on an agent**
  - The **Identity** section only renders when Capsule has linked an Entra agent identity to that agent, so an agent with no linked identity shows no section at all
  - Confirm `AgentIdentity.Read.All` and `AgentIdentityBlueprintPrincipal.Read.All` are consented; a tenant connected before those permissions existed needs consent granted again
  - Capsule links an identity by Entra object ID, or by display name when the agent's platform reports no object ID. An agent whose name differs from its Entra display name will not match on the fallback - rename one to align them, or wait for the platform to report the object ID
  - Agent identities are read on the same recurring schedule as users, so a newly created identity appears on the next sync rather than immediately
7. **Sync appears slow**
  - Microsoft Graph throttles directory reads. Capsule honors Graph's `Retry-After` responses and backs off rather than hammering the API, so a heavily throttled tenant syncs more slowly.


## Security & Privacy

### Data Access

- **Read-only.** Capsule holds no write permissions and cannot create, modify, or delete directory objects.
- **Directory metadata only.** None of these permissions grant access to mailboxes, files, sites, Teams messages, sign-in logs, Conditional Access policy, or anything an agent identity says or does at runtime. The agent identity permissions read directory registration metadata only - what an agent identity is, not what it did.
- **The permission is broader than what Capsule reads.** `Directory.Read.All` authorizes reading directory objects generally, including applications, service principals, devices, and directory roles. Capsule queries only users, their group memberships, and their managers, but that is a property of Capsule's implementation rather than a restriction enforced by the token. Entra offers no way to narrow an application permission below `Directory.Read.All` for these reads, so evaluate the consent on the full scope it grants.
- **Enabled accounts only.** Disabled accounts are not enumerated.


### Authentication

- Installation uses the OAuth 2.0 authorization code flow to establish tenant-wide admin consent
- Ongoing syncs use app-only **client credentials** tokens scoped to your Entra tenant
- Access tokens are short-lived and minted per sync run. They are never persisted; the only value Capsule stores for this integration is your Entra tenant ID.
- Revoking consent or deleting the Capsule enterprise application in Entra stops Capsule from minting new tokens right away. An access token already issued stays valid until it expires (Microsoft Graph app-only tokens are typically valid for about an hour), so treat revocation as effective within that window rather than instantaneous.


## Support

For help with this integration:

- **Email**: support@capsule.security
- **Include**: Your organization ID, Entra tenant ID, and any error messages from the installation card


## References

- [Grant tenant-wide admin consent to an application](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/grant-admin-consent)
- [Microsoft Graph permissions reference](https://learn.microsoft.com/en-us/graph/permissions-reference)
- [Microsoft Graph throttling guidance](https://learn.microsoft.com/en-us/graph/throttling)
- [SSO - Microsoft Entra ID](/guides/ms-entra-id-sso-config)