API 安全最佳实践：身份验证、授权和速率限制

API 是现代商业平台的结缔组织。您的 ERP 通过 API 与您的电子商务商店进行通信。您的支付网关通过 API 处理交易。您的移动应用程序通过 API 获取数据。攻击者也知道这一点：Gartner 预测，到 2026 年，API 将超过传统 Web 界面，成为企业 Web 应用程序最常见的攻击媒介。

OWASP API 安全十大漏洞表明，最常见的 API 漏洞并不是外来的零日漏洞，而是根本性的身份验证失败、授权破坏和过多的数据泄露。这些都是可预防的缺陷，源于不完善的安全架构，而不是复杂的攻击。

要点

• OAuth2 与 PKCE 是 API 身份验证的当前标准；仅 API 密钥不足以满足生产系统的需要
• 破坏对象级授权 (BOLA) 是头号 API 漏洞 --- 每个端点都必须验证资源所有权
• 速率限制是一种安全控制，而不仅仅是性能优化 --- 它可以防止撞库、枚举和 DoS
• API 边界的输入验证可防止注入、溢出和业务逻辑攻击到达您的数据库

---

身份验证：证明身份

身份验证回答了“谁发出此请求？”的问题。对于 API，答案必须是可加密验证的、能够抵抗重放攻击并且能够跨分布式系统扩展。

认证方式比较

OAuth2 和 OIDC 最佳实践

OAuth2 与 OpenID Connect (OIDC) 是现代应用程序中 API 身份验证的标准。主要实施实践：

将授权代码流程与 PKCE 结合使用适用于所有客户端类型，包括单页应用程序和移动应用程序。由于浏览器历史记录和引用标头中的令牌暴露，隐式流已被弃用。

**短期访问令牌。**访问令牌应在 15-60 分钟内过期。使用刷新令牌（安全存储，轮换使用）来获取新的访问令牌，而无需重新身份验证。

**令牌存储。**切勿将令牌存储在 localStorage 或 sessionStorage 中（容易受到 XSS 攻击）。使用具有 Secure 和 SameSite 属性的 HttpOnly cookie。对于必须直接使用令牌的 SPA，仅将它们保存在内存中并接受页面刷新时会话丢失的权衡。

彻底验证令牌。 每个 API 请求都必须验证令牌的签名、过期时间、颁发者、受众和范围。不要简单地解码 JWT 并信任其内容。

令牌绑定。 在可能的情况下，使用 DPoP（演示所有权证明）标头将令牌绑定到请求令牌的客户端，以防止令牌被盗和重放。

JWT 安全注意事项

JWT 是 API 最常见的令牌格式，但它们具有特定的风险：

• 切勿使用 none 算法。 始终根据预期算法的白名单验证 alg 标头。
• 对于面向公众的 API，优先选择非对称算法（RS256、ES256），而不是对称算法（HS256）。非对称密钥允许在不共享签名密钥的情况下进行令牌验证。
• 包括标准声明： iss（发行人）、aud（受众）、exp（过期）、iat（发行于）、sub（主题）、jti（用于撤销的唯一 ID）。
• 保持有效负载较小。 JWT 不是数据库。仅包括授权决策所需的声明。需要时从用户信息端点获取附加数据。
• 实施令牌撤销。 使用较短的过期时间与令牌阻止列表（在 Redis 或类似的中）相结合，以便在帐户受到威胁时立即撤销。

---

授权：实施访问控制

身份验证会告诉您谁在发出请求。授权告诉您他们可以做什么。 OWASP API Top 10 将破坏对象级授权 (BOLA) 列为排名第一的 API 漏洞，因为它是最常见且影响最大的。

RBAC 与 ABAC

基于角色的访问控制 (RBAC) 将权限分配给角色，并将用户分配给角色。它的实现和推理都很简单。

基于属性的访问控制 (ABAC) 针对用户、资源、操作和环境的属性评估策略。它支持更复杂的规则，但更难审核。

对于大多数业务平台（包括 ERP 和电子商务系统），RBAC 与资源所有权检查相结合就足够了。当您的授权规则取决于时间、位置、数据分类或动态组织层次结构等上下文因素时，请考虑 ABAC。

