entra-agent-id

Name: entra-agent-id
Author: microsoft

Microsoft Entra 代理标识

使用 Microsoft Graph 为 AI 代理创建和管理支持 OAuth 2.0 的标识。每个代理实例拥有独立的标识、审计轨迹和独立范围的权限授予。

快速参考

属性	值
服务	Microsoft Entra 代理标识
API	Microsoft Graph (`https://graph.microsoft.com/v1.0`)
所需角色	代理标识开发者、代理标识管理员或应用程序管理员
对象模型	蓝图（应用程序）→ 蓝图主体（服务主体）→ 代理标识（服务主体）
运行时交换	两步 `fmi_path` 交换（自主和 OBO）
.NET 帮助程序	`Microsoft.Identity.Web.AgentIdentities`
多语言帮助程序	Microsoft Entra SDK for AgentID（边车容器）

何时使用此技能

预配新的代理标识蓝图和蓝图主体
在蓝图下创建每个实例的代理标识
在蓝图上配置凭据（FIC、托管标识或客户端密码）
实现两步 fmi_path 运行时令牌交换（自主或 OBO）
跨租户代理令牌流
为多语言代理（Python、Node、Go、Java）部署 Microsoft Entra SDK for AgentID 边车
授予每个代理标识的应用程序（appRoleAssignments）或委托（oauth2PermissionGrants）权限
诊断代理标识错误，例如 AADSTS82001、AADSTS700211 或 PropertyNotCompatibleWithAgentIdentity

MCP 工具

工具	用途
`mcp_azure_mcp_documentation`	搜索 Microsoft Learn 以获取当前的代理标识设置、Graph API 形状和 SDK 配置

目前没有专用的代理标识 MCP 服务器。此技能指导直接的 Microsoft Graph API 调用（PowerShell 或 Python requests）。在运行前使用 mcp_azure_mcp_documentation 根据当前文档验证请求体和端点。

开始之前

使用 mcp_azure_mcp_documentation 工具搜索 Microsoft Learn 以获取当前的代理标识文档：

"Microsoft Entra 代理标识设置说明"
"Microsoft Entra SDK for AgentID"

根据已安装的 SDK 版本验证请求体和端点——Graph API 形状会演变。

概念模型

代理标识蓝图（应用程序）         ← 每个代理类型/项目一个
  └── 蓝图主体（服务主体）    ← 必须显式创建
        ├── 代理标识（SP）：agent-1    ← 每个代理实例一个
        ├── 代理标识（SP）：agent-2
        └── 代理标识（SP）：agent-3

概念	描述
蓝图	定义代理类型/类的应用程序对象。持有凭据（密码、证书、联合标识）。
蓝图主体	蓝图中在租户中的服务主体。不会自动创建。
代理标识	单个代理实例的仅服务主体标识。不能持有自己的凭据。
赞助者	负责该标识的用户（或组，对于代理标识）。创建时必须提供。

先决条件

所需的 Entra 角色

以下之一：代理标识开发者、代理标识管理员或应用程序管理员。

PowerShell（交互式设置）

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

Python（编程式预配）

pip install azure-identity requests

身份验证

不支持 DefaultAzureCredential。 Azure CLI 令牌携带 Directory.AccessAsUser.All，代理标识 API 会硬拒绝（403）。请使用专用的应用注册配合 client_credentials，或使用 Connect-MgGraph 并指定显式的委托范围。

PowerShell（委托）

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

Python（应用程序）

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

核心工作流

步骤 1：创建代理标识蓝图

使用类型化端点。创建蓝图时，赞助者必须是用户。此代码片段假设使用上述 Python 身份验证块中的 requests 客户端和 headers 字典。

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"]

步骤 2：创建蓝图主体

必须执行。创建蓝图不会自动创建其服务主体。跳过此步骤会产生：
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()

使预配脚本幂等——即使蓝图已存在，也要始终检查蓝图主体。

步骤 3：创建代理标识

代理标识的赞助者可以是用户或组。

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"]

运行时身份验证

