如何设计安全的 Web API 访问

这张图其实在讲“安全访问 Web API”最常见的两条路：**Token（令牌）**和HMAC（签名）。它们解决的核心问题不一样：Token 更像“拿到一张通行证”，HMAC 更像“每次递交文件都盖防伪章”。

1) 图上半部分：Token-based authentication（令牌认证）

流程解读（图中 1→4）：

1. Client 把用户名/密码（或一次性验证码、OAuth 授权码等）发给Authentication Server

2. 认证通过，Auth Server 返回token（常见是 access token，可能还有 refresh token）

3. Client 携带 token 去请求Web Server

4. Web Server 校验 token（本地验签或去 Auth Server introspect），通过后返回资源

怎么把它设计“安全”（关键点在“token 被偷怎么办？”）：

• 必须全程 HTTPS/TLS：否则 token/密码在路上就是“裸奔”。

• Access Token 要短命：比如 5–15 分钟；并配套Refresh Token（更长，但更严格保护）。

• 最小权限（Scopes/Claims）：token 里只给需要的能力，例如read:pdf、convert:pdf，别一把梭“管理员”。

• 绑定目标（aud/iss）：校验iss（谁签发）/aud（给谁用）/exp（过期）/nbf（生效时间）。

• Token 存储要分场景

  • 浏览器端：优先 HttpOnly + Secure Cookie（降低 XSS 直接读 token 风险），再配合 CSRF 防护。

  • 原生/桌面/服务端：放系统安全存储（Windows Credential Manager、DPAPI、Keychain 等），不要写明文配置。

• 可撤销与轮换：refresh token 支持撤销（用户退出/泄露/风控），服务端支持密钥轮换（JWT 的kid）。

• 防暴力破解与风控：登录接口要限速、验证码/2FA、异常登录告警。

一句话：Token 方案更适合“用户登录态 / 第三方授权 / 多服务统一身份”。

2) 图下半部分：HMAC authentication（签名认证）

流程解读（图中 1→7）：

1. Client 向 Auth Server 申请API key（通常包括key_id+secret）

2. Client 拿到 API key（secret 只给一次/或可重置）

3. Client 本地用 secret 生成hmac A

4. Client 发送请求 + 签名到 Web Server

5. Web Server 用同一 secret 生成hmac B

6. 对比 hmac A 和 hmac B（相同则通过）

7. 返回资源

图里还强调：签名输入通常包含
appId、URI、body、HTTP method、timestamp、nonce+secret→ HMAC signature
这叫请求不可篡改（method/路径/body 被改签名就对不上）+防重放（timestamp/nonce）。

怎么把 HMAC 设计“安全可用”（关键点在“签名串怎么拼、重放怎么防”）：

• 定义“规范化请求（canonical request）”：双方必须完全一致，否则会出现“我算的签名永远不对”的噩梦。常见做法：

  • method 大写

  • path 原样（或统一 URL decode/encode 规则）

  • query 参数按 key 排序、统一编码

  • body 用SHA-256(body)放入签名（避免大 body 直接拼接）

• 把 timestamp + nonce 纳入签名，并做校验：