AutoGineer
Generated banner for Entra Agent Id
Generated logo for Entra Agent Id

Entra Agent Id

MicrosoftOfficialPublished by Microsoft

  • Skill
  • Tool integration
  • Security
  • MIT
  • Low risk
Download ZIP

From the author

Microsoft Entra Agent ID (preview) for creating OAuth2-capable AI agent identities via Microsoft Graph beta API. Covers Agent Identity Blueprints, BlueprintPrincipals, Agent Identities, required permissions, sponsors, and Workload Identity Federation. Includes Microsoft Entra SDK for AgentID (containerized sidecar) for polyglot agent authentication (Docker/Kubernetes), 3P agent integration, autonomous and interactive agent patterns. Triggers: "agent identity", "agent id", "Agent Identity Blueprint", "BlueprintPrincipal", "entra agent", "agent identity provisioning", "Graph agent identity", "entra sidecar", "agent id sidecar", "auth sidecar", "3P agent", "third-party agent identity", "polyglot agent auth".
— the description by Microsoft

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

Microsoft Entra Agent ID provides a framework for creating and managing secure, OAuth2-capable identities for AI agents. This skill covers the lifecycle of agent identities, including the creation of Agent Identity Blueprints, BlueprintPrincipals, and individual Agent Identities. It details the necessary Microsoft Graph beta API interactions, required permissions, and authentication patterns such as Workload Identity Federation for production or client secrets for development.

What it does

  • Provision Agent Identity Blueprints to define agent types.
  • Create BlueprintPrincipals to enable agent identity functionality.
  • Generate individual Agent Identities for specific agent instances.
  • Configure Workload Identity Federation for secure production authentication.
  • Manage permissions and admin consent for Agent ID operations.
  • Perform cleanup of blueprints, principals, and agent identities.

When to use it

  • When building AI agents that require secure, OAuth2-based authentication within the Microsoft Entra ecosystem.
  • When deploying polyglot agents in containerized environments like Docker or Kubernetes.
  • When implementing autonomous or interactive agent patterns that need distinct service identities.
  • When managing third-party agent integrations that require standard identity provisioning.

Advantages

  • Enables standardized OAuth2 authentication for AI agents.
  • Supports secure production workflows via Workload Identity Federation.
  • Provides granular control over agent identity lifecycles.
  • Integrates directly with Microsoft Graph for programmatic management.

Usage examples

“How do I create an Agent Identity Blueprint using the Microsoft Graph API?”
The agent provides the JSON structure for a POST request to the /applications endpoint, including the required sponsor binding and OData type.
“What are the steps to set up Workload Identity Federation for my agent?”
The agent outlines the process of setting identifierUris, creating a federated identity credential on the blueprint, and configuring the Managed Identity for token exchange.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/microsoft/entra-agent-id/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip entra-agent-id.zip -d .agents/skills

Documentation by Microsoft

Microsoft Entra Agent ID

Create and manage OAuth2-capable identities for AI agents using Microsoft Graph beta API.

Preview API — All Agent Identity endpoints are under /beta only. Not available in /v1.0.

Before You Start

Search microsoft-docs MCP for the latest Agent ID documentation:

  • Query: "Microsoft Entra agent identity setup"

  • Verify: API parameters match current preview behavior

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

Prerequisites

PowerShell (recommended for interactive setup)
# Requires PowerShell 7+
Install-Module Microsoft.Graph.Beta.Applications -Scope CurrentUser -Force
Python (for programmatic provisioning)
pip install azure-identity requests
Required Entra Roles

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

Environment Variables

AZURE_TENANT_ID=<your-tenant-id>
AZURE_CLIENT_ID=<app-registration-client-id>
AZURE_CLIENT_SECRET=<app-registration-secret>

Authentication

⚠️ DefaultAzureCredential is NOT supported. Azure CLI tokens contain Directory.AccessAsUser.All, which Agent Identity APIs explicitly reject (403). You MUST use a dedicated app registration with client_credentials flow or connect via Connect-MgGraph with explicit delegated scopes.

PowerShell (delegated permissions)
Connect-MgGraph -Scopes @(
    "AgentIdentityBlueprint.Create",
    "AgentIdentityBlueprint.ReadWrite.All",
    "AgentIdentityBlueprintPrincipal.Create",
    "User.Read"
)
Set-MgRequestContext -ApiVersion beta

$currentUser = (Get-MgContext).Account
$userId = (Get-MgUser -UserId $currentUser).Id
Python (application permissions)
import os
import 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/beta"
headers = {
    "Authorization": f"Bearer {token.token}",
    "Content-Type": "application/json",
    "OData-Version": "4.0",  # Required for all Agent Identity API calls
}

Core Workflow

Step 1: Create Agent Identity Blueprint

