凭据与回调管理

凭据证明调用方身份,回调地址接收验证与通知。两者都需要在创建时确认、在变更时复核;凭据只在创建时显示一次,回调地址修改后必须重新验证,验证完成前不用于正式调用。轮换与验证结果可在凭据记录中核对。

标识、凭据与回调的分工

四类信息承担不同职责。标识说明目标,凭据说明调用方,回调地址接收验证与通知,授权范围限定可调用的字段与期限;混用会让排查无法判断环节。

标识可以对调用方可见,凭据必须保密。回调地址由开发方维护,修改后重新验证;授权范围由目标主体确认,调整时提交授权事项,不自行扩大。

对象作用可见范围变更方式
Agent 标识识别目标 Agent开发方与调用方可见登记信息更新
调用凭据证明调用方身份仅调用方保管签发、轮换、停用
回调地址接收验证与通知开发方维护修改后重新验证
授权范围限定可调用字段与期限目标主体确认提交授权调整

签发与首次保存

创建 Agent 时签发沙箱凭据,联调通过后签发正式凭据。凭据明文只在创建时显示一次,之后只显示凭据标识;没有当场保存,只能停用后重建。

首次保存应当进入受控的密钥管理位置,不落在代码、配置文件明文或共享文档中。保存后立即核对一次调用,确认凭据可用,也确认调用方配置已经指向正确环境。

  • 凭据不写入前端代码与客户端安装包。
  • 凭据不提交到公开仓库,不粘贴到工单与聊天记录。
  • 凭据不记录在日志与错误信息中。
  • 不同 Agent 使用独立凭据,便于单独停用。
  • 沙箱凭据与正式凭据分开保管,不交叉使用。
  • 保存后核对一次调用,确认环境与凭据匹配。

轮换安排

凭据设置有效期,到期前签发新凭据。新旧凭据在一段时间内同时可用,便于调用方平滑切换;轮换完成后停用旧凭据,并核对调用记录,确认请求已使用新凭据。

轮换不要等到过期当天处理。提前部署新凭据,留出核对时间,可以避免切换过程中出现调用中断。

  1. 在到期前创建新凭据,确认新凭据只在创建时显示。
  2. 把新凭据部署到调用方,完成一次调用核对。
  3. 观察调用记录,确认请求已使用新凭据。
  4. 停用旧凭据,确认停用立即生效。
  5. 保留轮换时间与操作人,便于事后核对。
  6. 轮换完成后核对旧凭据是否已停用,避免新旧凭据长期并存。

回调地址的验证

回调地址用于接收验证与通知。创建 Agent 时填写的地址需要能够接收验证;修改后重新验证,验证未完成前不用于正式调用。

回调地址不可达时,验证无法完成,登记信息处于未确认状态。先修复可达性,再重新发起验证;用临时调试地址通过验证,后续仍会因地址失效而中断。

  • 回调地址使用可长期维护的地址,不使用临时调试地址。
  • 地址变更与端点变更分开提交,避免一次改动覆盖两类信息。
  • 验证失败时保留失败时间与返回信息,便于定位。
  • 多个 Agent 的回调地址分别登记,不混用。
  • 验证完成后再用于正式调用,未验证前不接收正式流量。

停用、重建与注销

停用与注销的影响不同。停用立即停止调用但保留记录,重新启用时版本递增;注销后标识不再复用,凭据同时停用,需要继续使用时按首次接入重新办理。

重建凭据只替换身份证明,不改变标识与登记信息。重建后同样只在创建时显示一次,旧凭据不再使用;重建前确认调用方已经准备好接收新凭据。

操作影响记录与后续
停用凭据调用立即停止记录保留,可重新签发
重建凭据生成新凭据,明文只显示一次旧凭据不再使用
停用 Agent停止对外提供调用记录保留,恢复后版本递增
注销 Agent标识不再复用凭据同时停用,按首次接入重新办理

泄露与异常调用处置

怀疑凭据泄露或出现异常调用时,先控制影响,再核对记录。处置顺序稳定,才能判断影响范围;没有保留记录就删除凭据,后续无法确认异常请求来自哪里。

处置完成后复核凭据、回调与授权范围,确认没有遗留旧配置。涉及多个 Agent 时分别核对,避免只处理其中一个而留下同类风险。

  1. 停用相关凭据,阻止继续调用。
  2. 保留调用记录,记录异常时间、调用方与目标标识。
  3. 核对授权范围与回调地址,确认没有遗留的旧配置。
  4. 按需重建凭据,重新完成一次调用核对。
  5. 涉及多个 Agent 时分别核对,确认同类风险已经处理。

多人协作的保管约定

凭据按用途分配给具体系统或服务,不按个人长期持有。人员变动时先停用其对应凭据,再按需签发;共享凭据看似方便,停用时却无法判断影响哪些调用。

回调验证与凭据轮换都写入操作记录,交接时把凭据标识、有效期与下次轮换时间一并说明。接收方按记录核对,不需要重新梳理历史操作。

凭据可以多人共用吗
不建议。按调用系统分别签发,便于单独停用与核对。
回调地址可以随时修改吗
可以。修改后需要重新验证,验证完成前不用于正式调用。
凭据丢失后能找回原值吗
不能。停用原凭据后重新签发,新凭据同样只在创建时显示一次。

把凭据与回调管起来

按用途签发凭据,提前安排轮换,回调变更后重新验证,异常时先停用再核对记录。

查看安全与合规