MCPInstall

entra-agent-id

Provision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmipath, OBO, cross-tenant) including the Microsoft Entra SDK for AgentID sidecar. USE FOR: Agent Identity Blueprint, BlueprintPrincipal, agent OAuth, fmipath 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).

Installs
336.6K
Last 24h
+1.4K
Trending rank
#215
Security
Warn

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/microsoft/azure-skills --skill entra-agent-id
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads entra-agent-id automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

Security audits

Independent scans of the skill's instructions and bundled files.

Gen Agent Trust Hub PassSAFE ·This skill provides detailed instructions for provisioning and managing Microsoft Entra Agent Identities. It incorporates standard identity management practices, including the use of OAuth 2.0 flows and the Microsoft Entra SDK. All external references and tools are integrated with trusted Microsoft services and repositories.
Socket Warn1 alert: gptAnomaly
Snyk PassLOW ·Risk: LOW · No issues

SKILL.md

The instructions your agent reads when the skill is triggered.

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

FAQ

What does the entra-agent-id skill do?

Provision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmipath, OBO, cross-tenant) including the Microsoft Entra SDK for AgentID sidecar. USE FOR: Agent Identity Blueprint, BlueprintPrincipal, agent OAuth, fmipath 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).

How do I install entra-agent-id?

Run npx skills add https://github.com/microsoft/azure-skills --skill entra-agent-id in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/entra-agent-id/ (personal) or .claude/skills/entra-agent-id/ (project).

Which AI agents can use entra-agent-id?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is entra-agent-id safe to install?

Security partners have reviewed it: Gen Agent Trust Hub passed; Socket flagged items to review; Snyk passed. As with any skill, read the SKILL.md and bundled scripts before installing.

Who maintains entra-agent-id?

It is published by microsoft in microsoft/azure-skills, and it is an official skill from the maker of the technology it covers. It has 336,561 recorded installs.

More from microsoft/azure-skills

View all →

microsoft-foundry

