PluginBench
Skill
Official
Review
Audit score 70

entra-agent-id

microsoft/azure-skills

Provision OAuth 2.0 identities for AI agents with per-instance audit trails via Microsoft Entra and Microsoft Graph.

SourceView on skills.sh

What is entra-agent-id?

Create and manage Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities in Microsoft Entra using Microsoft Graph. Each agent instance receives a distinct identity, independent permission grants, and audit trail. Use this for agent OAuth 2.0 token exchange (fmi_path, OBO, cross-tenant), Workload Identity Federation, and polyglot agent authentication via the Microsoft Entra SDK for AgentID sidecar.

  • Provision Agent Identity Blueprints and BlueprintPrincipals via Microsoft Graph
  • Create per-instance Agent Identities with distinct service principals and audit trails
  • Configure OAuth 2.0 token exchange (fmi_path, OBO, cross-tenant) for agents
  • Grant per-Agent-Identity application and delegated permissions independently
  • Deploy Microsoft Entra SDK for AgentID sidecar for polyglot agents (Python, Node, Go, Java)
  • Diagnose Agent ID errors (AADSTS82001, AADSTS700211, PropertyNotCompatibleWithAgentIdentity)

How to install entra-agent-id

npx skills add https://github.com/microsoft/azure-skills --skill entra-agent-id
Prerequisites
  • Microsoft Entra role: Agent Identity Developer, Agent Identity Administrator, or Application Administrator
  • PowerShell 7+ with Microsoft.Graph.Applications module, or Python 3.7+ with azure-identity and requests
  • Dedicated app registration with client_credentials for programmatic provisioning (DefaultAzureCredential not supported)
  • Access to Microsoft Learn documentation via mcp_azure_mcp_documentation tool
Claude Code
Cursor
Windsurf
Cline

How to use entra-agent-id

  1. 1.Authenticate to Microsoft Graph using delegated scopes (PowerShell) or application credentials (Python) — avoid DefaultAzureCredential
  2. 2.Create an Agent Identity Blueprint with displayName and at least one User sponsor
  3. 3.Create a BlueprintPrincipal for the Blueprint (mandatory; skipping causes 400 errors)
  4. 4.Create per-instance Agent Identities under the Blueprint, specifying agentIdentityBlueprintId and sponsors
  5. 5.Configure credentials on the Blueprint (Managed Identity + WIF for production, client secret for dev)
  6. 6.Implement two-step fmi_path token exchange at agent runtime to acquire per-instance Graph tokens
  7. 7.Grant application or delegated permissions to individual Agent Identities via appRoleAssignments or oauth2PermissionGrants

Use cases

Good for
  • Provisioning a multi-tenant AI agent platform where each agent instance needs isolated credentials and audit trails
  • Setting up federated identity credentials on an Agent Blueprint for production Azure-hosted agents
  • Implementing two-step fmi_path token exchange so agents can acquire per-instance Graph tokens with distinct sub claims
  • Granting role-based permissions to individual agent instances without affecting others
  • Deploying polyglot agents (Python, Node, Go, Java) using the Microsoft Entra SDK for AgentID sidecar container
Who it's for
  • AI agent developers building multi-instance agent platforms
  • Cloud architects designing agent identity and access control
  • DevOps engineers provisioning agent credentials in Azure
  • Polyglot agent teams using languages beyond .NET

entra-agent-id FAQ

Why does creating a Blueprint not auto-create its service principal?

The BlueprintPrincipal must be created explicitly via a separate Microsoft Graph call. Skipping this step produces a 400 error: 'The Agent Blueprint Principal for the Agent Blueprint does not exist.'

Can I use DefaultAzureCredential for Agent Identity provisioning?

No. Azure CLI tokens carry Directory.AccessAsUser.All, which Agent Identity APIs hard-reject with 403. Use a dedicated app registration with client_credentials or Connect-MgGraph with explicit delegated scopes instead.

Who can be a sponsor for an Agent Identity?

