4. 认证与授权审计基线：Bearer Token、OAuth2、API Key、JWT校验、最小权限原则检查

认证（Authentication）与授权（Authorization）是API安全的第一道防线。OpenAPI规范通过securitySchemes和security字段声明API的安全模型。审计基线要求验证：安全方案定义是否完整、令牌校验逻辑是否严格、权限范围是否遵循最小权限原则。

4.1 核心概念与审计目标

认证确认“你是谁”，授权确认“你能做什么”。在OpenAPI审计中，需要区分以下四种主流机制：

4.2 Bearer Token 审计基线

Bearer Token是最常见的HTTP认证方式。OpenAPI中通过type: http和scheme: bearer定义。审计要点包括：

• Bearer格式声明：必须使用bearerFormat字段说明Token类型（如JWT、Opaque）。
• 传输安全：所有Bearer Token必须通过HTTPS传输，禁止明文HTTP。
• Token存储：服务端不应持久化明文Token，应使用哈希或加密存储。
• 过期机制：Token必须设置exp（过期时间），服务端需校验。

# 正确的Bearer Token定义示例
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT  # 明确声明Token格式
      description: "使用JWT格式的Bearer Token，通过Authorization头传递"

4.3 OAuth2 审计基线

OAuth2是委托授权标准，OpenAPI支持四种授权流程。审计基线要求验证流程定义、Scope粒度、客户端凭证管理。

# OAuth2 授权码流程定义示例
components:
  securitySchemes:
    OAuth2Auth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/authorize
          tokenUrl: https://auth.example.com/token
          scopes:
            read:   "读取用户数据"
            write:  "写入用户数据"
            admin:  "管理权限（需审批）"

4.4 API Key 审计基线

API Key通过type: apiKey定义，可放置在Header、Query或Cookie中。审计基线要求：

• 传输位置：优先使用Header（in: header），避免在URL Query中传递Key。
• Key命名：使用标准Header名称如X-API-Key，避免自定义敏感名称。
• Key轮换：API Key必须支持定期轮换，审计检查是否有轮换机制文档。
• 权限隔离：每个API Key应绑定最小权限，禁止使用“超级Key”。

# API Key 定义示例（推荐Header方式）
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: "通过X-API-Key头传递API密钥"

4.5 JWT 校验审计基线

JWT（JSON Web Token）通常作为Bearer Token的载体。审计基线要求验证JWT的完整性、签名算法、Payload声明。

# JWT Payload 最小声明集示例
{
  "iss": "https://auth.example.com",
  "sub": "user_12345",
  "aud": "https://api.example.com/v2",
  "exp": 1718000000,
  "iat": 1717996400,
  "scope": "read write"
}

4.6 最小权限原则检查

最小权限原则（Principle of Least Privilege）要求每个API端点只授予完成操作所需的最小权限集合。审计检查方法：

• 端点级权限声明：每个路径+方法必须显式声明所需的安全范围（Scope）。
• Scope粒度：避免使用admin或full_access等粗粒度Scope，应拆分为users:read、orders:write等细粒度Scope。
• 全局覆盖检查：检查security字段是否在顶层定义后，又被子路径覆盖为更宽松的权限。
• 未授权端点：审计标记所有未声明安全方案的端点（security: []），要求业务方确认。

# 最小权限原则合规示例
paths:
  /users:
    get:
      summary: "获取用户列表"
      security:
        - BearerAuth: [users:read]   # 仅需读取权限
    post:
      summary: "创建用户"
      security:
        - BearerAuth: [users:write]  # 需要写入权限
  /admin:
    get:
      summary: "管理面板"
      security:
        - BearerAuth: [admin:read]   # 管理权限单独定义

4.7 认证与授权审计流程总览

下图展示了从OpenAPI规范解析到最终审计报告生成的完整流程：

4.8 审计基线检查清单

以下清单可作为自动化审计工具的输入，也可用于人工审查：