---
title: "Microsoft Entra Agent ID Integration"
canonical: "https://helm.docs.mindburn.org/integrations/entra-agent-id"
source: "helm-ai-enterprise/docs/public/product/integrations/entra-agent-id.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/product/integrations/entra-agent-id.md"
section: "reference"
access: "public"
sensitivity: "public"
last_reviewed: "2026-04-29"
checksum_sha256: "sha256:32d8cfd1876c443138cdbdefed9c4a1d7a63be73524221422efac2a044f6b7ea"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Integration: Microsoft Entra Agent ID

## Audience

## Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

## Source Truth

- Public route: `integrations/entra-agent-id`
- Source document: `helm-ai-enterprise/docs/public/product/integrations/entra-agent-id.md`
- Public manifest: `helm-ai-enterprise/docs/public-docs.manifest.json`
- Source inventory: `helm-ai-enterprise/docs/source-inventory.manifest.json`
- Validation: `corepack pnpm run docs:coverage`, `corepack pnpm run docs:truth`, and `npm run coverage:inventory` from `docs-platform`

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A link or route is missing from the docs website | Check `docs/public-docs.manifest.json`, `llms.txt`, search, and the per-page Markdown export before changing navigation. |
| A claim is not backed by code or tests | Remove the claim or add the missing code, example, schema, or validation command before publishing. |

HELM AI Enterprise can use Microsoft Entra Agent ID as an upstream identity provider for governed agent execution. The connector maps validated Entra agent token claims into HELM AI Enterprise principals and signed guardian decision context before an MCP or A2A side effect is permitted.

## Current Microsoft Surface

Microsoft Entra Agent ID is currently preview. Microsoft describes agent identities as service-principal-backed identities created from blueprints, without credentials on the agent identity itself. Resource servers that receive agent tokens are expected to validate OAuth claims, check agent facet claims, enforce permissions, and keep tenant boundaries intact.

Sources:

- [Agent identities in Microsoft Entra Agent ID](https://learn.microsoft.com/en-us/entra/agent-id/agent-identities)
- [Tokens in Microsoft agent identity platform](https://learn.microsoft.com/en-us/entra/agent-id/agent-tokens)
- [Best practices for Microsoft Entra Agent ID](https://learn.microsoft.com/en-us/entra/agent-id/best-practices-agent-id)

## HELM Binding

The commercial adapter lives at:

```text
commercial/integrations/entraagent
```

It accepts claims after JWT signature verification by the caller, then enforces:

- expected Entra tenant (`tid`)
- expected issuer and API audience
- token expiry
- agent identity presence from `xms_act_fct`, `azp`, `appid`, or agent-specific claim aliases
- optional blueprint and agent allowlists
- fail-closed rejection for high-privilege Microsoft Graph permissions such as `Directory.ReadWrite.All` and `RoleManagement.ReadWrite.Directory`

The normalized identity becomes:

- a commercial RBAC principal with provider `microsoft_entra_agent_id`
- a guardian subject such as `entra-agent:<tenant>:<agent>`
- signed decision context fields including `entra_agent_id`, `entra_agent_blueprint_id`, `entra_identity_type`, and `entra_agent_user_object_id` when delegated user context is present

The downstream `EffectPermit` remains the core kernel artifact. Entra identity is bound through the signed guardian verdict and decision context that the permit references.

## Console Connector Option

The enterprise connector catalog exposes:

```go
connectors.MicrosoftEntraAgentIDDefinition()
```

The definition is commercial-only and declares the `microsoft_entra_agent_id` family with required config for tenant ID, issuer, and allowed audiences. It is intentionally separate from `helm-ai-kernel` and protected core paths.

## Minimal Flow

1. Entra issues an agent token to the HELM resource audience.
2. The HELM edge verifies JWT signature and standard OAuth validity.
3. `entraagent.Validate` maps and validates claims against tenant policy.
4. HELM evaluates guardian policy with the returned subject and decision context.
5. If guardian allows the side effect, HELM issues the normal signed permit and receipt chain.

## Failure Behavior

The connector fails closed for missing claims, wrong tenant, wrong audience, wrong issuer, expired token, missing agent identity, untrusted blueprint, or blocked high-privilege permission.

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        token["Entra agent token"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        validate["Validate OAuth claims"]
        normalize["Normalize HELM principal"]
        guardian["Guardian decision"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        permit["Effect permit"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        receipt["Signed receipt context"]
    end

    %% Operational Flow Edges
    token --> validate
    validate --> normalize
    normalize --> guardian
    guardian --> permit
    permit --> receipt

    %% Premium Styling Rules
    style validate fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style normalize fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style guardian fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style permit fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style receipt fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```