api-security-design

API 安全设计

安全的 API 设计可保护后端服务和数据免受滥用，并防范 OWASP API Security Top 10 风险，包括对象级授权失效（BOLA）、身份验证失效、功能级授权失效（BFLA）、资源消耗不受限制、服务端请求伪造等。在 Azure 上，Azure API Management (APIM) 是主要的策略执行点，并与 WAF、Entra ID、Key Vault 和 Defender for APIs 配合使用。

适用场景

在 API 上线前，或作为定期设计评审的一部分，设计或评审 API 安全性——尤其是面向外部、面向合作伙伴或涉及敏感数据的 API。

请勿将此技能用于：

• 一般应用或 Web 应用安全（使用 security-architecture、threat-modelling）
• 仅进行 API 运行时检测和安全态势管理（使用 defender-for-apis）
• 前端 / SPA 设计（使用 Web 应用安全指南）

根据 OWASP API 风险选择合适的控制措施

OWASP API Top 10 风险	主要控制措施	所在位置
API1 - BOLA（对象级授权）	对每个对象进行授权检查	后端代码（网关无法完全覆盖）
API2 - 身份验证失效	使用 Entra ID 和 validate-jwt 实现 OAuth 2.0 / OIDC	网关 + Entra
API3 - 对象属性授权失效	架构验证 + 响应筛选	后端 + 网关
API4 - 资源消耗不受限制	速率限制、配额、载荷大小、超时	网关（APIM）
API5 - BFLA（功能级授权）	对每项操作检查角色 / 范围	后端代码
API6 - 对敏感流程的访问不受限制	强化身份验证、防滥用规则	Entra + 网关
API7 - SSRF	出站 URL 允许列表 + 出口流量控制	后端 + 网络
API8 - 安全配置错误	IaC + APIM 策略模板	DevOps + 网关
API9 - 库存管理不当	APIM 中的 API 目录 + 生命周期管理	APIM + 治理
API10 - 不安全地使用第三方 API	验证上游响应、设置超时	后端

经验法则： BOLA 和 BFLA 是最主要的两项 API 风险，无法仅在网关层彻底解决——后端必须强制执行针对每个对象和每项功能的授权。网关必不可少，但单靠网关并不足够。

方法

1. 在网关使用 Entra ID 进行身份验证 - 要求通过 Microsoft Entra ID 使用 OAuth 2.0 / OpenID Connect；在 APIM 使用 validate-jwt 策略验证 JWT（颁发者、受众、签名密钥、过期时间、必需声明）。避免仅使用静态 API 密钥作为唯一控制措施；如果确实使用，应积极轮换。 验证：网关会拒绝携带无效或已过期 JWT 的请求；日志会显示拒绝原因。
2. 在后端进行授权 - 在 JWT 中实施最小权限范围/角色，然后在后端对每次调用检查对象级和功能级授权。网关能识别调用者；只有后端知道调用者是否拥有该对象。 验证：用户 A 的测试 JWT 请求用户 B 的数据时会返回 403，即使网关允许该调用通过。
3. 应用网关保护措施（APIM） - 配置：按订阅/IP/身份实施速率限制和配额策略，为允许列表设置 IP 过滤，依据 OpenAPI 架构进行请求和响应验证，限制负载大小、设置超时，并将 CORS 限定为已知来源。 验证：超出速率限制的请求会返回 429；超大负载会被拒绝；不符合 OpenAPI 架构的请求会被拒绝。
4. 传输和机密 - 在每个端点强制使用 TLS 1.2+；在威胁模型要求时，对后端使用 mTLS；将所有机密（后端凭据、签名密钥）存储在 Azure Key Vault 中，并通过具有托管标识的 APIM 命名值引用。策略 XML 中不得包含机密，代码中也不得包含机密。 验证：APIM 策略或源代码仓库中没有明文机密；APIM 使用托管标识在运行时获取 Key Vault 引用。
5. 暴露面和网络控制 - 使用 WAF（Application Gateway 或 Azure Front Door）保护公共 API，提供第 7 层保护（OWASP Core Rule Set）；使用 Private Endpoints 确保后端不暴露于公共互联网。内部 API 不应具有公共路由。 验证：对公共 IP 进行端口扫描时，只能访问 WAF/APIM；无法从互联网直接访问后端。
6. 严格验证输入 - 在网关依据 OpenAPI 架构进行验证；拒绝意外字段、超大负载和格式错误的类型。后端代码应重新验证业务不变量，绝不能只信任网关。 验证：对 API 进行模糊测试会产生 4xx 响应，而非 5xx；任何输入类别都不会导致崩溃或泄露堆栈跟踪。
7. 添加运行时威胁检测 - 为由 APIM 提供前端的 API 启用 Microsoft Defender for APIs，以检测运行时威胁（可疑访问模式、敏感数据暴露、侦察行为、与 OWASP 对齐的攻击）。 验证：蓄意滥用的测试客户端会触发 Defender for APIs 警报。
8. 编目 API 并管理其生命周期 - 在 APIM（或你的网关）中盘点每个 API，按敏感级别和所有权添加标签，并按计划停用弃用版本。影子 API（未记录、未监控）是最常见的入侵途径。