Users or Groups can sponsor an Agent Identity. However, only Users can sponsor a Blueprint at creation time; you can add Group sponsors later.

How do agents acquire per-instance tokens at runtime?

Agents use a two-step fmi_path exchange: the Blueprint credential (Managed Identity, client secret, or federated credential) acquires a parent token, then exchanges it for a per-Agent-Identity token with a distinct sub claim and audit trail.

What is the Microsoft Entra SDK for AgentID sidecar?

A polyglot helper (sidecar container) that acquires and caches Agent ID tokens over HTTP for agents written in Python, Node, Go, or Java, eliminating the need for language-specific SDKs.

Full instructions (SKILL.md)

Source of truth, from microsoft/azure-skills.


name: entra-agent-id description: "Provision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmi_path, OBO, cross-tenant) including the Microsoft Entra SDK for AgentID sidecar. USE FOR: Agent Identity Blueprint, BlueprintPrincipal, agent OAuth, fmi_path token exchange, agent OBO, Workload Identity Federation for agents, polyglot agent auth, Microsoft.Identity.Web.AgentIdentities. DO NOT USE FOR: standard Entra app registration (use entra-app-registration), Microsoft Foundry agent authoring (use microsoft-foundry)." license: MIT metadata: author: Microsoft version: "1.1.1"

Microsoft Entra Agent ID

Create and manage OAuth 2.0-capable identities for AI agents using Microsoft Graph. Every agent instance gets a distinct identity, audit trail, and independently-scoped permission grants.

Quick Reference