Sponsors are required and must be User objects — ServicePrincipals and Groups are rejected.

import subprocess

# Get sponsor user ID (client_credentials has no user context, so use az CLI)
result = subprocess.run(
    ["az", "ad", "signed-in-user", "show", "--query", "id", "-o", "tsv"],
    capture_output=True, text=True, check=True,
)
user_id = result.stdout.strip()

blueprint_body = {
    "@odata.type": "Microsoft.Graph.AgentIdentityBlueprint",
    "displayName": "My Agent Blueprint",
    "[email protected]": [
        f"https://graph.microsoft.com/beta/users/{user_id}"
    ],
}
resp = requests.post(f"{GRAPH}/applications", 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

This step is mandatory. Creating a Blueprint does NOT auto-create its service principal. Without this, Agent Identity creation fails with: 400: The Agent Blueprint Principal for the Agent Blueprint does not exist.

sp_body = {
    "@odata.type": "Microsoft.Graph.AgentIdentityBlueprintPrincipal",
    "appId": app_id,
}
resp = requests.post(f"{GRAPH}/servicePrincipals", headers=headers, json=sp_body)
resp.raise_for_status()

If implementing idempotent scripts, check for and create the BlueprintPrincipal even when the Blueprint already exists (a previous run may have created the Blueprint but crashed before creating the SP).

Step 3: Create Agent Identities
agent_body = {
    "@odata.type": "Microsoft.Graph.AgentIdentity",
    "displayName": "my-agent-instance-1",
    "agentIdentityBlueprintId": app_id,
    "[email protected]": [
        f"https://graph.microsoft.com/beta/users/{user_id}"
    ],
}
resp = requests.post(f"{GRAPH}/servicePrincipals", headers=headers, json=agent_body)
resp.raise_for_status()
agent = resp.json()

API Reference

OperationMethodEndpointOData Type
Create BlueprintPOST/applicationsMicrosoft.Graph.AgentIdentityBlueprint
Create BlueprintPrincipalPOST/servicePrincipalsMicrosoft.Graph.AgentIdentityBlueprintPrincipal
Create Agent IdentityPOST/servicePrincipalsMicrosoft.Graph.AgentIdentity
List Agent IdentitiesGET/servicePrincipals?$filter=...—
Delete Agent IdentityDELETE/servicePrincipals/{id}—
Delete BlueprintDELETE/applications/{id}—

All endpoints use base URL: https://graph.microsoft.com/beta

Required Permissions

PermissionPurpose
Application.ReadWrite.AllBlueprint CRUD (application objects)
AgentIdentityBlueprint.CreateCreate new Blueprints
AgentIdentityBlueprint.ReadWrite.AllRead/update Blueprints
AgentIdentityBlueprintPrincipal.CreateCreate BlueprintPrincipals
AgentIdentity.Create.AllCreate Agent Identities
AgentIdentity.ReadWrite.AllRead/update Agent Identities

There are 18 Agent Identity-specific Graph application permissions. Discover all:

az ad sp show --id 00000003-0000-0000-c000-000000000000 \
  --query "appRoles[?contains(value, 'AgentIdentity')].{id:id, value:value}" -o json

Grant admin consent (required for application permissions):

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

Admin consent may fail with 404 if the service principal hasn't replicated. Retry with 10–40s backoff.

Cleanup

# Delete Agent Identity
requests.delete(f"{GRAPH}/servicePrincipals/{agent['id']}", headers=headers)

# Delete BlueprintPrincipal (get SP ID first)
sps = requests.get(
    f"{GRAPH}/servicePrincipals?$filter=appId eq '{app_id}'",
    headers=headers,
).json()
for sp in sps.get("value", []):
    requests.delete(f"{GRAPH}/servicePrincipals/{sp['id']}", headers=headers)

# Delete Blueprint
requests.delete(f"{GRAPH}/applications/{blueprint_obj_id}", headers=headers)

Best Practices

  1. Always create BlueprintPrincipal after Blueprint — not auto-created; implement idempotent checks on both

  2. Use User objects as sponsors — ServicePrincipals and Groups are rejected

  3. Handle permission propagation delays — after admin consent, wait 30–120s; retry with backoff on 403

  4. Include OData-Version: 4.0 header on every Graph request

  5. Use Workload Identity Federation for production auth — for local dev, use a client secret on the Blueprint (see references/oauth2-token-flow.md)

  6. Set identifierUris on Blueprint before using OAuth2 scoping (api://{app-id})

  7. Never use Azure CLI tokens for API calls — they contain Directory.AccessAsUser.All which is hard-rejected

  8. Check for existing resources before creating — implement idempotent provisioning

References

FileContents
references/oauth2-token-flow.mdProduction (Managed Identity + WIF) and local dev (client secret) token flows
references/known-limitations.md29 known issues organized by category (from official preview known-issues page)
references/sdk-sidecar.mdMicrosoft Entra SDK for AgentID — endpoints, 3P agent patterns, Docker/K8s deployment, security
External Links
ResourceURL
Official 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 AgentID — Overviewhttps://learn.microsoft.com/en-us/entra/msidweb/agent-id-sdk/overview
Microsoft Entra SDK for AgentID — Endpointshttps://learn.microsoft.com/en-us/entra/msidweb/agent-id-sdk/endpoints

Files

references/known-limitations.md

Known Limitations (Preview)

Source: Microsoft Entra Agent ID preview: Known issues and gaps

API & Object Model

  1. Preview API only — all endpoints are under /beta, not /v1.0

  2. Sponsors must be Users — ServicePrincipals and Groups are not accepted as sponsors

  3. BlueprintPrincipal not auto-created — requires explicit POST /servicePrincipals after Blueprint creation

  4. Agent Identities cannot have password credentials — credentials belong on the Blueprint only (PropertyNotCompatibleWithAgentIdentity error)

  5. Agent Identities have no backing application object — they are service-principal-only entities

  6. Blueprint needs explicit identifierUris — not set by default, required for OAuth2 scope resolution (api://{app-id}/.default)

  7. No Graph relationship filtering for Agent IDs — /ownedObjects, /deletedItems, /owners etc. return all types; must client-side filter by odata.type

  8. Orphaned agent users after deletion — deleting a blueprint or identity does NOT auto-delete its agent users; clean up manually via admin center or Graph API

Roles & Permissions

  1. Directory.AccessAsUser.All hard rejection — if present on the client, all other Agent ID delegated permissions are ignored → 403 Forbidden

  2. No viable delegated permission for creating agent identities — must use application permissions

  3. No quick-start permission bundle — must discover and grant 18+ individual Agent Identity permissions

  4. Permission propagation delay — 30–120+ seconds after admin consent before tokens include new claims; use delegated permissions where possible and add retry with exponential backoff

  5. Global Reader cannot list agent identities — GET /servicePrincipals/graph.agentIdentity returns 403; use GET /servicePrincipals instead

  6. Custom roles cannot include Agent ID actions — use built-in roles (Agent ID Administrator, Agent ID Developer)

  7. Administrative units not supported — cannot add agent identities, blueprints, or blueprint principals to admin units; use owners property instead

  8. Agent ID Admin cannot update agent user photos — use User Administrator role

Admin Center & Management

  1. No blueprint management in Entra admin center — must use Microsoft Graph APIs / PowerShell to create and edit blueprints

  2. /me endpoint unavailable in client_credentials flow — use az ad signed-in-user show or Graph delegated permissions for user context

Authentication & Consent

  1. No SSO to web apps — Agent IDs cannot sign in via Microsoft Entra ID sign-in pages (no OpenID Connect or SAML); use web APIs instead

  2. Admin consent workflow (ACW) broken — does not work properly for permissions requested by Agent IDs; contact tenant admin directly

  3. Cannot grant app permissions to blueprint principals — grant application permissions to individual agent identities instead

  4. Cannot assign app roles where target resource is an agent identity — use blueprint principal as the target resource

  5. Risk-based step-up blocks consent silently — no "risky" indication in the UX

Groups, Logs & Monitoring

  1. No dynamic group membership — agent identities and agent users cannot be added to dynamic groups; use security groups with fixed membership

  2. Audit logs do not distinguish Agent IDs — operations on blueprints/identities logged as ApplicationManagement, agent users as User Management; cross-reference object IDs via Graph to determine entity type

  3. Graph activity logs do not distinguish Agent IDs — agent identity requests logged as applications, agent user requests as users; join with sign-in logs

Performance & Scale

  1. Sequential creation requests may fail — creating multiple entities in quick succession (e.g., blueprint → principal → identity) can return 400 Bad Request: Object with id {id} not found; especially with application permissions. Use delegated permissions where possible and add exponential backoff retry.

Product Integrations

  1. Copilot Studio — only custom engine agents are supported; Agent IDs are used for channel auth only (not connectors or tools)

  2. MSAL complexity — Agent ID scenarios require managing Federated Identity Credentials manually. For .NET use Microsoft.Identity.Web.AgentIdentities. For other languages use the Microsoft Entra SDK for Agent ID.

Reporting Issues

Report unlisted issues via aka.ms/agentidfeedback.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs a command-line tool, Needs Python

Security

What our scanner noticed· Low risk

  • Instructions that use the network

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
Microsoft
Publisher
Microsoft (Official)
Source
microsoft/skills · .github/skills/entra-agent-id · commit 0696600
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Microsoft or Microsoft.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download entra-agent-id.zip