AI 原生开放教材

外观

AI 工程从零到一（中文）源码研读·中文原文 ↗原件 ↓仓库 ↗

集成协议、身份与最小权限 ​

工具安全取决于系统能否拒绝未授权调用；Claude 是否谨慎不能代替授权。

类型： 构建 语言： Python 前置要求： 端到端架构与价值取舍；阶段 13，第 01、05、06、16 和 18 课 预计时间： 约 150 分钟

学习目标 ​

  • 根据需求选择直接 API、CLI、MCP 或 agent 间集成
  • 将能力发现与执行授权分开
  • 设计最小权限工具集和身份传递机制
  • 返回结构化、可操作且不会泄露机密的错误
  • 把审批、审计和撤销控制放在执行边界

问题所在 ​

一个客服 agent 可以读取工单、起草回复、发放退款和删除用户账户。大多数客服人员只需要前两项 能力。团队却让四个工具始终启用，只增加了一条 prompt：“除非绝对必要，否则绝不退款或删除 账户。”

这不是最小权限。危险能力依然存在，模型依然能看到它，prompt 注入也依然可以把它当作目标。 确认文本可以减少误操作，却不能代替授权。

结构性修复很直接：移除角色不需要的能力，传递调用方身份，并在工具执行时强制检查 权限范围和审批状态。

核心概念 ​

根据边界选择集成形态 ​

这些协议的能力有重叠，但它们主要解决的问题不同。

形态最适用场景主要取舍
直接 API应用已知一个服务契约，并且需要低开销服务耦合紧密，需要自定义发现机制
CLI围绕可执行程序的本地或 CI 自动化进程、环境和输出管理负担
MCPhost 需要跨 server 以标准方式发现工具、资源或 prompt需要运维另一套协议边界和授权模型
agent 间集成一个 agent 把任务委派给另一个自主服务信任、身份、进度和故障语义更难处理

MCP 不会取代所有 API。对于稳定的内部服务调用，直接 API 可能更清晰、更快。多个 host 需要 用统一方式发现和调用能力，或工具所有权需要留在 server 边界之后时，适合使用 MCP。

CLI 适合本地开发工作流和 CI，但长时间运行的任务需要持久状态、取消和结果获取能力，不能只 依赖脆弱的子进程。只有远程一方负责自主执行任务时，agent 间集成才合理；如果对方只是一个 函数端点，就不适合。

分开发现、选择与执行 ​

mermaid
sequenceDiagram
    participant U as User identity
    participant H as Claude host
    participant R as Capability registry
    participant G as Authorization gate
    participant S as Service
    U->>H: Request with identity and purpose
    H->>R: Discover capabilities allowed for role
    R-->>H: Narrow tool definitions
    H->>H: Claude selects a tool
    H->>G: Tool, arguments, identity, context
    G->>G: Scope, policy, approval, freshness
    alt authorized
        G->>S: Execute with bounded credential
        S-->>G: Structured result
        G-->>H: Result plus audit reference
    else denied
        G-->>H: Structured non-retryable error
    end

发现控制模型能看到什么，授权控制实际会发生什么。两者缺一不可。

如果发现机制返回所有工具，模型会承担额外的上下文和选择成本，还会看到危险操作的说明。如果 缺少授权，隐藏工具只是一种遮掩，调用方仍可能直接访问端点。

传递身份，不要替换身份 ​

应用 API key 标识的是应用。它不会自动代表发起请求的真人用户或服务。

传递：

  • 身份主体 ID
  • 租户或组织
  • 经过身份验证的会话
  • 角色和 scope
  • 政策要求的用途或案件标识符
  • 高权限操作的审批引用
  • 请求 ID 和 trace ID

下游系统应依据可信身份声明自行作出授权决策。不要授予宽泛的服务凭证，再让 Claude 模拟用户 权限。

在四个层级应用最小权限 ​

  1. 工具集：只暴露当前任务和角色需要的能力。
  2. 工具 schema：只接受必要参数，并约束参数值。
  3. 凭证：只授予所需的服务 scope 和资源。
  4. 操作：执行时重新检查当前政策、对象所有权和审批状态。

权限会变化，审批会过期，工具定义可能在几分钟前就已加载。执行时授权是最后一道控制。

把审批设计成一种能力 ​

“先问用户”含义模糊。可靠的审批包含：

  • 拟执行的确切操作和参数
  • 预期影响和可逆性
  • 请求方身份
  • 审批方身份和权限
  • 到期时间
  • 单次使用或有限次数使用语义
  • 审计引用

审批后，只执行获批的那项确切操作。如果参数变化，就重新申请审批。

返回结构化错误 ​

工具的故障需要不同的恢复方式。

json
{
  "ok": false,
  "error": {
    "category": "authorization",
    "retryable": false,
    "message": "refunds:write scope is required",
    "safe_details": {
      "required_action": "request authorized human review"
    }
  }
}

类别可以包括验证、授权、未找到、冲突、速率限制、依赖、超时和内部错误。告诉 agent 是否可以 安全重试，以及什么变化能改变结果。不要返回原始堆栈跟踪、token 或包含机密的上游消息。

渐进式发现减少能力膨胀 ​

大型工具目录会消耗上下文，并增加选择错误。先加载一个小而稳定的工具集以及搜索或注册机制， 等任务明确需要时再加载专用工具。

渐进式发现仍应强制执行身份主体的 scope。搜索结果不能泄露调用方无权得知的能力名称或说明。

MCP scope 不等同业务授权 ​

MCP 对能力交换进行了标准化。身份、租户隔离、同意、审批、政策、审计和凭证管理仍由应用负责。 传输安全不等于授权，协议握手成功也不代表有权使用每个工具。

