切换深色模式
Microsoft Entra Agent ID：身份模型与认证接入
核对日期：2026-10-05。本文沿用 Google 篇 的范围：公司客户端、第三方本地 Agent、服务器沙箱。本系统只做认证，业务授权由项目负责。 官方能力与“本系统设计”分别标注；没有进行真实租户联调。区域、租户资格和功能发布状态须在部署时核实。
1. 结论：把用户与执行者同时表达清楚
微软的关键价值是将 Agent 纳入企业身份目录，并区分它代表人执行、以应用身份执行和使用自身用户账户执行。它不是一个让任意本地程序自动获得可信来源标签的桌面认证协议。身份模型
本系统可借鉴这种主体与调用者分离的设计。如果项目只需要公司用户登录，无须先把每台个人电脑都注册成 Entra Agent identity；先接普通用户登录，再根据服务器 Agent 的管理需求引入 Agent ID。
2. 官方身份对象
| 对象 | 用途 | 本系统映射建议 |
|---|---|---|
| Blueprint | 管理一组 Agent 身份和凭证使用关系 | 独立记录 blueprint_id |
| Agent identity | 特殊服务主体，通过 Blueprint 获得凭证 | actor_id，不等于自然人 |
| 人类用户 | OBO 操作代表的主体 | 按租户和用户对象映射 |
| Agent user account | Agent 自己的用户账户 | 单独的主体类型 |
| Sponsor / owner | 治理和责任关系 | 资产登记信息，不代表当前委托 |
Agent identity 自身不持有独立凭证；它是租户内的身份。跨租户部署要分别建立当地身份，不能把一个租户的主体直接当另一个租户的主体。S1
3. 架构与信任边界
以下是本系统集成设计：
图：使用 imagegen 生成。蓝色表示厂商能力，青色表示本系统集成设计；凭证交换与检查顺序以下文为准。
Agent ID 的各类实体是 confidential client，不支持普通交互式 /authorize。交互登录由独立客户端发起；Blueprint 的部分回调配置用于同意流程，不能据此把它当桌面公共客户端。认证协议
公司客户端的公开 client_id 被复制后，不能凭这个字段判断二进制来源。实例公钥只能证明持钥；要声明软件来源，仍需受管理设备或应用证明，并标出证明范围。
4. 本地 Agent 如何得到用户身份
以下步骤属于本系统设计，登录协议交给成熟 OIDC 实现：
- 为桌面端注册公共客户端，登记准确回调；不下发 Blueprint 凭证。
- 使用外部浏览器和 PKCE，绑定
state；涉及 ID Token 时验证nonce。 - Broker 验证登录结果，映射内部用户，创建服务器端会话。
- 本地实例需要绑定时生成密钥，通过受认证会话登记公钥，再完成挑战证明；不接受客户端自报用户 ID。
- Broker 为指定项目签发短期凭证；项目验证签名、受众、时效和身份类别，再自主授权。
用户能登录只证明用户身份。第三方软件接入后的来源可为 unverified，由项目决定是否接受；认证平台不把它升级为公司软件。
5. 服务端 OBO 的真实调用关系
OBO 是 On-Behalf-Of：服务端结合自己的身份与用户凭证，为下游换取委托访问凭证。微软 Agent ID 的官方流程涉及多阶段交换：OBO 文档
text
Tc：用户 → Blueprint，aud 必须指向 Blueprint
服务端 Blueprint 凭证 → Entra → T1（交换用途）
T1 + Tc → 子 Agent identity 的 OBO 交换 → 下游资源 TokenT1 的 audience 是交换资源，不能错误要求它与 Tc audience 相同。子身份也不能自己弹出普通登录同意页；继承权限配置与管理员实际同意必须完成。实现优先采用官方 SDK/sidecar。S2
本系统负责验证和保持身份关联；项目或目标资源负责批准业务权限。使用 Microsoft Graph 时，Graph 的权限与同意机制仍需配置，“本系统只认证”不能跳过资源方授权。
自主任务选择 app-only，输出 Agent 主体；不要为了审计方便，把创建人填成当前执行用户。
6. 配置清单与输出契约
部署人员需要准备：租户 ID、Blueprint ID、Agent identity ID、登录客户端、目标 API audience、FIC/托管身份关联、资源侧同意记录、SDK 版本。生产凭证优先托管身份/FIC 或证书。S2
以下 JSON 是本系统适配器配置示例，不是 Microsoft API 请求：
json
{
"provider": "entra-agent-id",
"tenant_id": "<tenant-id>",
"blueprint_id": "<blueprint-id>",
"agent_identity_id": "<agent-identity-id>",
"user_assertion_audience": "<blueprint-client-id>",
"project_audience": "urn:company:project:demo",
"subject_mapping": "tenant_id + object_id",
"software_origin_default": "unverified"
}资源服务器可以验证并解释发给自己的 Token；客户端应将资源 access token 当不透明凭证。资源端关注 tid、oid、aud 和 azp（v1 为 appid）。idtyp=user 也可能是 Agent 自己的用户账户，需结合主体事实字段区分；不能仅凭 idtyp 推断自然人。Token claims
本系统输出 subject_kind、user_id（可空）、actor_id、provider、session_id。上游字段缺失时保留未知，不能通过邮箱补造稳定主体。不要把 Blueprint ID 当所有子 Agent 的统一放行依据。
7. 校验、撤销与审计
本系统设计：固定信任租户和 issuer；使用适配令牌版本的验证库；检查 audience、签名、算法、有效期及主体映射。为每个目标分开缓存令牌，缓存键至少含租户、主体、Agent、目标资源与认证模式。
用户登出或绑定撤销后，停止本系统续签，并按项目的撤销检查方式使旧凭证失效。上游停用不一定瞬间使所有离线 JWT 失效；需测量传播窗口。审计记录用户、调用 Agent、Blueprint、目标、结果和关联 ID，不记录原始 Token。
8. 实施顺序与真实环境验收
先完成普通登录和项目验签，再增加单租户服务器 Agent；完成 app-only 后再联调 OBO，最后扩展跨租户和轮换。以下均为未实测，是上线条件，不是本轮研究的成功记录：
| 编号 | 验收动作 | 必须看到的结果 |
|---|---|---|
| M1 | 桌面公共客户端正常登录 | 用户可识别，来源仍按证据标记 |
| M2 | 将 Graph Token 当 Tc 提交 | audience 不匹配时拒绝 |
| M3 | 更换另一子身份或租户 | 不得串用原有交换上下文 |
| M4 | 未完成资源同意时调用 | 明确失败，不回退管理员凭证 |
| M5 | Agent user account 调用 | 不归类为人类用户 |
| M6 | 停用身份/撤销会话及轮换密钥 | 记录实际失效时间与恢复行为 |
9. 详细设计：一次用户委托请求如何完成
本节把前述官方流程应用到一个具体场景：员工让 Agent 查询项目工单，项目系统仍自行判断员工是否能看该工单。除明确引用官方机制的内容外，接口与运行约定均为本系统设计。
9.1 四种凭证不能混用
| 凭证 | 持有位置 | 接收方 | 验证目的 |
|---|---|---|---|
| 登录结果 / 客户端会话 | 客户端或 Broker 会话设施 | 登录客户端 / Broker | 确立当前用户 |
| 用户访问令牌 Tc | 本地到可信服务端链路 | Blueprint 所代表的 API | 确认该用户正调用这个服务端 |
| 交换令牌 T1 | 服务端 SDK 的受保护缓存 | Entra 交换端点 | 子 Agent 进行交换时的客户端身份依据 |
| 下游资源令牌 | 服务端 Agent | 对应目标 API | 表达面向该资源的用户与 actor |
OBO 请求中的 assertion 和 client_assertion 分别承担用户与调用方身份作用，不能用同一个用户 Token 填两处。准确参数由官方 SDK 构建，协议依据见 S3。
9.2 请求处理顺序
- 建立登录事务。 客户端生成一次性登录参数，浏览器完成身份源认证。本系统保存登录事务而非只依赖回调中的用户信息。
- 接收调用。 服务端先校验 Tc 的签名、签发者、时效及预期受众，映射可信用户。请求体中的
user_id即使存在也不作为身份输入。 - 选择 Agent。 根据已登记应用、租户和当前服务的映射选择子身份。允许用户挑选展示名称，不允许其指定任意租户的 Agent ID 触发交换。
- 获得 T1。 SDK 使用 Blueprint 的运行凭证完成交换。短期结果仅存于服务端，不返回浏览器或日志。
- 请求资源令牌。 在子 Agent 上下文中结合 Tc 与 T1 换取目标资源 Token；所需资源和 scopes 取服务端允许的集成配置。
- 调用工单服务。 若工单服务直接接受 Entra Token，就按该资源的验证契约验证；若接受内部 Token，则走事先明确的 Broker 接入，不假装任意 Graph Token 都能换内部身份。
- 执行项目授权。 工单服务用验证出的用户和 actor 检查工单可见性。身份正确但无权查看时由项目返回拒绝。
该例中的 OBO 用于实际需要 Entra 下游委托的路径。只访问接受内部凭证的自有项目时，可直接采用 Broker 登录及凭证签发，不应为了形式完整而增加无用交换。
9.3 服务端适配器契约
| 本系统操作 | 可信输入 | 输出 | 不接受的替代输入 |
|---|---|---|---|
authenticate_user | 已验证的目标 API 用户凭证 | 租户、内部用户、会话 | 邮箱后缀或请求体用户 ID |
resolve_agent | 服务端登记与租户上下文 | 唯一子 Agent 引用 | 任意客户端传入的 Blueprint/Agent 组合 |
acquire_resource_token | 用户会话、Agent、固定资源配置 | 仅供目标资源使用的 Token | 任意 URL 或调用者提供的 issuer |
issue_project_identity | 独立验证并归一化的身份事实 | 内部项目凭证 | 未验证的上游 claims |
这些是程序内操作名称，不是 Microsoft Graph API。模块边界应允许替换 SDK，而不改变项目使用的身份字段。
9.4 缓存与并发
本系统建议将资源令牌缓存键设为租户、主体类型、用户、子 Agent、目标资源及请求权限集合的规范化组合。自主任务和用户委托不能共享缓存项；两个用户即使调用同一 Agent 也必须隔离。
刷新采用单航班锁，避免同一会话并发刷新造成请求风暴。凭证失效、用户会话撤销或 Agent 映射版本变化时清理相关缓存。网络超时可有界重试；租户、受众或同意错误不能通过换成更高权限身份重试。
9.5 错误处理与审计证据
| 失败位置 | 对外行为 | 内部排查重点 |
|---|---|---|
| 登录事务无效 | 重新登录 | 回调、state、事务时效 |
| Tc 无效 | 401 | issuer/audience/签名/时间，避免输出原 Token |
| Agent 映射不存在 | 拒绝该集成 | 租户、登记和禁用状态 |
| 同意不完整 | 返回需要管理员处理的集成错误 | 资源侧实际同意记录 |
| 下游业务拒绝 | 保留项目 403 | 用户、actor、资源决策关联 |
| 上游不可用 | 有界重试后返回可重试故障 | SDK 诊断关联 ID、依赖状态 |
单条审计事件建议含内部请求 ID、租户、用户、actor、Blueprint、目标项目、认证结果与项目决策引用。把“认证通过”和“业务允许”写为不同事件，才能解释 Agent 以谁的身份做了什么。
9.6 无人值守任务的边界
定时任务默认走工作负载身份。确需长期用户上下文时，要保留明确的委托会话、刷新生命周期和撤销入口；用户最初创建过 Agent 并不构成无限期委托。服务重启后只能恢复仍有效的受保护会话，不能从任务表里的用户 ID 重造身份。