Back to Details

api-security-design

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

API Security Design

API安全设计

Secure API design protects backend services and data from abuse and the OWASP API Security Top 10 risks - broken object-level authorization (BOLA), broken authentication, broken function-level authorization (BFLA), unrestricted resource consumption, server-side request forgery, and more. On Azure, Azure API Management (APIM) is the primary policy enforcement point, paired with WAF, Entra ID, Key Vault, and Defender for APIs.
安全的API设计可保护后端服务与数据免受滥用，抵御OWASP API安全Top 10风险——包括对象级授权失效（BOLA）、身份验证失效、功能级授权失效（BFLA）、无限制资源消耗、服务器端请求伪造等。在Azure平台上，Azure API Management (APIM) 是主要的策略执行点，可搭配WAF、Entra ID、Key Vault和Defender for APIs使用。

When to use

适用场景

Designing or reviewing the security of APIs - especially external-facing, partner-facing, or sensitive-data APIs - before they go live or as part of a recurring design review.
Do not use this skill for:
  • General application or web app security (use 
    security-architecture
    , 
    threat-modelling
    )
  • API runtime detection and posture only (use 
    defender-for-apis
    )
  • Front-end / SPA design (use web app security guidance)
在API上线前或定期设计评审中，设计或审核API的安全性——尤其是面向外部、合作伙伴或涉及敏感数据的API。
请勿将此技能用于：
  • 通用应用或Web应用安全（请使用
    security-architecture
    、
    threat-modelling
    相关内容）
  • 仅API运行时检测与态势管理（请使用
    defender-for-apis
    相关内容）
  • 前端/SPA设计（请使用Web应用安全指南）

Pick the right control per OWASP API risk

针对OWASP API风险选择合适的控制措施

OWASP API Top 10 riskPrimary controlWhere it lives
API1 - BOLA (object-level auth)Per-object authorization checkBackend code (gateway cannot fully cover)
API2 - Broken authenticationOAuth 2.0 / OIDC with Entra ID, 
validate-jwt
Gateway + Entra
API3 - Broken object property authSchema validation + response filteringBackend + gateway
API4 - Unrestricted resource consumptionRate limit, quota, payload size, timeoutGateway (APIM)
API5 - BFLA (function-level auth)Role/scope check on each operationBackend code
API6 - Unrestricted access to sensitive flowsStep-up auth, anti-abuse rulesEntra + gateway
API7 - SSRFOutbound URL allow-list + egress controlsBackend + network
API8 - Security misconfigurationIaC + APIM policy templatesDevOps + gateway
API9 - Improper inventory managementAPI catalog + lifecycle in APIMAPIM + governance
API10 - Unsafe consumption of third-party APIsValidate upstream responses, timeoutsBackend
Rule of thumb: BOLA and BFLA are the top two API risks and cannot be fully fixed at the gateway - the backend must enforce per-object and per-function authorization. The gateway is necessary but not sufficient.
OWASP API安全Top 10风险主要控制措施实施位置
API1 - BOLA（对象级授权）逐对象授权检查后端代码（网关无法完全覆盖）
API2 - 身份验证失效基于Entra ID的OAuth 2.0 / OIDC、
validate-jwt
策略		网关 + Entra
API3 - 对象属性授权失效Schema验证 + 响应过滤后端 + 网关
API4 - 无限制资源消耗速率限制、配额、负载大小限制、超时设置网关（APIM）
API5 - BFLA（功能级授权）对每个操作进行角色/范围检查后端代码
API6 - 敏感流程无限制访问进阶身份验证、反滥用规则Entra + 网关
API7 - SSRF出站URL白名单 + 出口控制后端 + 网络
API8 - 安全配置错误IaC + APIM策略模板DevOps + 网关
API9 - 不当的库存管理APIM中的API目录 + 生命周期管理APIM + 治理
API10 - 不安全的第三方API调用验证上游响应、超时设置后端
经验法则： BOLA和BFLA是排名前两位的API风险，且无法仅通过网关完全解决——后端必须强制执行逐对象和逐功能的授权。网关是必要的，但并不足够。