动手构建 ​

交互实验 ​

figure
25-identity-permission-path

使用权限路径探索器，跟踪身份如何从通过身份验证的请求开始，依次经过能力发现、模型选择、执行时 授权、审批、服务调用和审计。改变 scope 可以说明发现和授权为何是两项独立控制。

实践实验 ​

只授予发现 scope 并尝试执行，然后加入与操作绑定的审批，观察哪项决策发生了变化、哪道边界仍 在强制执行。

交付产物 ​

填写完成的 outputs/least-privilege-review.json 记录了可见工具， 以及一次被拒绝退款尝试的结构化结果。

验证 ​

复现该行为，并运行所有授权测试：

bash
cd certifications/claude/lessons/25-integration-protocols-identity-and-least-privilege/code
python3 main.py
python3 -m unittest discover tests -v

测验会检查协议、身份、审批和重试规则。

综合项目关联 ​

把这份报告作为 Architect Professional 综合项目中身份与最小权限的证据。

该实验使用 Python 标准库，清楚呈现这条边界。

bash
cd certifications/claude/lessons/25-integration-protocols-identity-and-least-privilege/code
python3 main.py
python3 -m unittest discover tests -v

第 1 步：选择主要形态 ​

select_protocol 要求指定一种主要集成需求。动态发现对应 MCP，本地自动化对应 CLI，远程自主 委派对应 agent 间集成，已知服务调用对应直接 API。需求含糊时会失败，迫使架构师澄清边界。

第 2 步：定义身份主体和工具契约 ​

Principal 携带 scope 和当前有效的审批。ToolContract 声明所需 scope、风险，以及是否要求 审批。说明文字负责解释行为，但不会授予权限。

第 3 步：过滤发现结果 ​

discover_tools 会移除超出身份主体 scope 的能力。负责起草回复的客服永远看不到删除账户工具。

第 4 步：在执行时授权 ​

authorize 检查当前 scope 和审批。检查失败时，execute_tool 会拒绝调用，并返回结构化、 不可重试的错误。

这个玩具系统没有实现基于密码学的身份机制、token 验证或政策引擎。这些能力属于生产基础设施， 但实验仍把授权决策放在正确的边界上。

上手使用 ​

针对客服系统，为每个角色创建专属工具包：

  • 分诊：读取分配的工单、分类、路由
  • 回复人员：读取工单和政策、写入草稿
  • 退款审核人：读取案件和建议、批准或拒绝
  • 退款执行人：只执行一项明确获批的操作
  • 管理员：在客服 agent 路径之外维护账户

不能因为一个服务有能力提供管理员工具，就把这些工具交给模型。高风险操作应该使用与获批操作 绑定的短期凭证，并产生不可变的审计记录。

选择 MCP 还是直接 API 时，编写一份 ADR 比较：

  • host 的数量和多样性
  • 是否需要动态发现
  • 延迟预算
  • 现有身份验证和 SDK 的成熟度
  • 部署和所有权边界
  • 流式或长时间运行行为
  • 可观测性和支持负担

协议是否流行，不是需求。

考试决策模式 ​

如果一个角色永远不需要某项能力，就把它从配置中移除。日志和确认属于补偿性控制，不是最小权限。

优先选择符合以下特征的答案：

  • 传递已验证身份的用户或服务身份
  • 严格限制工具和凭证的权限范围
  • 执行时重新授权
  • 高影响操作使用当前有效的审批
  • 返回分类明确、指明能否重试的错误
  • 根据集成边界选择协议
  • 工具目录很大时采用渐进式能力发现

不要选择那些假定更好的 prompt、更大的模型或成功建立 MCP 连接就能解决授权问题的答案。

常见陷阱 ​

所有用户共用一个服务账户 ​

下游服务只能看到宽泛的应用权限。每个用户的限制会退化成 prompt 政策，而不是可强制执行的 政策。

确认没有绑定操作 ​

用户批准退款 50 美元，之后参数却变成了 500 美元。审批必须与操作、参数、身份和时间绑定。

把工具说明当成控制措施 ​

说明文字有助于选择工具。从安全角度看，它们是不受信任的文本，本身也可能携带 prompt 注入。

重试授权错误 ​

重试不会创造权限。把错误标记为不可重试，并交给正确的审批或访问流程。

练习 ​

  1. 增加资源级授权，让身份主体只能读取分配给自己的工单。
  2. 创建一条经过签名、仅能使用一次的审批记录，并拒绝发生变化的参数。
  3. 定义渐进式发现接口，隐藏未授权工具的名称。
  4. 在 200 毫秒延迟预算下，比较三个内部服务使用 MCP 和直接 API 的效果。
  5. 对工具说明和结果进行红队测试，检查间接 prompt 注入。

关键术语 ​

术语人们常说的意思实际含义
身份验证操作权限身份的证明
授权登录决定该身份能否执行这项操作
Scope一条 prompt 规则由可信凭证或政策决策携带的有限权限
发现授权找到某项能力，与是否允许执行分开
最小权限增加确认移除不必要的能力，并尽可能收紧剩余权限边界
审批用户同意了针对确切操作参数、与身份和时间绑定的授权

延伸阅读 ​

  • MCP 规范，了解当前协议行为
  • MCP 授权规范，了解协议级授权要求
  • Claude 工具使用文档，了解当前工具契约
  • 阶段 13，第 05 课：schema 设计
  • 阶段 13，第 18 课：生产 MCP 身份验证
  • 阶段 17，第 25 课：机密和审计控制