防护原则

• BOLA/BFLA 是 API 的首要风险——必须在服务端按对象和功能强制执行授权。网关可以识别调用者，但无法得知调用者可以访问哪些对象。
• 不要只依赖网关——通过网关和后端实现纵深防御。单层防护可能失效；分层控制意味着一处配置错误不会直接导致安全漏洞。
• 根据架构验证输入；拒绝意外字段和超大负载。最常见的 API CVE 就是“我们接受了预料之外的内容”。
• **不要将静态 API 密钥作为唯一身份验证方式。**改用 OAuth 2.0 + Entra ID。如果为兼容合作伙伴而保留密钥，应勤于轮换并严格限制速率。
• 将 API 清单视为资产——影子 API 属于未受管理的风险。发现并编制目录是 API 安全的一部分，而不仅仅是运维工作。
• 后端重新验证并非重复操作——这是安全实施逐对象授权的唯一位置。

常见反模式

• **“我们在网关进行了 JWT 验证，所以很安全。”**后端缺少 BOLA/BFLA 检查——这是最常见的 API 漏洞模式。
• **静态 API 密钥既没有速率限制，也不会轮换。**凭据一旦泄露，就会导致全面暴露，而且无法检测。
• **网关没有架构验证。**后端会因格式错误的输入而崩溃并泄露堆栈跟踪；模糊测试会在生产环境中而非测试环境中发现漏洞。
• **在 APIM 策略 XML 或代码仓库中存放机密。**首次轮换凭据时，机密就会永久暴露在历史记录中。
• **即使前面有 APIM，后端仍公开可访问。**任何找到后端 URL 的人都能绕过网关。使用 Private Endpoints / VNet integration。
• **没有 API 目录。**影子 API 是外部 API 漏洞的主要模式。如果无法列出它们，就无法保护它们。

示例提示词

• Design a secure API on Azure API Management aligned to the OWASP API Security Top 10.
• How do I validate JWTs at the gateway instead of relying on static API keys?
• Configure rate limiting and payload validation to protect a backend API.
• Review my API authentication and authorization design for least privilege.
• What controls cover BOLA and BFLA on Azure API Management?

Microsoft Learn

• API Management 安全基线：https://learn.microsoft.com/azure/api-management/security-baseline
• 使用 Entra ID 保护后端：https://learn.microsoft.com/azure/api-management/api-management-howto-protect-backend-with-aad
• validate-jwt 策略：https://learn.microsoft.com/azure/api-management/validate-jwt-policy
• 缓解 OWASP API 威胁：https://learn.microsoft.com/azure/api-management/mitigate-owasp-api-threats
• Defender for APIs：https://learn.microsoft.com/azure/defender-for-cloud/defender-for-apis-introduction
• APIM 登陆区加速器：https://learn.microsoft.com/azure/cloud-adoption-framework/scenarios/app-platform/api-management/landing-zone-accelerator