Approach

实施步骤

  1. Authentication at the gateway with Entra ID - Require OAuth 2.0 / OpenID Connect via Microsoft Entra ID; validate JWTs at APIM with the 
    validate-jwt
     policy (issuer, audience, signing key, expiration, required claims). Avoid static API keys as the only control - rotate them aggressively if used at all. Verify: a request with an invalid or expired JWT is rejected at the gateway; logs show the rejection reason.
  2. Authorization in the backend - Enforce least-privilege scopes/roles in the JWT, then check object-level and function-level authorization in the backend on every call. The gateway sees the caller; only the backend knows whether the caller owns the object. Verify: a test JWT for user A returns 403 when requesting user B's data, even though the gateway lets the call through.
  3. Apply gateway protections (APIM) - Configure: rate-limit and quota policies per subscription/IP/identity, IP filtering for allow-lists, request and response validation against the OpenAPI schema, payload size limits, timeouts, and CORS scoped to known origins. Verify: a request exceeding the rate limit returns 429; an oversized payload is rejected; a request not matching the OpenAPI schema is rejected.
  4. Transport and secrets - Enforce TLS 1.2+ on every endpoint, use mTLS to backends where threat model requires it, and store all secrets (backend credentials, signing keys) in Azure Key Vault referenced via APIM named values with a managed identity. No secrets in policy XML, no secrets in code. Verify: no secret literal appears in APIM policies or source repo; APIM uses managed identity to fetch Key Vault references at runtime.
  5. Exposure and network controls - Front public APIs with WAF (Application Gateway or Azure Front Door) for L7 protection (OWASP Core Rule Set), and use Private Endpoints to keep backends off the public internet. Internal APIs should not have a public route. Verify: a port scan of the public IP reaches WAF/APIM only; backends are not reachable directly from the internet.
  6. Validate input rigorously - Validate against the OpenAPI schema at the gateway; reject unexpected fields, oversized payloads, and malformed types. Backend code re-validates business invariants - never trust the gateway alone. Verify: fuzz testing on the API produces 4xx responses, not 5xx; no input class causes a crash or stack trace leak.
  7. Add runtime threat detection - Enable Microsoft Defender for APIs for APIM-fronted APIs to detect runtime threats (suspicious access patterns, sensitive-data exposure, reconnaissance, OWASP-aligned attacks). Verify: a deliberately abusive test client triggers a Defender for APIs alert.
  8. Catalog and lifecycle the APIs - Inventory every API in APIM (or your gateway), tag by sensitivity and ownership, and retire deprecated versions on a schedule. Shadow APIs
    • undocumented, unmonitored - are the most common breach path.
  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 Schema的请求与响应验证、负载大小限制、超时设置，以及限定已知来源的CORS。 验证：超出速率限制的请求返回429状态码；过大的负载被拒绝；不符合OpenAPI Schema的请求被拒绝。
  4. 传输安全与密钥管理 - 在每个端点强制使用TLS 1.2+；在威胁模型要求的场景下，对后端使用mTLS；将所有密钥（后端凭据、签名密钥）存储在Azure Key Vault中，通过APIM托管身份引用命名值。禁止在策略XML或代码中存储密钥。 验证：APIM策略或代码仓库中无明文密钥；APIM使用托管身份在运行时获取Key Vault引用。
  5. 暴露面与网络控制 - 为公开API部署WAF（Application Gateway或Azure Front Door）提供L7防护（OWASP核心规则集），并使用专用端点确保后端不暴露在公网中。内部API不应有公网路由。 验证：对公网IP的端口扫描仅能访问WAF/APIM；后端无法从互联网直接访问。
  6. 严格验证输入 - 在网关层基于OpenAPI Schema验证输入；拒绝意外字段、过大负载和格式错误的类型。后端代码需重新验证业务规则——永远不要仅信任网关。 验证：对API的模糊测试返回4xx状态码，而非5xx；任何输入类型都不会导致崩溃或堆栈跟踪泄露。
  7. 添加运行时威胁检测 - 为APIM前端的API启用Microsoft Defender for APIs，以检测运行时威胁（可疑访问模式、敏感数据泄露、侦察行为、符合OWASP标准的攻击）。 验证：故意发起恶意请求的测试客户端会触发Defender for APIs警报。
  8. API目录与生命周期管理 - 在APIM（或你的网关）中登记所有API，按敏感度和归属方打标签，并按计划停用已弃用的版本。影子API——未文档化、未监控的API——是最常见的入侵路径。

