跳到主要内容

API 身份认证

当前商业试点使用与角色绑定的 Bearer 凭据实现身份体系，每个凭据对应一个可追责参与者和一个相互隔离的流程角色。

已实现行为​

  • 请求使用 Authorization: Bearer <token>。
  • Token 必须包含 32 至 256 个无空格的可打印 ASCII 字符。
  • 私有凭据文件只保存 Token 的 SHA3-256 摘要。
  • 每个凭据映射到一个参与者 ID 和唯一一个角色。
  • 参与者身份由服务器根据凭据确定，状态变更时间由服务器时钟确定；请求不能自行提交这两个字段。
  • 缺少或使用无效凭据返回 401 Unauthorized；有效参与者执行角色以外的操作返回 403 Forbidden。
  • 操作控制台把 Token 保存在浏览器 sessionStorage，关闭标签页后即清除。

支持的角色为 initiator、approver、security_admin、executor 和 auditor。同一个凭据不能合并多个角色。

凭据记录​

{
  "schema_version": 1,
  "credentials": [
    {
      "actor_id": "partner-approver-01",
      "roles": ["approver"],
      "token_sha3_256": "<64 个小写十六进制字符>"
    }
  ]
}

在代码仓库外生成秘密 Token 及其存储摘要：

TOKEN=$(openssl rand -hex 32)
printf '%s' "$TOKEN" | openssl dgst -sha3-256

明文 Token 通过双方认可的秘密传输渠道交付给指定参与者。不得把它提交到代码仓库、写入证据导出、放入 URL 查询参数或复制到支持日志。

接入核验​

安装私有凭据文件并启动试点服务后，参与者核验自己的身份和角色：

curl https://<pilot-host>/v1/session \
  -H "Authorization: Bearer $TOKEN"

返回的参与者 ID 和角色必须与双方批准的角色表一致，之后才能开始流程测试。

试点轮换流程​

  1. 生成新的随机 Token 和摘要。
  2. 在私有凭据文件中为同一参与者和角色加入替代摘要。
  3. 重启受控试点服务，并用新 Token 验证 /v1/session。
  4. 删除旧摘要，再次重启，并确认旧 Token 返回 401。
  5. 在凭据文件外记录变更时间、操作人、参与者和验证结果。

当前服务在启动时加载凭据，因此试点轮换通过受控文件更新和服务重启完成。

生产要求​

企业部署配置将增加双方确定的 TLS 或私有服务网格终止方式、秘密管理系统归属、自动过期与撤销、限流、凭据轮换证据，以及 OAuth、合作方 mTLS、工作负载身份或硬件保护凭据等身份机制。