用 Cognito 为 Agent 换取受限访问令牌
文章介绍 Cognito 基于 RFC 8693 的令牌交换,用 TypeScript 和 AWS CDK 构建书店 Agent 只读访问订单 API 的示例。交换后的令牌限制权限与目标服务、不含刷新令牌,并可通过 act 声明标识代理身份。
AI 深度解读
AI agent 替用户查订单,究竟该拿谁的 token 调后端?作者给出的方案是:把用户 token 换成一张权限更小、只面向订单 API、还能标明 agent 身份的新 token。重点不在模型如何调用工具,而在工具调用背后的授权边界。
据原文,Amazon Cognito 从 2026 年 11 月 12 日起支持 RFC 8693 token exchange。作者用 TypeScript 和 AWS CDK 搭了一个书店示例,也记录了新功能上线时 SDK、CloudFormation 尚未跟上的问题。这套思路对正在接入 agent 或 MCP 的团队很有参考价值,但示例离生产授权系统仍有距离。
用户登录了,不代表 agent 可以拿走全部权限
书店用户向聊天助手提问:「我的订单到哪了?」agent 需要读取订单,却不需要取消订单。如果直接转发用户的 access token,就可能同时拿到读取和取消权限,订单 API 也无法区分这次请求来自用户操作,还是 agent 的工具调用。
Token exchange 把这两个身份拆开了。
subject_token 代表被代理的用户,actor_token 代表实际执行操作的服务。交换后的 token 仍然关联用户,但可以缩小 scope,也就是允许执行的操作;同时用 aud 指定接收它的 API。带上 actor token 时,新 token 还会包含 act claim,让后端识别代理者。
Cognito 提供两种模式:不传 actor token 是 impersonation,传入则是 delegation。作者更倾向让 AI agent 使用 delegation,因为审计时需要知道「谁替谁做了什么」。对应的客户端开关分别是 ALLOW_TOKEN_EXCHANGE_IMPERSONATION 和 ALLOW_TOKEN_EXCHANGE_DELEGATION。
交换后的权限上限,取决于请求 scope、用户原有 scope、交换客户端允许 scope 三者的交集。
例如,用户可以取消订单,但 agent 客户端只允许 bestellungen/lesen,交换就不能凭空获得 bestellungen/stornieren。这里的德语标识分别表示「订单/读取」和「订单/取消」。
原文还列出了几项约束:新 token 只面向一个已注册的 resource server,不带 refresh token;交换时检查原 token 的签名、有效期和撤销状态,禁用或未确认的用户无法获得新 token。套餐要求是 Essentials 或 Plus,Lite 不支持。
没有 refresh token 能减少长期续期的入口,但不要由此推断:用户退出登录后,所有已签发的派生 token 都会立即失效。原文没有给出这样的验证结果。
订单 API 为什么必须拒绝原始 token
示例的链路是:Web 应用登录用户,携带用户 token 请求 agent Lambda;Lambda 获取自己的 actor token,再交换出订单专用 token,最后调用订单 API。