PropertyValue
ServiceMicrosoft Entra Agent ID
APIMicrosoft Graph (https://graph.microsoft.com/v1.0)
Required roleAgent Identity Developer, Agent Identity Administrator, or Application Administrator
Object modelBlueprint (application) → BlueprintPrincipal (SP) → Agent Identity (SP)
Runtime exchangeTwo-step fmi_path exchange (autonomous and OBO)
.NET helperMicrosoft.Identity.Web.AgentIdentities
Polyglot helperMicrosoft Entra SDK for AgentID (sidecar container)

When to Use This Skill

  • Provisioning a new Agent Identity Blueprint and BlueprintPrincipal
  • Creating per-instance Agent Identities under a Blueprint
  • Configuring credentials (FIC, Managed Identity, or client secret) on the Blueprint
  • Implementing the two-step fmi_path runtime token exchange (autonomous or OBO)
  • Cross-tenant agent token flows
  • Deploying the Microsoft Entra SDK for AgentID sidecar for polyglot agents (Python, Node, Go, Java)
  • Granting per-Agent-Identity application (appRoleAssignments) or delegated (oauth2PermissionGrants) permissions
  • Diagnosing Agent ID errors such as AADSTS82001, AADSTS700211, or PropertyNotCompatibleWithAgentIdentity

MCP Tools

ToolUse
mcp_azure_mcp_documentationSearch Microsoft Learn for current Agent ID setup, Graph API shapes, and SDK configuration

There is no dedicated Agent Identity MCP server today. This skill guides direct Microsoft Graph API calls (PowerShell or Python requests). Use mcp_azure_mcp_documentation to verify request bodies and endpoints against current docs before running.

Before You Start

Use the mcp_azure_mcp_documentation tool to search Microsoft Learn for current Agent ID documentation:

  • "Microsoft Entra Agent ID setup instructions"
  • "Microsoft Entra SDK for AgentID"

Verify request bodies and endpoints against the installed SDK version — Graph API shapes evolve.

Conceptual Model

Agent Identity Blueprint (application)         ← one per agent type/project
  └── BlueprintPrincipal (service principal)    ← MUST be created explicitly
        ├── Agent Identity (SP): agent-1        ← one per agent instance
        ├── Agent Identity (SP): agent-2
        └── Agent Identity (SP): agent-3
ConceptDescription
BlueprintApplication object that defines a type/class of agent. Holds credentials (secret, certificate, federated identity).
BlueprintPrincipalService principal for the Blueprint in the tenant. Not auto-created.
Agent IdentityService-principal-only identity for a single agent instance. Cannot hold its own credentials.
SponsorA User (or Group, for Agent Identity) who is responsible for the identity. Required on creation.

Prerequisites

Required Entra Roles

One of: Agent Identity Developer, Agent Identity Administrator, or Application Administrator.

PowerShell (interactive setup)

# PowerShell 7+
Install-Module Microsoft.Graph.Applications -Scope CurrentUser -Force

Python (programmatic provisioning)

pip install azure-identity requests

Authentication

DefaultAzureCredential is not supported. Azure CLI tokens carry Directory.AccessAsUser.All, which Agent Identity APIs hard-reject (403). Use a dedicated app registration with client_credentials, or Connect-MgGraph with explicit delegated scopes.

PowerShell (delegated)

Connect-MgGraph -Scopes @(
    "AgentIdentityBlueprint.Create",
    "AgentIdentityBlueprint.ReadWrite.All",
    "AgentIdentityBlueprintPrincipal.Create",
    "AgentIdentity.Create.All",
    "User.Read"
)

Python (application)

import os, requests
from azure.identity import ClientSecretCredential

credential = ClientSecretCredential(
    tenant_id=os.environ["AZURE_TENANT_ID"],
    client_id=os.environ["AZURE_CLIENT_ID"],
    client_secret=os.environ["AZURE_CLIENT_SECRET"],
)
token = credential.get_token("https://graph.microsoft.com/.default")

GRAPH = "https://graph.microsoft.com/v1.0"
headers = {
    "Authorization": f"Bearer {token.token}",
    "Content-Type": "application/json",
    "OData-Version": "4.0",
}

Core Workflow

Step 1: Create Agent Identity Blueprint

Use the typed endpoint. Sponsors must be Users at Blueprint creation. This snippet assumes the requests client and headers dict from the Python authentication block above.

import subprocess
import requests

user_id = subprocess.run(
    ["az", "ad", "signed-in-user", "show", "--query", "id", "-o", "tsv"],
    capture_output=True, text=True, check=True,
).stdout.strip()

blueprint_body = {
    "displayName": "My Agent Blueprint",
    "sponsors@odata.bind": [
        f"https://graph.microsoft.com/v1.0/users/{user_id}"
    ],
}
resp = requests.post(
    f"{GRAPH}/applications/microsoft.graph.agentIdentityBlueprint",
    headers=headers, json=blueprint_body,
)
resp.raise_for_status()

blueprint = resp.json()
app_id = blueprint["appId"]
blueprint_obj_id = blueprint["id"]

Step 2: Create BlueprintPrincipal

Mandatory. Creating a Blueprint does NOT auto-create its service principal. Skipping this step produces: 400: The Agent Blueprint Principal for the Agent Blueprint does not exist.

sp_body = {"appId": app_id}
resp = requests.post(
    f"{GRAPH}/servicePrincipals/microsoft.graph.agentIdentityBlueprintPrincipal",
    headers=headers, json=sp_body,
)
resp.raise_for_status()

Make your provisioning scripts idempotent — always check for the BlueprintPrincipal even when the Blueprint already exists.

Step 3: Create Agent Identities

Sponsors for an Agent Identity may be Users or Groups.

agent_body = {
    "displayName": "my-agent-instance-1",
    "agentIdentityBlueprintId": app_id,
    "sponsors@odata.bind": [
        f"https://graph.microsoft.com/v1.0/users/{user_id}"
    ],
}
resp = requests.post(
    f"{GRAPH}/servicePrincipals/microsoft.graph.agentIdentity",
    headers=headers, json=agent_body,
)
resp.raise_for_status()
agent = resp.json()
agent_sp_id = agent["id"]

Runtime Authentication

Agents authenticate at runtime using credentials configured on the Blueprint (not on the Agent Identity — Agent Identities can't hold credentials).

OptionUse caseCredential on Blueprint
Managed Identity + WIFProduction (Azure-hosted)Federated Identity Credential
Client secretLocal dev / testingPassword credential
Microsoft Entra SDK for AgentIDPolyglot / 3P agentsSidecar container acquires tokens over HTTP

For the two-step fmi_path exchange (parent token → per-Agent-Identity Graph token) that gives each agent instance a distinct sub claim and audit trail, see references/runtime-token-exchange.md.

For OBO (agent acting on behalf of a user), see references/obo-blueprint-setup.md.

For the containerized polyglot auth sidecar (Python, Node, Go, Java — no SDK embedding), see references/sdk-sidecar.md.

For MI+WIF and client-secret setup details, see references/oauth2-token-flow.md.

.NET quick path

For .NET services, use Microsoft.Identity.Web.AgentIdentities — it handles Federated Identity Credential management and the two-step exchange for you. See the package README at github.com/AzureAD/microsoft-identity-web under src/Microsoft.Identity.Web.AgentIdentities/.

Granting Permissions (Per Agent Identity)

Agent Identities support both application permissions (autonomous) and delegated permissions (OBO). Grants are scoped per Agent Identity, not to the BlueprintPrincipal.

Application permissions (autonomous)

graph_sp = requests.get(
    f"{GRAPH}/servicePrincipals?$filter=appId eq '00000003-0000-0000-c000-000000000000'",
    headers=headers,
).json()["value"][0]

user_read_all = next(r for r in graph_sp["appRoles"] if r["value"] == "User.Read.All")

requests.post(
    f"{GRAPH}/servicePrincipals/{agent_sp_id}/appRoleAssignments",
    headers=headers,
    json={
        "principalId": agent_sp_id,
        "resourceId": graph_sp["id"],
        "appRoleId": user_read_all["id"],
    },
).raise_for_status()

Delegated permissions (OBO)

from datetime import datetime, timedelta, timezone

expiry = (datetime.now(timezone.utc) + timedelta(days=3650)).strftime("%Y-%m-%dT%H:%M:%SZ")

requests.post(
    f"{GRAPH}/oauth2PermissionGrants",
    headers=headers,
    json={
        "clientId": agent_sp_id,
        "consentType": "AllPrincipals",
        "resourceId": graph_sp["id"],
        "scope": "User.Read Tasks.ReadWrite Mail.Send",
        "expiryTime": expiry,
    },
).raise_for_status()

Browser-based admin consent URLs do not work for Agent Identities — use oauth2PermissionGrants for programmatic delegated consent.

Cross-Tenant Agent Identities

Blueprints can be multi-tenant (signInAudience: AzureADMultipleOrgs). When exchanging tokens cross-tenant:

Step 1 of the parent token exchange MUST target the Agent Identity's home tenant, not the Blueprint's. Wrong tenant → AADSTS700211: No matching federated identity record found.

See references/runtime-token-exchange.md for full cross-tenant examples.

API Reference

OperationMethodEndpoint
Create BlueprintPOST/applications/microsoft.graph.agentIdentityBlueprint
Create BlueprintPrincipalPOST/servicePrincipals/microsoft.graph.agentIdentityBlueprintPrincipal
Create Agent IdentityPOST/servicePrincipals/microsoft.graph.agentIdentity
Add FIC to BlueprintPOST/applications/{id}/microsoft.graph.agentIdentityBlueprint/federatedIdentityCredentials
List Agent IdentitiesGET/servicePrincipals/microsoft.graph.agentIdentity
Grant app permissionPOST/servicePrincipals/{id}/appRoleAssignments
Grant delegated permissionPOST/oauth2PermissionGrants
Delete Agent IdentityDELETE/servicePrincipals/{id}
Delete BlueprintDELETE/applications/{id}

Base URL: https://graph.microsoft.com/v1.0.

Required Graph Permissions

PermissionPurpose
AgentIdentityBlueprint.CreateCreate Blueprints
AgentIdentityBlueprint.ReadWrite.AllRead/update Blueprints
AgentIdentityBlueprintPrincipal.CreateCreate BlueprintPrincipals
AgentIdentity.Create.AllCreate Agent Identities
AgentIdentity.ReadWrite.AllRead/update Agent Identities
Application.ReadWrite.AllBlueprint CRUD on application objects
AppRoleAssignment.ReadWrite.AllGrant application permissions
DelegatedPermissionGrant.ReadWrite.AllGrant delegated permissions

Grant admin consent (required for application permissions):

az ad app permission admin-consent --id <client-id>

After admin consent, tokens may not include new claims for 30–120 seconds — retry with exponential backoff.

Best Practices

  1. Always create BlueprintPrincipal after Blueprint — not auto-created.
  2. Use typed endpoints (/applications/microsoft.graph.agentIdentityBlueprint) instead of raw /applications with @odata.type.
  3. Credentials live on the Blueprint — Agent Identities can't hold secrets/certs (PropertyNotCompatibleWithAgentIdentity).
  4. Include OData-Version: 4.0 on every Graph request.
  5. Use Workload Identity Federation for production — client secrets only for local dev.
  6. Set identifierUris: ["api://{appId}"] on the Blueprint before OAuth2 scope resolution.
  7. Never use Azure CLI tokens for Agent Identity APIs — Directory.AccessAsUser.All causes hard 403.
  8. Use fmi_path with client_credentials — NOT RFC 8693 urn:ietf:params:oauth:grant-type:token-exchange (returns AADSTS82001).
  9. Always use /.default scope in both steps of the exchange — individual scopes fail.
  10. Step 1 targets the Agent Identity's home tenant in cross-tenant flows.
  11. Grant permissions per Agent Identity, not to the BlueprintPrincipal.
  12. Handle permission-propagation delays — retry 403s with 30–120s backoff after admin consent.
  13. Keep the Entra SDK for AgentID on localhost — never expose via LoadBalancer or Ingress.

Troubleshooting

ErrorCauseFix
AADSTS82001Used RFC 8693 token-exchange grantUse client_credentials with fmi_path
AADSTS700211Step 1 parent token targeted wrong tenantTarget Agent Identity's home tenant
AADSTS50013OBO user token targets Graph, not BlueprintUse api://{blueprint_app_id}/access_as_user
AADSTS65001Missing grant or used individual scopesUse /.default and verify oauth2PermissionGrants
403 Authorization_RequestDeniedNo grant on this Agent IdentityAdd via appRoleAssignments or oauth2PermissionGrants
PropertyNotCompatibleWithAgentIdentityTried to add credential to Agent Identity SPPut credentials on the Blueprint
Agent Blueprint Principal does not existBlueprintPrincipal not createdStep 2 of the Core Workflow
AADSTS650051 on admin consentSP already exists from partial consentGrant directly via appRoleAssignments

References

FileContents
references/runtime-token-exchange.mdTwo-step fmi_path exchange: autonomous + OBO, cross-tenant
references/oauth2-token-flow.mdMI + WIF (production) and client secret (local dev)
references/obo-blueprint-setup.mdConfiguring the Blueprint as an OAuth2 API for OBO
references/sdk-sidecar.mdMicrosoft Entra SDK for AgentID — architecture, configuration, endpoints
references/sdk-sidecar-deployment.mdSDK code patterns (Python/TypeScript), Docker/Kubernetes manifests, security, troubleshooting
references/known-limitations.mdDocumented gaps organized by category

External Links

ResourceURL
Agent ID Setup Guidehttps://learn.microsoft.com/en-us/entra/agent-id/identity-platform/agent-id-setup-instructions
AI-Guided Setuphttps://learn.microsoft.com/en-us/entra/agent-id/identity-platform/agent-id-ai-guided-setup
Microsoft Entra SDK for AgentIDhttps://learn.microsoft.com/en-us/entra/msidweb/agent-id-sdk/overview
Microsoft.Identity.Web.AgentIdentities (.NET)https://github.com/AzureAD/microsoft-identity-web/blob/master/src/Microsoft.Identity.Web.AgentIdentities/README.AgentIdentities.md