| name | metaframe-api-security-patterns |
|---|---|
| category | security |
| description | API 安全模式 | Security & Privacy |
英文名: API Security Patterns
分类: API 设计与集成
作者: OWASP Foundation
复杂度: advanced
成熟度: foundational
AI 相关: ✅ 是
通过 OAuth2 范围、API 密钥、JWT 验证和 CORS 强化保护 API 表面免受未授权访问
- OAuth2 范围与最小权限：在资源-操作级别定义权限范围（如 accounts:read），并仅向特定客户端集成颁发所需范围的令牌，在令牌泄露时将影响范围降至最低
- JWT 验证链：完整的验证序列——签名验证、声明检查（exp、iss、aud）、算法限制——所有环节必须通过才能授权请求；跳过任何一步都会产生可利用的漏洞
- BOLA（对象级授权缺失）：最普遍的 API 漏洞，API 在不检查认证用户是否拥有或有权访问的情况下返回 URL 中任意 ID 的数据
- CORS 策略强化：跨源资源共享错误配置（通配符来源与凭证、过度宽松的方法）允许恶意网页代表浏览器用户发起认证 API 调用
- 服务间 mTLS：双向 TLS 认证，客户端和服务端都出示证书，为零信任环境中高安全性内部 API 通信提供密码学身份证明
- 按敏感程度对所有 API 端点分类，选择合适的认证机制：API 密钥用于服务间集成，OAuth2 客户端凭证用于机器对机器流程，OAuth2 授权码 + PKCE 用于用户授权访问，mTLS 用于高安全性服务网格通信
- 实施细粒度的 OAuth2 范围遵循最小权限原则：在资源和操作级别定义范围（如 orders:read、orders:write、payments:create），并在每个受保护的处理程序中执行范围检查
- 严格验证 JWT：使用颁发者的公钥验证签名，检查 exp、nbf、iss 和 aud 声明，拒绝 algorithm: none 的令牌，并通过快速查找黑名单或短过期窗口实现令牌吊销
- 强化 CORS 配置：明确白名单允许的来源（避免对凭证请求使用通配符 *），限制允许的方法和头部，设置 Access-Control-Max-Age 头部以减少预检请求频率
- 应用 OWASP API 安全 Top 10 缓解措施：对每个资源执行对象级授权（BOLA）、实施速率限制和配额执行、用严格模式验证所有输入载荷，以及记录所有认证事件用于审计和异常检测
['当设计任何向外部消费者暴露敏感数据、金融操作或用户授权行为的 API 时', '当安全审计或渗透测试发现了认证弱点（缺失授权检查、过于宽松的 CORS、弱令牌验证）时', '当与需要标准化令牌认证（OAuth2/OIDC）的第三方系统集成时', '当合规框架（PCI-DSS、HIPAA、SOC 2）要求有文档记录的 API 认证和授权控制时']
- 在每次请求时验证完整的 JWT 声明集——签名、过期时间、颁发者和受众——使用维护良好的库，而非编写自定义 JWT 验证代码
- 在每个返回或修改特定资源的 API 处理程序中实施对象级授权检查，而非仅在路由/控制器层面
- 定期轮换 API 密钥和客户端密钥，并提供自助密钥轮换机制，使客户端无需停机即可轮换
- 用结构化字段（client_id、endpoint、error_code）记录每次认证失败、令牌验证错误和授权拒绝，用于安全监控和事件响应
- 不要对低敏感度内部工具以外的任何场景使用 HTTP Basic Auth 或查询参数中的 API 密钥——两者都容易在日志、浏览器历史和 Referer 头部中泄露
- 不要在未针对授权数据库验证的情况下信任 JWT 载荷中客户端提供的声明（user_id、role、is_admin）——任何持有令牌的人都可以读取 JWT 载荷数据
- 不要将 CORS 配置为 Access-Control-Allow-Origin: * 同时配合 Access-Control-Allow-Credentials: true——浏览器会阻止这种组合，如果以某种方式被接受则会允许任何站点发起凭证请求
- 不要对认证端点（登录、令牌交换）跳过速率限制——凭证填充和暴力破解攻击专门针对未节流的认证端点
Sources: SDFrame (Software Design) MetaFrame: 🔒 Security & Privacy / 安全与隐私