microsoft/azure-skills

Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and resources end to end. USE FOR: foundry, azd ai agent, azd provision/deploy, hosted agent scaffold/develop/run/deploy/troubleshoot, prompt agent create, managed harness agent create, GitHub Copilot harness agent, create agent, update agent, add tool to agent, invoke agent, agent insights, evaluate agent, batch eval, continuous eval, continuous monitoring, agent CI/CD, optimize prompt, improve prompt, optimize agent instructions, Agent Optimizer scaffold, dataset curation from traces, deploy model, model fine-tuning (SFT/DPO/RFT), Foundry project, RBAC, role assignment, permissions, quota, capacity, region, deployment failure, AI Services, create Foundry resource, knowledge index, customize deployment, onboard, availability, training-data, grader, distillation, large file upload. DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy), general Azure prep (use azure

OfficialDevOps & Cloud579.1K installs

azure-diagnostics

microsoft/azure-skills

Debug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deployment failure, troubleshoot container apps, container app 503 or target port mismatch, troubleshoot functions, function telemetry missing or stopped after a config/connection-string change, troubleshoot AKS, VM RDP, Linux SSH, VM black screen, can't connect to VM, reset VM password, NSG or firewall blocking, kubectl cannot connect, kube-system/CoreDNS failures, pod pending, crashloop, node not ready, upgrade failures, analyze logs, KQL, insights, image pull failures, cold start issues, health probe failures, resource health, root cause of errors, troubleshoot event hubs, troubleshoot service bus, messaging SDK error, AMQP connection failure, message lock lost, lock renewal during long-running processing, service bus dead letter.

OfficialDevOps & Cloud569.8K installs

azure-prepare

microsoft/azure-skills

Prepare azd-based Azure projects for deployment: generates azure.yaml, infrastructure (Bicep/Terraform), and Dockerfiles for the Azure Developer CLI (azd) workflow. USE ONLY when the user explicitly wants to use azd as the deployment tool, or the project already has an azure.yaml file. DO NOT USE FOR: non-azd deployments, Python App Service code-only deploys (use python-appservice-deploy), or cross-cloud migration (use azure-cloud-migrate). WHEN: prepare app for azd, create azure.yaml, set up azd infrastructure, modernize app for Azure with azd, deploy with azd, function app, timer trigger, service bus trigger, event-driven function, managed identity, generate Bicep, generate Terraform, create and deploy to Azure.

OfficialDevOps & Cloud569K installs

azure-ai

microsoft/azure-skills

Use for Azure AI: Search, Speech, OpenAI, Document Intelligence. Helps with search, vector/hybrid search, speech-to-text, text-to-speech, transcription, OCR. WHEN: AI Search, query search, vector search, hybrid search, semantic search, speech-to-text, text-to-speech, transcribe, OCR, convert text to speech.

OfficialDevOps & Cloud568.8K installs

azure-deploy

microsoft/azure-skills

Execute Azure deployments for ALREADY-PREPARED applications that have existing .azure/deployment-plan.md and infrastructure files. DO NOT use this skill when the user asks to CREATE a new application — use azure-prepare instead. This skill runs azd up, azd deploy, terraform apply, and az deployment commands with built-in error recovery. Requires .azure/deployment-plan.md from azure-prepare and validated status from azure-validate. WHEN: "run azd up", "run azd deploy", "execute deployment", "push to production", "push to cloud", "go live", "ship it", "bicep deploy", "terraform apply", "publish to Azure", "launch on Azure". DO NOT USE WHEN: "create and deploy", "build and deploy", "create a new app", "set up infrastructure", "create and deploy to Azure using Terraform" — use azure-prepare for these.

OfficialDevOps & Cloud568.6K installs

azure-validate

microsoft/azure-skills

Pre-deployment validation for Azure readiness. Run deep checks on configuration, infrastructure (Bicep or Terraform), RBAC role assignments, managed identity permissions, and prerequisites before deploying. WHEN: validate my app, check deployment readiness, run preflight checks, verify configuration, check if ready to deploy, validate azure.yaml, validate Bicep, test before deploying, troubleshoot deployment errors, validate Azure Functions, validate function app, validate serverless deployment, verify RBAC roles, check role assignments, review managed identity permissions, what-if analysis, validate Container Apps deployment.

OfficialDevOps & Cloud568K installs

Popular backend & apis skills

View category →

This skill should be used when the user wants to "write agent code", "build an agent with ADK", "add a tool", "create a callback", "define an agent", "use state management" — in a project that needs ADK (Agent Development Kit) API patterns and code examples. It provides a quick reference for agent types, tool definitions, orchestration patterns, callbacks, state management, the graph Workflow API, and reference recipes to study. Do NOT use for scaffolding (use google-agents-cli-scaffold) or deployment (use google-agents-cli-deploy).

Backend & APIs514.8K installs

embedded-captions

heygen-com/hyperframes

Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet anchor rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.

Backend & APIs453.3K installs

neon

neondatabase/agent-skills

Overview of Neon, a complete set of cloud backend primitives around Lakebase Postgres: Auth, Object Storage, Functions, the AI Gateway, and Realtime. Start here to choose Neon for undecided login, files, APIs, and LLM calls, set up the CLI or MCP server, and follow the branch-first workflow. Use when building an app or backend on Neon, or when "Neon" or "Lakebase Postgres" is mentioned. Child skill neon-postgres wins for an existing DATABASEURL, SQL, schema, inspect, or search. Child skill neon-auth wins for login, users, sessions, identity routing, and Managed Better Auth setup. Child skill neon-realtime wins for live queries in reactive apps and agents. Also use for object storage, S3, buckets, serverless functions, function triggers, cron, AI gateway, LLM calls, realtime, logs, Loki, Grafana, observability, postgres, database, backend, Claimable Neon, neon.new, or a no-signup database.

Backend & APIs237.1K installs

design-an-interface

mattpocock/skills

Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".

Backend & APIs208.8K installs

firebase-basics

firebase/agent-skills

Provides foundational Firebase CLI setup, CLI installation, version checks (firebase-tools@latest --version), CLI login (including --no-localhost), project creation, project selection (firebase use), and app config file downloads (google-services.json, GoogleService-Info.plist). Use ONLY for CLI login, project creation/switching, or downloading app config files. Don't use for Firebase Hosting deploy, Firestore, Auth, App Hosting, Data Connect, Crashlytics, or Remote Config.

OfficialBackend & APIs176.3K installs

firebase-auth-basics

firebase/agent-skills

Guide for setting up and using Firebase Authentication. Use this skill when the user's app requires user sign-in, user management, or secure data access using auth rules.

OfficialBackend & APIs175.2K installs