验证下游 API 中的代理标识令牌

当 AI 代理通过 Microsoft Entra ID 身份验证 SDK（sidecar）调用你的 API 时，请求中会包含一个 Bearer 令牌。 API 会验证此令牌，以确认请求来自具有正确权限的经过身份验证的代理。如果验证失败，API 会返回 HTTP 401，原因如下。

本文介绍验证检查，并演示如何配置和运行验证代理标识令牌端到端的示例天气 API。

先决条件

Docker Desktop（macOS / Windows）或 Docker Engine（Linux）。
具有智能体标识蓝图和智能体标识的 Microsoft Entra 租户。有关设置步骤，请参阅创建代理蓝图并创建和删除代理标识。
用于测试的代理标识令牌。可以从 sidecar 本地开发示例或 Microsoft Entra 智能体 ID 示例存储库中的脚本获取一个。

令牌验证检查

下游 API 应对每个传入代理标识令牌执行四次检查：

检查	它验证什么	详细信息
签名	令牌不会被篡改。	根据 `https://login.partner.microsoftonline.cn/<tenant>/discovery/v2.0/keys` 处的 JSON Web 密钥集 (JWKS) 验证 RS256 签名。
颁发者	Microsoft Entra ID颁发了令牌。	声明 `iss` 匹配 `https://sts.chinacloudapi.cn/<tenant>/` 或 `https://login.partner.microsoftonline.cn/<tenant>/v2.0`。
观众	令牌是为你的 API 设计的。	声明 `aud` 与 API 的预期受众值匹配。
代理身份标记	令牌已颁发给代理，而不是常规应用。	声明 `xms_par_app_azp` 存在于代理标识令牌中，在标准仅限应用令牌中不存在。此声明标识创建代理的蓝图。

当所有四个检查通过时，API 都可以信任并处理请求。

示例天气 API 的工作原理

Microsoft Entra 智能体 ID示例存储库包含演示这些验证检查的示例天气 API。示例 API 是一个最小的 Flask 应用，充当代理调用的下游 API。它验证传入的代理标识令牌，并从 Open-Meteo 返回真实天气数据。

本地开发 (Ollama) 和 AWS (Bedrock) 边车示例均调用相同的天气 API 容器。此示例包含三个文件：

app.py： 具有路由处理程序、令牌验证逻辑和 Open-Meteo 客户端的 Flask 应用。
Dockerfile： 使用 python:3.13-slim 作为基础映像。在端口 8080 上运行 gunicorn app:app 。
requirements.txt：依赖项：flask、、pyjwt[crypto]cryptography、requestsgunicorn。

API 公开两个终结点：

GET /weather?city=<name>： 验证 Authorization: Bearer <token> 标头并返回指定城市的天气数据。
GET /healthz： 返回不需令牌验证的健康状态。

下图显示了令牌如何从代理程序流经 Sidecar 到天气 API。代理从不直接与Microsoft Entra ID联系。相反，sidecar 会代表代理标识获取令牌（TR），代理将该令牌传递到标头中的 Authorization: Bearer 天气 API。

显示代理呼叫者向天气 API 发送持有者令牌的示意图，该 API 验证令牌后调用 Open-Meteo。

代理标识令牌 TR 由Microsoft Entra ID通过 sidecar 颁发。它包含您 API 验证的声明信息，包括 xms_par_app_azp 代理身份标识。有关流中所有令牌的详细分解，请参阅运行边车进行本地开发。

令牌验证库因生态系统而异（Python、Node.js、.NET）。此示例将 PyJWT 与后端配合使用 cryptography 进行 RS256 签名验证。生成自己的下游 API 时，为技术堆栈选择等效的 JWT 验证库。

配置示例天气 API

示例天气 API 接受以下环境变量：

Variable	必需	默认	Purpose
`TENANT_ID`	Yes	—	贵公司的 Microsoft Entra 租户 ID，用于生成 JWKS URL 并验证颁发者声明。
`EXPECTED_AUDIENCE`	No	`https://microsoftgraph.chinacloudapi.cn`	预期的 `aud` 声明值。默认为 Microsoft Graph，使相同的智能体令牌可用于本地测试。
`PORT`	No	`8080`	API 监听的 HTTP 端口。

运行示例天气 API

若要将天气 API 作为独立容器运行并测试令牌验证，请执行以下操作：

克隆存储库并导航到天气 API 目录：

git clone https://github.com/microsoft/entra-agentid-samples.git
cd entra-agentid-samples/sidecar/weather-api

生成并运行容器：

docker build -t weather-api:local .
docker run --rm -p 8080:8080 \
  -e TENANT_ID=<your-tenant-id> \
  -e EXPECTED_AUDIENCE=https://microsoftgraph.chinacloudapi.cn \
  weather-api:local

使用代理标识令牌发送请求：

curl -H "Authorization: Bearer $TOKEN" \
     "http://localhost:8080/weather?city=Dallas"

API 返回一个 JSON 响应，其中包含天气数据和令牌验证结果：

{
  "city": "Dallas",
  "temperature": 61,
  "temperature_unit": "F",
  "condition": "Overcast",
  "humidity": 93,
  "wind_speed": 8,
  "is_agent_identity": true,
  "agent_app_id": "<agent-app-id from xms_par_app_azp>",
  "validated_by": "Agent Identity Token",
  "data_source": "Open-Meteo API (Real-time)"
}

这些is_agent_identity、agent_app_id和validated_by字段确认令牌验证。

is_agent_identity： 当true 声明存在时，将其设置为 xms_par_app_azp，该声明确认令牌已颁发给代理标识，而不是标准应用注册。
agent_app_id： 用于标识创建代理身份的蓝图应用程序的声明值 xms_par_app_azp 。
validated_by： 应用于令牌的验证方法。显示 Agent Identity Token 当代理标记声明存在时。

Last updated on 2026-09-03