代理在运行时使用在蓝图上配置的凭据进行身份验证（而不是在代理标识上——代理标识不能持有凭据）。

选项	用例	蓝图上的凭据
托管标识 + WIF	生产环境（Azure 托管）	联合标识凭据
客户端密码	本地开发/测试	密码凭据
Microsoft Entra SDK for AgentID	多语言/第三方代理	边车容器通过 HTTP 获取令牌

关于两步 fmi_path 交换（父令牌 → 每个代理标识的 Graph 令牌），它为每个代理实例提供不同的 sub 声明和审计轨迹，请参阅 references/runtime-token-exchange.md。

关于 OBO（代理代表用户操作），请参阅 references/obo-blueprint-setup.md。

关于容器化的多语言身份验证边车（Python、Node、Go、Java——无需嵌入 SDK），请参阅 references/sdk-sidecar.md。

关于 MI+WIF 和客户端密码设置的详细信息，请参阅 references/oauth2-token-flow.md。

.NET 快速路径

对于 .NET 服务，请使用 Microsoft.Identity.Web.AgentIdentities——它会为您处理联合标识凭据管理和两步交换。请参阅 github.com/AzureAD/microsoft-identity-web 下 src/Microsoft.Identity.Web.AgentIdentities/ 中的包自述文件。

授予权限（每个代理标识）

代理标识支持应用程序权限（自主）和委托权限（OBO）。授予范围限定为每个代理标识，而不是蓝图主体。

应用程序权限（自主）

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

委托权限（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()

基于浏览器的管理员同意 URL 不适用于代理标识——请使用 oauth2PermissionGrants 进行编程式委托同意。

跨租户代理标识

蓝图可以是多租户的（signInAudience: AzureADMultipleOrgs）。在跨租户交换令牌时：

父令牌交换的步骤 1 必须针对代理标识的主租户，而不是蓝图的主租户。错误的租户会导致 AADSTS700211: No matching federated identity record found。

请参阅 references/runtime-token-exchange.md 获取完整的跨租户示例。

API 参考

操作	方法	端点
创建蓝图	`POST`	`/applications/microsoft.graph.agentIdentityBlueprint`
创建蓝图主体	`POST`	`/servicePrincipals/microsoft.graph.agentIdentityBlueprintPrincipal`
创建代理标识	`POST`	`/servicePrincipals/microsoft.graph.agentIdentity`
向蓝图添加 FIC	`POST`	`/applications/{id}/microsoft.graph.agentIdentityBlueprint/federatedIdentityCredentials`
列出代理标识	`GET`	`/servicePrincipals/microsoft.graph.agentIdentity`
授予应用程序权限	`POST`	`/servicePrincipals/{id}/appRoleAssignments`
授予委托权限	`POST`	`/oauth2PermissionGrants`
删除代理标识	`DELETE`	`/servicePrincipals/{id}`
删除蓝图	`DELETE`	`/applications/{id}`

基础 URL：https://graph.microsoft.com/v1.0。

所需的 Graph 权限

权限	用途
`AgentIdentityBlueprint.Create`	创建蓝图
`AgentIdentityBlueprint.ReadWrite.All`	读取/更新蓝图
`AgentIdentityBlueprintPrincipal.Create`	创建蓝图主体
`AgentIdentity.Create.All`	创建代理标识
`AgentIdentity.ReadWrite.All`	读取/更新代理标识
`Application.ReadWrite.All`	对应用程序对象进行蓝图 CRUD
`AppRoleAssignment.ReadWrite.All`	授予应用程序权限
`DelegatedPermissionGrant.ReadWrite.All`	授予委托权限

授予管理员同意（应用程序权限需要）：

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

管理员同意后，令牌可能需要 30–120 秒才能包含新声明——请使用指数退避重试。

最佳实践