Guardrails

防护准则

  • BOLA/BFLA are the top API risks - authorization must be enforced server-side per object and per function. The gateway can see the caller but not which objects they may touch.
  • Don't rely on the gateway alone - defence in depth across gateway + backend. Single layers fail; layered controls mean a misconfiguration in one place does not equal breach.
  • Validate input against a schema; reject unexpected fields and oversized payloads. The most common API CVE is "we accepted what we did not expect".
  • No static API keys as sole authentication. Move to OAuth 2.0 + Entra ID. If keys remain for partner compatibility, rotate aggressively and rate-limit hard.
  • Treat the API inventory as an asset - shadow APIs are unmanaged risk. Discovery + catalog is part of API security, not just operations.
  • Backend re-validation is not duplication - it is the only place per-object authorization can land safely.
  • BOLA/BFLA是首要API风险——必须在服务器端逐对象、逐功能强制执行授权。网关可识别调用者，但无法知晓他们能访问哪些对象。
  • 不要仅依赖网关——在网关+后端之间构建纵深防御。单一防护层可能失效；多层控制意味着某一处的配置错误不会直接导致入侵。
  • 基于Schema验证输入；拒绝意外字段和过大负载。最常见的API CVE是“我们接受了预期之外的内容”。
  • 不要将静态API密钥作为唯一身份验证方式。迁移至OAuth 2.0 + Entra ID。若因合作伙伴兼容性必须保留密钥，需频繁轮换并严格限制速率。
  • 将API清单视为资产——影子API是未受管控的风险。发现+编目是API安全的一部分，而非仅运维工作。
  • 后端重新验证并非重复操作——这是唯一能安全实现逐对象授权的地方。

Common anti-patterns

常见反模式

  • "We have JWT validation at the gateway, we are secure." Missing BOLA/BFLA checks in the backend - the most common API breach pattern.
  • Static API keys with no rate limit and no rotation. Single credential leak = full exposure with no detection.
  • No schema validation at the gateway. Backends crash on malformed input and leak stack traces; fuzzing finds bugs in production rather than in test.
  • Secrets in APIM policy XML or repo. First credential rotation incident exposes them permanently in history.
  • Public backend even with APIM in front. Anyone who finds the backend URL bypasses the gateway. Use Private Endpoints / VNet integration.
  • No API catalog. Shadow APIs are the dominant external API breach pattern. If you cannot list them you cannot secure them.
  • “我们在网关层验证JWT，所以很安全。” 缺少后端的BOLA/BFLA检查——这是最常见的API入侵模式。
  • 静态API密钥无速率限制且不轮换。单一凭据泄露=完全暴露且无检测机制。
  • 网关层无Schema验证。后端因格式错误的输入崩溃并泄露堆栈跟踪；模糊测试在生产环境而非测试环境中发现漏洞。
  • 密钥存储在APIM策略XML或代码仓库中。首次密钥轮换事件会导致密钥永久暴露在历史记录中。
  • 即使前端有APIM，后端仍公开。任何人找到后端URL即可绕过网关。请使用专用端点/VNet集成。
  • 无API目录。影子API是外部API入侵的主要模式。若无法列出所有API，就无法保护它们。

Example prompts

示例提示词

  • 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?
  • 基于OWASP API安全Top 10标准，在Azure API Management上设计安全API。
  • 如何在网关层验证JWT，而非依赖静态API密钥？
  • 配置速率限制和负载验证以保护后端API。
  • 审核我的API身份验证与授权设计是否符合最小权限原则。
  • 在Azure API Management上，哪些控制措施可覆盖BOLA和BFLA风险？

Microsoft Learn

Microsoft Learn资源