标识与凭据
标识与凭据承担不同职责,混用会增加冒用与误调用的风险。调用方标识说明发起请求的主体,授权范围说明可调用的字段与期限,由目标 Agent 主体确认;鉴权时几类信息一起核对,缺少任何一项都不返回端点。
鉴权结果只说明本次请求能否继续,不代表对后续请求的长期授权。授权范围调整后,调用方需要按新范围准备字段;凭据轮换后,旧凭据在约定时间内仍可用,便于切换。
| 对象 | 作用 | 谁持有 |
|---|---|---|
| Agent 标识 | 识别目标 Agent | 开发方与调用方可见 |
| 调用方标识 | 识别发起调用的主体 | 调用方持有 |
| 调用凭据 | 证明调用方身份 | 调用方保管,不公开 |
| 授权范围 | 说明可调用的字段与期限 | 目标 Agent 主体确认 |
鉴权顺序
鉴权按固定顺序判断,任一步失败都会返回明确错误,且不返回端点。调用方根据错误类型处理,不重复提交相同请求;需要变更凭据或授权时,按登记与调整流程办理后再试。
鉴权失败不返回端点,也不提示目标的具体配置。调用方按错误类型补充材料或调整范围,避免通过多次尝试探测目标信息。
- 校验调用方标识与凭据。
- 校验目标 Agent 标识与状态。
- 判断调用方是否在授权范围内。
- 返回目标端点与可用字段。
- 写入调用记录。
凭据生命周期
创建 Agent 时生成沙箱凭据,联调通过后生成正式凭据。凭据设置有效期,到期前签发新凭据,新旧凭据在一段时间内同时可用,避免调用中断;轮换完成后停用旧凭据,并核对调用记录是否正常。
凭据只在创建时显示一次,之后只显示凭据标识。丢失或泄露时停用并重建,不尝试找回原值;停用立即生效,重建后的凭据同样只在创建时显示一次。
保管要求
凭据等同于调用方身份的证明,保管方式直接影响调用安全。测试凭据与正式凭据分开管理,不同 Agent 使用独立凭据,便于单独停用;成员离开或系统下线时,及时停用对应凭据。
- 不写入前端代码。
- 不提交到公开仓库。
- 不记录在日志与错误信息中。
- 不通过聊天工具或邮件明文传递。
- 停用操作立即生效,无需等待。
常见疑问
- Agent 标识需要保密吗
- 标识用于识别目标,可以对调用方可见;调用凭据用于证明身份,必须保密。
- 调用方标识与凭据有什么区别
- 调用方标识说明是谁发起调用,凭据证明该身份真实有效,两者需要同时提交。
- 授权范围由谁确认
- 由目标 Agent 主体确认;范围需要调整时提交授权调整,不自行扩大。
- 凭据到期会立即失效吗
- 到期前签发新凭据,新旧凭据在一段时间内同时可用,便于平滑切换。
- 凭据可以多人共用吗
- 不建议。按调用方或系统分配独立凭据,出现异常时可以单独停用并核对记录。