Microsoft Entra Agent ID Integration

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

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
• Tokens in Microsoft agent identity platform
• Best practices for Microsoft Entra Agent ID

HELM Binding

The commercial adapter lives at:

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:

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

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

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