预防 BOLA

当 API 允许用户通过操纵资源标识符来访问或修改属于其他用户的资源时，就会发生对象级授权被破坏的情况。例如，将 /api/orders/12345 更改为 /api/orders/12346 不应泄露其他用户的订单。

预防规则：

1. 每个端点都必须验证资源所有权。 切勿仅依赖身份验证。验证用户身份后，验证他们是否有权访问所请求的特定资源。
2. 使用间接引用。 使用 UUID 或用户范围的引用号，而不是公开顺序数据库 ID。
3. 在数据层强制执行。 将所有权过滤器（例如 WHERE organization_id = ?）添加到每个数据库查询，而不仅仅是在控制器级别。这是ECOSIRE 平台架构 中使用的多租户模式。
4. 自动化测试。 在 CI/CD 管道中包含授权绕过测试。对于每个端点，测试用户 A 是否无法访问用户 B 的资源。

---

速率限制和节流

速率限制是一种防止滥用的安全控制，而不仅仅是防止过载的性能优化。如果没有速率限制，攻击者可以每秒尝试数千次执行凭证填充、枚举有效帐户、抓取整个产品目录或耗尽上游提供商的 API 配额。

速率限制策略

按端点类型进行速率限制

不同的端点面临不同的威胁概况并需要不同的限制：

• 身份验证端点（登录、令牌交换）：每个 IP 每分钟 5-10 个请求。低限制可以防止撞库和暴力破解。
• 密码重置/帐户恢复：每个帐户每小时 3-5 个请求。防止帐户枚举和滥用。
• 数据读取端点：每个用户每分钟 100-1000 个请求。防止刮擦，同时允许正常使用。
• 数据写入端点：每个用户每分钟 30-60 个请求。防止自动滥用和垃圾邮件。
• 公共搜索端点：每个 IP 每分钟 20-60 个请求。防止竞争性抓取。
• Webhook 接收器：验证签名而不是速率限制，但丢弃超出预期数量的请求。

实施速率限制

返回正确的 HTTP 状态代码和标头，以便客户端可以自我调节：

• 429 请求过多 超出限制时
• Retry-After 标头，其中包含限制重置之前的秒数
• X-RateLimit-Limit 标头显示允许的请求总数
• X-RateLimit-Remaining 标头显示窗口中剩余的请求
• X-RateLimit-Reset 窗口重置时带有 UTC 时间戳的标头

使用集中式速率限制服务（Redis 支持）而不是按实例限制来防止攻击者跨实例分发请求以绕过限制。

---

输入验证

API 边界的输入验证是抵御注入攻击、缓冲区溢出和业务逻辑利用的第一道防线。输入 API 的每条数据都必须经过类型、格式、长度、范围和业务规则的验证。

OWASP API 安全性前 10 名

OWASP API 安全 Top 10（2023 版）确定了每个 API 必须解决的关键风险：

验证最佳实践

架构验证。 定义请求架构（使用 JSON Schema、Zod 或 OpenAPI 规范）并拒绝任何不符合要求的请求。这可以在格式错误的数据到达业务逻辑之前捕获它。

参数化查询。 切勿将用户输入连接到 SQL、NoSQL 或 LDAP 查询中。使用参数化查询或自动处理转义的 ORM 方法。这是适用于所有业务平台的关键安全规则。

内容类型强制。 仅接受预期的 Content-Type 标头。需要 JSON 的 API 应拒绝 XML、表单数据和其他内容类型，以防止基于解析器的攻击。

响应过滤。 切勿将完整的数据库记录返回给客户端。使用 DTO（数据传输对象）显式定义每个响应中包含哪些字段。密码哈希、内部 ID 和审核元数据等内部字段不应出现在 API 响应中。

错误处理。 将通用错误消息返回给客户端。切勿暴露堆栈跟踪、数据库错误或内部系统详细信息。在服务器端记录详细错误以进行调试。

---

API 安全架构模式

API网关模式

API 网关位于所有后端服务的前面，集中处理跨领域的安全问题：