始终在创建蓝图后创建蓝图主体——不会自动创建。
使用类型化端点（/applications/microsoft.graph.agentIdentityBlueprint）而不是原始 /applications 配合 @odata.type。
凭据位于蓝图上——代理标识不能持有密码/证书（PropertyNotCompatibleWithAgentIdentity）。
在每个 Graph 请求中包含 OData-Version: 4.0。
生产环境使用工作负载标识联合——客户端密码仅用于本地开发。
在蓝图上设置 identifierUris: ["api://{appId}"]，在 OAuth2 范围解析之前。
切勿对代理标识 API 使用 Azure CLI 令牌——Directory.AccessAsUser.All 会导致硬 403。
使用 fmi_path 配合 client_credentials——而不是 RFC 8693 urn:ietf:params:oauth:grant-type:token-exchange（返回 AADSTS82001）。
在交换的两个步骤中始终使用 /.default 范围——单个范围会失败。
在跨租户流中，步骤 1 针对代理标识的主租户。
权限授予每个代理标识，而不是蓝图主体。
处理权限传播延迟——管理员同意后，使用 30–120 秒退避重试 403。
将 Entra SDK for AgentID 保留在 localhost 上——切勿通过 LoadBalancer 或 Ingress 暴露。

故障排除

错误	原因	修复
`AADSTS82001`	使用了 RFC 8693 令牌交换授权	使用 `client_credentials` 配合 `fmi_path`
`AADSTS700211`	步骤 1 父令牌针对了错误的租户	针对代理标识的主租户
`AADSTS50013`	OBO 用户令牌针对 Graph 而不是蓝图	使用 `api://{blueprint_app_id}/access_as_user`
`AADSTS65001`	缺少授予或使用了单个范围	使用 `/.default` 并验证 `oauth2PermissionGrants`
`403 Authorization_RequestDenied`	此代理标识上没有授予	通过 `appRoleAssignments` 或 `oauth2PermissionGrants` 添加
`PropertyNotCompatibleWithAgentIdentity`	尝试向代理标识 SP 添加凭据	将凭据放在蓝图上
`Agent Blueprint Principal does not exist`	蓝图主体未创建	核心工作流的步骤 2
管理员同意时出现 `AADSTS650051`	部分同意后 SP 已存在	直接通过 `appRoleAssignments` 授予

参考

文件	内容
references/runtime-token-exchange.md	两步 `fmi_path` 交换：自主 + OBO，跨租户
references/oauth2-token-flow.md	MI + WIF（生产环境）和客户端密码（本地开发）
references/obo-blueprint-setup.md	将蓝图配置为 OAuth2 API 以用于 OBO
references/sdk-sidecar.md	Microsoft Entra SDK for AgentID——架构、配置、端点
references/sdk-sidecar-deployment.md	SDK 代码模式（Python/TypeScript）、Docker/Kubernetes 清单、安全性、故障排除
references/known-limitations.md	按类别组织的已知限制

外部链接

资源	URL
代理标识设置指南	https://learn.microsoft.com/en-us/entra/agent-id/identity-platform/agent-id-setup-instructions
AI 引导设置	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

你可能还喜欢

security-and-hardening

77Ksecurity

强化代码以抵御漏洞。适用于处理用户输入、身份验证、数据存储或外部集成时。适用于构建任何接受不可信数据、管理用户会话或与第三方服务交互的功能。

addyosmani

获取

api-security-best-practices

43Ksecurity

Implement secure API design patterns including authentication, authorization, input validation, rate limiting, and protection against common API vulnerabilities

sickn33

获取

security-review

37Ksecurity

AI-powered codebase security scanner that reasons about code like a security researcher — tracing data flows, understanding component interactions, and catching vulnerabilities that pattern-matching tools miss. Use this skill when asked to scan code for security vulnerabilities, find bugs, check for SQL injection, XSS, command injection, exposed API keys, hardcoded secrets, insecure dependencies, access control issues, or any request like "is my code secure?", "review for security issues", "audit this codebase", or "check for vulnerabilities". Covers injection flaws, authentication and access control bugs, secrets exposure, weak cryptography, insecure dependencies, and business logic issues across JavaScript, TypeScript, Python, Java, PHP, Go, Ruby, and Rust.

github

获取

继续探索

浏览 security 热门 Skills 最近更新