标识、凭据与回调的分工
四类信息承担不同职责。标识说明目标,凭据说明调用方,回调地址接收验证与通知,授权范围限定可调用的字段与期限;混用会让排查无法判断环节。
标识可以对调用方可见,凭据必须保密。回调地址由开发方维护,修改后重新验证;授权范围由目标主体确认,调整时提交授权事项,不自行扩大。
| 对象 | 作用 | 可见范围 | 变更方式 |
|---|---|---|---|
| Agent 标识 | 识别目标 Agent | 开发方与调用方可见 | 登记信息更新 |
| 调用凭据 | 证明调用方身份 | 仅调用方保管 | 签发、轮换、停用 |
| 回调地址 | 接收验证与通知 | 开发方维护 | 修改后重新验证 |
| 授权范围 | 限定可调用字段与期限 | 目标主体确认 | 提交授权调整 |
签发与首次保存
创建 Agent 时签发沙箱凭据,联调通过后签发正式凭据。凭据明文只在创建时显示一次,之后只显示凭据标识;没有当场保存,只能停用后重建。
首次保存应当进入受控的密钥管理位置,不落在代码、配置文件明文或共享文档中。保存后立即核对一次调用,确认凭据可用,也确认调用方配置已经指向正确环境。
- 凭据不写入前端代码与客户端安装包。
- 凭据不提交到公开仓库,不粘贴到工单与聊天记录。
- 凭据不记录在日志与错误信息中。
- 不同 Agent 使用独立凭据,便于单独停用。
- 沙箱凭据与正式凭据分开保管,不交叉使用。
- 保存后核对一次调用,确认环境与凭据匹配。
轮换安排
凭据设置有效期,到期前签发新凭据。新旧凭据在一段时间内同时可用,便于调用方平滑切换;轮换完成后停用旧凭据,并核对调用记录,确认请求已使用新凭据。
轮换不要等到过期当天处理。提前部署新凭据,留出核对时间,可以避免切换过程中出现调用中断。
- 在到期前创建新凭据,确认新凭据只在创建时显示。
- 把新凭据部署到调用方,完成一次调用核对。
- 观察调用记录,确认请求已使用新凭据。
- 停用旧凭据,确认停用立即生效。
- 保留轮换时间与操作人,便于事后核对。
- 轮换完成后核对旧凭据是否已停用,避免新旧凭据长期并存。
回调地址的验证
回调地址用于接收验证与通知。创建 Agent 时填写的地址需要能够接收验证;修改后重新验证,验证未完成前不用于正式调用。
回调地址不可达时,验证无法完成,登记信息处于未确认状态。先修复可达性,再重新发起验证;用临时调试地址通过验证,后续仍会因地址失效而中断。
- 回调地址使用可长期维护的地址,不使用临时调试地址。
- 地址变更与端点变更分开提交,避免一次改动覆盖两类信息。
- 验证失败时保留失败时间与返回信息,便于定位。
- 多个 Agent 的回调地址分别登记,不混用。
- 验证完成后再用于正式调用,未验证前不接收正式流量。
停用、重建与注销
停用与注销的影响不同。停用立即停止调用但保留记录,重新启用时版本递增;注销后标识不再复用,凭据同时停用,需要继续使用时按首次接入重新办理。
重建凭据只替换身份证明,不改变标识与登记信息。重建后同样只在创建时显示一次,旧凭据不再使用;重建前确认调用方已经准备好接收新凭据。
| 操作 | 影响 | 记录与后续 |
|---|---|---|
| 停用凭据 | 调用立即停止 | 记录保留,可重新签发 |
| 重建凭据 | 生成新凭据,明文只显示一次 | 旧凭据不再使用 |
| 停用 Agent | 停止对外提供调用 | 记录保留,恢复后版本递增 |
| 注销 Agent | 标识不再复用 | 凭据同时停用,按首次接入重新办理 |
泄露与异常调用处置
怀疑凭据泄露或出现异常调用时,先控制影响,再核对记录。处置顺序稳定,才能判断影响范围;没有保留记录就删除凭据,后续无法确认异常请求来自哪里。
处置完成后复核凭据、回调与授权范围,确认没有遗留旧配置。涉及多个 Agent 时分别核对,避免只处理其中一个而留下同类风险。
- 停用相关凭据,阻止继续调用。
- 保留调用记录,记录异常时间、调用方与目标标识。
- 核对授权范围与回调地址,确认没有遗留的旧配置。
- 按需重建凭据,重新完成一次调用核对。
- 涉及多个 Agent 时分别核对,确认同类风险已经处理。
多人协作的保管约定
凭据按用途分配给具体系统或服务,不按个人长期持有。人员变动时先停用其对应凭据,再按需签发;共享凭据看似方便,停用时却无法判断影响哪些调用。
回调验证与凭据轮换都写入操作记录,交接时把凭据标识、有效期与下次轮换时间一并说明。接收方按记录核对,不需要重新梳理历史操作。
- 凭据可以多人共用吗
- 不建议。按调用系统分别签发,便于单独停用与核对。
- 回调地址可以随时修改吗
- 可以。修改后需要重新验证,验证完成前不用于正式调用。
- 凭据丢失后能找回原值吗
- 不能。停用原凭据后重新签发,新凭据同样只在创建时显示一次。