• 身份验证 --- 在请求到达后端服务之前验证令牌
• 速率限制 --- 在网关级别强制实施限制
• 请求/响应转换 --- 剥离敏感标头，添加安全标头
• 日志记录和监控 --- 捕获所有 API 流量以进行安全分析
• WAF 集成 --- 阻止已知的攻击模式（SQL 注入、XSS 有效负载）

流行的 API 网关包括 Kong、AWS API Gateway、Azure API Management 和 Traefik。

服务到服务的身份验证

微服务之间的内部 API 也需要身份验证。选项包括：

• 相互 TLS (mTLS) --- 客户端和服务器都提供证书。功能强大但操作复杂。
• 服务令牌 --- 服务使用预共享令牌进行身份验证。简单但需要安全分发。
• 服务网格 --- Istio 或 Linkerd 自动处理 Kubernetes 中服务之间的 mTLS。
• OAuth2 客户端凭据 --- 服务使用客户端 ID 和密钥进行身份验证以获取访问令牌。

对于零信任架构，服务间身份验证对于防止违规后的横向移动至关重要。

---

监控和事件检测

API 安全监控必须捕获技术信号（失败的身份验证尝试、异常请求模式）和业务信号（异常交易金额、批量数据访问）。

关键 API 安全信号

• 身份验证失败 --- 从单个 IP 或针对单个帐户登录失败的次数激增
• 授权失败 --- 403 响应表明用户试图访问未经授权的资源
• 速率限制违规 --- 来自同一来源的持续 429 响应
• 异常数据量 --- 表明数据泄露的批量读取操作
• 参数篡改 --- 顺序ID枚举、负值、边界测试
• 地理异常 --- 来自意外区域或不可能的旅行模式的 API 调用

构建实时显示这些信号的仪表板。与您的 SIEM 集成以与其他安全事件关联。定义针对高可信度威胁的自动响应：阻止超过失败身份验证阈值的 IP、暂时禁用表现出不可能旅行的帐户，并对批量数据访问模式发出警报。

---

常见问题

我应该使用 API 密钥还是 OAuth2 令牌？

将 OAuth2 令牌用于为面向用户的应用程序或第三方集成提供服务的任何 API。 API 密钥仅适用于服务器到服务器的通信，其中两个端点都在您的控制之下，即使如此，HMAC 签名的请求也提供了更强的安全性。切勿使用 API 密钥作为可公开访问端点的唯一身份验证。

如何安全地处理 API 版本控制？

为了清晰和可发现性，使用基于 URL 的版本控制（例如 /api/v2/orders）。弃用版本时，设置日落日期，将其传达给消费者并监控使用情况。继续对已弃用的版本应用安全补丁，直到它们完全停用。永远不要让未打补丁的旧 API 版本继续运行——它们很容易成为攻击目标。

我应该为业务 API 设置什么速率限制？

开始保守，然后根据合法使用数据增加。对于身份验证端点，每个 IP 每分钟 5-10 个请求是标准的。对于数据端点，每个经过身份验证的用户每分钟 100-500 个请求涵盖了大多数业务用例。监视 429 响应以识别过于严格的限制，并监视滥用模式以识别过于慷慨的限制。

如何保护来自第三方服务的 Webhooks？

使用 HMAC-SHA256 和共享密钥验证 Webhook 签名。验证时间戳以防止重放攻击（拒绝超过 5 分钟的事件）。异步处理 Webhook 以防止基于超时的拒绝服务。记录所有 Webhook 事件以进行审计。在处理之前验证有效负载架构。

---

下一步是什么

API 安全性不是您在开发结束时添加的功能——它是必须从第一个端点开始体现的设计原则。从强身份验证 (OAuth2/OIDC) 开始，在每个资源访问点强制授权，对所有端点类型实施速率限制，并验证跨越 API 边界的每个输入。

ECOSIRE 将安全性融入到每个 API 集成中。我们的 OpenClaw AI 平台 默认实现 HMAC 签名请求、速率限制和 SSRF 保护，而我们的 Odoo ERP 集成 使用 OAuth2/OIDC 和基于角色的访问控制。 联系我们的团队 以保护您的业务平台 API。

---

由 ECOSIRE 发布 --- 通过 Odoo ERP、Shopify 电子商务 和 OpenClaw AI 等人工智能驱动的解决方案帮助企业扩展规模。