这条链路能限制权限,关键在接收方也有约束。
作者指出,普通 Cognito 登录产生的 access token 没有 aud,只有 Web 应用的 client_id。API Gateway JWT authorizer 会优先匹配 aud,缺少时匹配 client_id。把订单 API 的 audience 配成 bestellungen,原始用户 token 就无法直接通过。
agent 自己通过 client_credentials 获取的 token 也一样:按原文描述,它没有目标 aud,其 client_id 又属于 agent 客户端,因此同样会被拒绝。必须经过交换,才能拿到订单 API 接受的凭证。
下面这段代码负责构造交换请求,字段名直接对应 RFC 8693:
export function buildExchangeBody(req: ExchangeRequest): URLSearchParams {
if (req.scopes.length === 0) throw new Error('Specify at least one scope');
const body = new URLSearchParams({
grant_type: GRANT_TOKEN_EXCHANGE,
subject_token: req.subjectToken,
subject_token_type: TYPE_ACCESS_TOKEN,
audience: req.audience,
scope: req.scopes.join(' '),
});
if (req.actorToken) {
body.set('actor_token', req.actorToken);
body.set('actor_token_type', TYPE_ACCESS_TOKEN);
}
return body;
}
要看的是 audience、scope 和 actor_token 三处,它们分别确定接收方、请求权限和代理身份。两个常量的值分别是 urn:ietf:params:oauth:grant-type:token-exchange 与 urn:ietf:params:oauth:token-type:access_token。
请求发往 /oauth2/token,使用 POST、application/x-www-form-urlencoded 和客户端 Basic 认证,因此 user pool 需要配置 domain。agent 实际请求的 audience 是 bestellungen,scope 是 bestellungen/lesen。
后端还要做业务判断。原文把规则放在独立的 entscheide 函数中:先检查操作所需 scope,再读取 act.sub;只要识别到 agent,就拒绝取消订单,即使 token 意外包含取消权限。这让凭证权限和业务限制形成两层约束。
新功能能调用,不代表部署工具已经支持
作者给出的环境要求是 Node.js 22 或更新版本,实测使用 Node.js 24;项目采用 ES modules、TypeScript 7、AWS CDK v2,并列出 Vitest。AWS 账户需先完成 npx cdk bootstrap,末尾测试还需要 curl、jq、openssl。
不过,提供的原文在基础设施代码和订单 API 代码处都有截断,也没有展示完整测试结果,不能直接当作可运行项目复制。
最有参考价值的是两处工具链问题。
第一,作者使用 aws-cdk-lib 2.276.0 时,cdk synth 会针对新 auth flow 报出 W3030,原因是 CloudFormation schema 尚未识别它。其处理方法是在部署后运行:
npx tsx scripts/enable-token-exchange.ts <user-pool-id> <agent-client-id>
脚本先用 DescribeUserPoolClient 读取配置,再通过 UpdateUserPoolClient 添加 delegation。这里不能只提交新 flow,因为作者指出,未提交的字段会被重置为默认值,原来的 scopes 和 OAuth 配置可能丢失。
下面的辅助函数保留现有配置,再追加新值:
// src/client-update.ts
// Builds a complete UpdateUserPoolClient request from DescribeUserPoolClient.
// Important: UpdateUserPoolClient resets every field you don't send to its default value.
import type { UpdateUserPoolClientCommandInput, UserPoolClientType } from '@aws-sdk/client-cognito-identity-provider';
const NICHT_AKTUALISIERBAR = ['ClientSecret', 'CreationDate', 'LastModifiedDate'] as const;
export function withAuthFlow(client: UserPoolClientType, flow: string): UpdateUserPoolClientCommandInput {
const input: Record<string, unknown> = { ...client };
for (const key of NICHT_AKTUALISIERBAR) delete input[key];
const flows = new Set<string>(client.ExplicitAuthFlows ?? []);
flows.add(flow);
// The SDK doesn't know the new value as a type yet, but sends it unchanged
input.ExplicitAuthFlows = [...flows];
return input as unknown as UpdateUserPoolClientCommandInput;
}
要留意 const input: Record<string, unknown> = { ...client };:这一步保留现有配置,随后删除不可更新字段。类型断言只是绕过 SDK 类型缺失,不提供运行时校验。后续 cdk deploy 若修改 agent 客户端,还可能覆盖这个 flow,所以作者要求每次部署后重跑脚本,等 schema 支持后再收回基础设施代码。
第二,原文使用的 @aws-sdk/client-cognito-identity-provider 3.1168.0 没有 GetDerivedTokenCommand,botocore 1.44.2 也不认识 GetDerivedToken。作者因此直接用 fetch 调 OAuth endpoint。这些是文中版本对应的限制,不能当作长期结论。
agent Lambda 在冷启动时读取 client secret,并缓存通过 buchladen-agent/handeln 获取的 actor token,在到期前 60 秒停止复用。作者这样处理是为了减少请求,因为 Cognito 的 M2M token 单独计费,但文中没有给出费用对照。
我的判断
我认同作者把授权边界放在工具执行层。模型选择调用哪个工具,后端决定这个调用能做什么;用 scope、audience 和 act 分别表达操作、接收方和代理身份,比只在提示词里要求「不要取消订单」更可靠。
相比自签 token,Cognito 代管签发能减少自建密钥轮换和 claims 组装代码。不过,「更省维护」仍是架构经验,原文没有提供成本或故障率对照。
还有两个缺口需要补齐。Cognito 不处理 RFC 8693 的 may_act,所以「哪个 agent 可以代理哪个用户」仍需通过客户端 scope、Lambda trigger 等方式约束。外部身份提供方的用户也必须事先关联到 user pool,交换不会自动创建用户。
此外,scope 只说明允许执行哪类操作,不能替代订单归属校验。 示例返回的是固定订单数据,没有展示按用户身份筛选订单。act 能提供审计线索,也不能证明用户明确批准了每一次操作。
原文的 decodeJwtPayload 仅解码 JWT,安全前提是 API Gateway 已完成验证。把它搬进普通 Node 服务时,必须保留这个前提。
能拿来做什么
- 给已有 Cognito 的 agent 工具调用增加交换环节,由 Node 服务或 MCP tool handler 持有客户端凭据,只请求目标 API 必需的 scope。
- 为后端验证三类请求:原始用户 token、agent 的 client credentials token、交换后的 token,确认只有符合 audience 和 scope 要求的凭证能够通过。
- 在订单等业务接口中同时校验用户的数据归属和代理者限制,并将用户身份、
act.sub、操作及结果写入审计记录。 - 如果采用文中的部署补丁,就把配置保留、flow 检查和部署后脚本纳入流水线,并根据实际 SDK、CDK 版本确认补丁是否仍然需要。