一次 API 调用可能涉及两套凭据
合作方已经通过接口签名,后端却返回认证失败,并不矛盾。平台验证“谁在调用我”,后端验证“谁在访问我的资源”,两次判断有不同的凭据、权限和撤销位置。
腾讯云后端资源凭据文档于 2026 年 10 月 15 日更新,明确把后端凭据用于网关访问资源时的出站认证。这是一个具体产品实例。本文的配置、响应及验收步骤均为通用设计示意,未经 YesAPI Pro 产品端点实测。
合作方服务端 ──应用签名或访问令牌──> API 平台
API 平台 ──后端服务凭据──────> 订单系统
<──业务结果─────────
合作方服务端 <──允许公开的响应────
调用方通常只持有自己应用的凭据。平台访问订单系统的密钥保留在受控服务端,不能发给合作方,也不能放进浏览器代码。签名中的应用标识可用于查找密钥,密钥本身不随请求发送;Bearer 令牌则由持有者直接出示。两种方式都需要 HTTPS。
先写清身份和权限的对应关系
入站鉴权成功,只能证明请求符合某个应用的认证规则。是否允许查询订单、查询哪个租户,仍需业务授权。OWASP REST 安全指南要求受保护端点执行访问控制,不能只靠一个通用 API Key 保护敏感资源。
建议为一个只读订单接口建立以下关系,再配置转发。
| 对象 | 通用示例 | 必须确定的边界 |
|---|---|---|
| 调用应用 | partner-a-prod |
归属合作方 A,仅可读订单 |
| 可信身份映射 | 应用 A 对应租户 tenant-a |
来自服务端登记,调用方不能自行覆盖 |
| 后端服务账户 | gateway-order-reader |
仅有必要接口权限,不具备管理员权限 |
| 后端凭据引用 | orders/prod/reader-v2 |
对应生产资源,不与测试共用 |
| 业务对象规则 | 订单必须属于 tenant-a |
每次请求校验,不能只校验接口名称 |
如果服务账户能读取多个租户,后端还需验证可信租户上下文和对象归属。客户端传来的 X-Tenant-Id 不能直接成为授权依据;平台应移除伪造值,再通过受保护链路传递已验证的身份,或使用后端能够验证的委托令牌。
配置凭据时,把值与路由分开
下面是便于评审的伪配置,不对应 YesAPI Pro 控制台字段或可执行配置文件。
route: order-read
inbound:
application: partner-a-prod
permission: orders:read
tenant_from: verified_application_mapping
outbound:
origin: https://orders.example.invalid
method: GET
path: /v1/orders/{order_id}
credential_ref: orders/prod/reader-v2
forward_inbound_authorization: false
实施时先创建权限受限的后端账户,将凭据值写入受控秘密管理设施,再让运行服务以必要权限读取。路由、工单和普通日志只记录凭据引用及版本。生产与测试分别使用账户、资源地址和凭据,避免一次错误发布跨环境访问。
转发前应显式处理认证头:移除不应转交的入站 Authorization,再按目标后端协议构造出站认证。不能让同名请求头意外覆盖凭据,也不能允许调用方通过参数选择任意后端地址或密钥引用。
通用请求示意:应用 A 查询 A-1001,平台验证应用、接口权限及租户关系后,使用后端只读凭据访问订单系统。响应仅包含允许公开的字段。
{ "order_id": "A-1001", "status": "paid", "request_id": "req-demo-001" }
同一应用改查其他租户的 B-2001,应得到按项目约定的拒绝或隐藏资源响应,不能因后端服务账户权限较大而放行。
轮换要验证新值,也要证明旧值失效
OWASP 秘密管理指南把创建、轮换、撤销和过期作为凭据生命周期,并建议限制权限、避免明文日志。下列轮换顺序是项目实施建议,前提是后端允许新旧凭据短时并存。
- 在后端签发新凭据,确认资源、账户与权限正确;记录变更单和负责人。
- 使用新版本完成只读探测,同时验证越权请求被拒绝。
- 更新平台引用或配置,检查所有实例和连接使用的新版本;保留不含密钥的发布证据。
- 观察成功率及认证错误,超过约定阈值时停止扩大变更。只有旧凭据未泄露且仍有效时,才可按预案回退。
- 在后端撤销旧凭据,并用旧值做受控失败验证;清理缓存、部署变量和临时副本。
若后端只支持一把密钥,需安排协调切换窗口,不能照搬双凭据流程。发生泄露时,优先在实际签发方撤销;删除平台配置、重启服务或恢复旧版本,都不等于令牌已经失效。
入站应用凭据的轮换独立执行。停用合作方 A 后,A 的新请求应被拦截,其他合作方继续访问;撤销共享后端凭据则可能影响多个应用,必须提前列明关联范围。
用失败分支完成交付验收
以下结果为建议验收目标,错误码、缓存生效时限和记录字段需写入项目约定。
| 验收输入或操作 | 应验证的结果 | 核对位置 |
|---|---|---|
| 正确应用、允许接口、己方订单 | 返回允许字段,关联 ID 可追踪 | 平台与后端 |
| 错误签名或已撤销应用 | 不发起后端业务调用 | 入站鉴权记录 |
| 正确应用查询其他租户订单 | 拒绝且不泄露订单内容 | 业务授权记录 |
| 测试凭据误配生产路由 | 被配置检查或后端权限拒绝 | 环境配置与后端 |
| 后端凭据过期 | 识别出站认证故障,不要求调用方无限换密钥 | 平台与签发方 |
| 新凭据发布后撤销旧值 | 新值成功,旧值失败,其他应用影响符合预期 | 全部运行实例 |
| 导出日志、复制报错详情 | 没有完整密钥、认证头或敏感业务正文 | 日志与运维工具 |
排障时先按关联 ID 判断失败发生在哪一段。后端返回 401,不能自动解释为合作方凭据有误;平台应按公开错误契约表达依赖认证故障,并由维护出站凭据的负责人处理。写操作认证失败或超时,也不能未经结果核对就自动换密钥重发。
在选型中确认由谁负责哪一层
YesAPI Pro 已确认的相关能力包括接口签名、应用权限和日志统计,可从 API 管理功能与 API 开放平台了解。独立后端凭据仓库、自动轮换、熔断切换尚未确认,不能由其他厂商文档推定产品内置。
准备演示时,可带上一个脱敏接口、两类应用身份和轮换验收表,通过联系页面逐项确认由平台配置、业务后端或外部秘密管理设施承担。涉及 Agent 适配的团队可继续阅读 REST API 转 MCP 的权限清单。
参考资料
以下为本文引用的官方资料。文中的通用示例与产品套餐能力分别说明。
接下来,如何选型?
把上下游身份,分别列入接入需求。
从开发者应用与接口权限核对接入方式。后端凭据仓库、自动轮换与切换机制需要按项目确认。
- 分别列出调用方身份、平台权限与后端凭据的责任方。
- 用环境隔离、撤销和轮换样例验证实际行为。