名称: api-jwt-认证器 类别: 安全 作者: Claude 版本: 1.0.0 标签: [fastapi, jwt, 认证, 安全, api] 描述: 一个概念性技能，用于通过JWT认证保护FastAPI REST API
API JWT认证器技能
何时使用此技能
当您需要为FastAPI REST API实现基于JWT的安全认证时，请使用此概念性技能。此技能适用于：
- 保护需要用户认证的API端点
- 强制执行用户特定的访问控制（确保用户只能访问自己的资源）
- 在微服务中实现无状态认证
- 通过标准JWT令牌验证保护REST API
- 为API端点添加基于角色的访问控制（RBAC）
此技能不应用于：
- 不需要认证的公共API
- 使用替代认证方法（OAuth、API密钥等）的API
- 基本认证就足够的简单应用程序
先决条件
- 理解JWT（JSON Web Token）概念
- FastAPI应用程序框架知识
- 基本安全原则和认证模式
- 用于安全管理密钥的环境
概念性实现框架
JWT令牌提取能力
- 从Authorization头中提取JWT令牌，格式为“Bearer <令牌>”
- 适当处理格式错误或缺失的授权头
- 验证头中是否存在“Bearer”前缀
令牌验证能力
- 使用共享密钥验证JWT令牌
- 验证令牌签名以确保完整性
- 检查令牌过期（exp）声明以防止使用过期令牌
- 在适用时验证令牌签发者（iss）和受众（aud）声明
用户身份验证能力
- 从令牌有效负载中提取用户身份信息
- 将令牌中的用户ID与请求的资源进行比较
- 基于用户身份强制执行访问控制规则
- 确保用户只能访问属于他们的资源
错误处理能力
- 为无效令牌生成适当的HTTP 401未授权响应
- 为权限不足生成HTTP 403禁止响应
- 提供清晰的错误消息而不暴露敏感信息
- 记录认证失败以进行安全监控
预期输入/输出
输入要求：
-
JWT令牌格式：
- 令牌必须在
Authorization头中，格式为Bearer <令牌> - 令牌必须包含具有所需声明的有效JWT结构
- 令牌不得过期
- 令牌必须在
-
令牌声明：
sub（主题）：用户标识符exp（过期）：令牌过期时间戳user_id（可选）：用于访问控制的唯一用户标识符role（可选）：用于基于角色的访问控制的用户角色
输出格式：
-
成功认证响应：
- 受保护端点的HTTP 200 OK
- 包含已认证用户信息的响应体
- 为下游处理提供正确认证的用户上下文
-
401未授权响应（无效/过期令牌）：
- HTTP 401状态码
- 错误消息：“无法验证凭据”
- 适当的WWW-Authenticate头
-
403禁止响应（权限不足）：
- HTTP 403状态码
- 错误消息：“访问被禁止：权限不足”
- 明确指示权限问题
-
令牌生成响应（如适用）：
- HTTP 200 OK
- 包含访问令牌和令牌类型的响应体
- 安全的令牌交付机制
安全注意事项
- 令牌传输：在生产环境中始终使用HTTPS以防止令牌被截获
- 令牌存储：将密钥安全存储在环境变量或安全保险库中
- 令牌过期：设置适当的过期时间以限制暴露窗口
- 令牌验证：在信任之前始终验证令牌签名和声明
- 信息泄露：避免在错误消息中暴露敏感信息
- 速率限制：实施速率限制以防止暴力攻击
- 日志记录：记录认证事件以进行安全监控，但不存储令牌
集成模式
依赖注入模式
- 使用FastAPI的依赖系统注入认证要求
- 将认证依赖应用于特定路由或整个路由器
- 根据需要组合多个认证要求
中间件集成
- 将认证实现为全局应用程序的中间件
- 在应用程序级别处理认证
- 集中认证逻辑以实现一致执行
基于角色的访问控制（RBAC）
- 在令牌声明中定义角色和权限
- 在认证依赖中实现角色验证
- 强制执行对特定端点的基于角色的访问
测试注意事项
- 测试认证失败场景（无效令牌、过期令牌）
- 验证用户特定的访问控制规则
- 测试基于角色的访问限制
- 验证错误响应格式和状态码
- 测试令牌刷新机制（如已实现）
性能影响
- JWT验证具有最小的计算开销
- 考虑高流量应用程序的令牌缓存策略
- 平衡令牌过期时间与性能要求
- 监控生产环境中与认证相关的延迟