entra-agent-id

microsoft/azure-skillsSecurityReview advisedSnapshot 823df001f0e7

Summary

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), Azure RBAC (use azure-rbac), Microsoft Foundry agent authoring (use microsoft-foundry).

SKILL.md

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

Property	Value
Service	Microsoft Entra Agent ID
API	Microsoft Graph (`https://graph.microsoft.com/v1.0`)
Required role	Agent Identity Developer, Agent Identity Administrator, or Application Administrator
Object model	Blueprint (application) → BlueprintPrincipal (SP) → Agent Identity (SP)
Runtime exchange	Two-step `fmi_path` exchange (autonomous and OBO)
.NET helper	`Microsoft.Identity.Web.AgentIdentities`
Polyglot helper	Microsoft 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)

Tool	Use
`mcp_azure_mcp_documentation`	Search Microsoft Learn for current Agent ID setup, Graph API shapes, and SDK configuration

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

Concept	Description
Blueprint	Application object that defines a type/class of agent. Holds credentials (secret, certificate, federated identity).
BlueprintPrincipal	Service principal for the Blueprint in the tenant. Not auto-created.
Agent Identity	Service-principal-only identity for a single agent instance. Cannot hold its own credentials.
Sponsor	A User (or Group, for Agent Identity) who is responsible for the identity. Required on creation.

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

pip install azure-identity requests

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

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",
}

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",
    "[email protected]": [
        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"]

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

agent_body = {
    "displayName": "my-agent-instance-1",
    "agentIdentityBlueprintId": app_id,
    "[email protected]": [
        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"]

Option	Use case	Credential on Blueprint
Managed Identity + WIF	Production (Azure-hosted)	Federated Identity Credential
Client secret	Local dev / testing	Password credential
Microsoft Entra SDK for AgentID	Polyglot / 3P agents	Sidecar container acquires tokens over HTTP

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()

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()

Operation	Method	Endpoint
Create Blueprint	`POST`	`/applications/microsoft.graph.agentIdentityBlueprint`
Create BlueprintPrincipal	`POST`	`/servicePrincipals/microsoft.graph.agentIdentityBlueprintPrincipal`
Create Agent Identity	`POST`	`/servicePrincipals/microsoft.graph.agentIdentity`
Add FIC to Blueprint	`POST`	`/applications/{id}/microsoft.graph.agentIdentityBlueprint/federatedIdentityCredentials`
List Agent Identities	`GET`	`/servicePrincipals/microsoft.graph.agentIdentity`
Grant app permission	`POST`	`/servicePrincipals/{id}/appRoleAssignments`
Grant delegated permission	`POST`	`/oauth2PermissionGrants`
Delete Agent Identity	`DELETE`	`/servicePrincipals/{id}`
Delete Blueprint	`DELETE`	`/applications/{id}`

Permission	Purpose
`AgentIdentityBlueprint.Create`	Create Blueprints
`AgentIdentityBlueprint.ReadWrite.All`	Read/update Blueprints
`AgentIdentityBlueprintPrincipal.Create`	Create BlueprintPrincipals
`AgentIdentity.Create.All`	Create Agent Identities
`AgentIdentity.ReadWrite.All`	Read/update Agent Identities
`Application.ReadWrite.All`	Blueprint CRUD on application objects
`AppRoleAssignment.ReadWrite.All`	Grant application permissions
`DelegatedPermissionGrant.ReadWrite.All`	Grant delegated permissions

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

Error	Cause	Fix
`AADSTS82001`	Used RFC 8693 token-exchange grant	Use `client_credentials` with `fmi_path`
`AADSTS700211`	Step 1 parent token targeted wrong tenant	Target Agent Identity's home tenant
`AADSTS50013`	OBO user token targets Graph, not Blueprint	Use `api://{blueprint_app_id}/access_as_user`
`AADSTS65001`	Missing grant or used individual scopes	Use `/.default` and verify `oauth2PermissionGrants`
`403 Authorization_RequestDenied`	No grant on this Agent Identity	Add via `appRoleAssignments` or `oauth2PermissionGrants`
`PropertyNotCompatibleWithAgentIdentity`	Tried to add credential to Agent Identity SP	Put credentials on the Blueprint
`Agent Blueprint Principal does not exist`	BlueprintPrincipal not created	Step 2 of the Core Workflow
`AADSTS650051` on admin consent	SP already exists from partial consent	Grant directly via `appRoleAssignments`

File	Contents
references/runtime-token-exchange.md	Two-step `fmi_path` exchange: autonomous + OBO, cross-tenant
references/oauth2-token-flow.md	MI + WIF (production) and client secret (local dev)
references/obo-blueprint-setup.md	Configuring the Blueprint as an OAuth2 API for OBO
references/sdk-sidecar.md	Microsoft Entra SDK for AgentID — architecture, configuration, endpoints
references/sdk-sidecar-deployment.md	SDK code patterns (Python/TypeScript), Docker/Kubernetes manifests, security, troubleshooting
references/known-limitations.md	Documented gaps organized by category

Resource	URL
Agent ID Setup Guide	https://learn.microsoft.com/en-us/entra/agent-id/identity-platform/agent-id-setup-instructions
AI-Guided Setup	https://learn.microsoft.com/en-us/entra/agent-id/identity-platform/agent-id-ai-guided-setup
Microsoft Entra SDK for AgentID	https://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

entra-agent-id

Summary

SKILL.md

Microsoft Entra Agent ID

Quick Reference

When to Use This Skill

MCP Tools

Before You Start

Conceptual Model

Prerequisites

Required Entra Roles

PowerShell (interactive setup)

Python (programmatic provisioning)

Authentication

PowerShell (delegated)

Python (application)

Core Workflow

Step 1: Create Agent Identity Blueprint

Step 2: Create BlueprintPrincipal

Step 3: Create Agent Identities

Runtime Authentication

.NET quick path

Granting Permissions (Per Agent Identity)

Application permissions (autonomous)

Delegated permissions (OBO)

Cross-Tenant Agent Identities

API Reference

Required Graph Permissions

Best Practices

Troubleshooting

References

External Links

Related skills