name: jwt-auth description: | 在FastAPI或Python项目中实现JWT身份验证时使用。触发场景：令牌生成、验证中间件、当前用户提取、访问令牌创建、令牌解码或基于角色的身份验证。不适用于：OAuth2提供程序设置、OpenID Connect或非Python后端。

JWT身份验证技能

为FastAPI和Python应用程序提供JWT令牌生成、验证和用户提取的专业实现。

快速参考

操作	函数	位置
生成令牌	`create_access_token(data, expires_delta=None)`	`auth/jwt.py`
验证令牌	`verify_token(token: str)`	`auth/dependencies.py`
获取当前用户	`get_current_user(token: str)`	`auth/dependencies.py`
从载荷提取用户	`User.from_payload(payload)`	`auth/dependencies.py`

核心工作流程

1. 生成访问令牌

from auth.jwt import create_access_token

# 带主题的基本令牌
token = create_access_token(data={"sub": "user@example.com"})

# 带自定义过期时间（分钟）的令牌
from datetime import timedelta
token = create_access_token(
    data={"sub": "user@example.com", "roles": ["admin"]},
    expires_delta=timedelta(minutes=15)
)

# 用于RBAC的带角色令牌
token = create_access_token(data={"sub": "user@corp.com", "roles": ["editor", "viewer"]})

声明结构：

sub（必需）：用户标识符（邮箱、ID或用户名）
exp（自动）：过期时间
roles（可选）：用于授权的角色字符串列表
自定义声明：根据需要添加任何额外数据

2. 使用依赖保护端点

from fastapi import APIRouter, Depends
from auth.dependencies import get_current_user

router = APIRouter()

@router.get("/protected")
def protected_route(user = Depends(get_current_user)):
    return {"message": f"Hello, {user.email}"}

3. 基于角色的访问控制

from auth.dependencies import get_current_user, RoleChecker

# 定义角色检查器
admin_only = RoleChecker(allowed_roles=["admin"])

@router.delete("/admin-only")
def admin_endpoint(user = Depends(admin_only)):
    return {"message": "Admin access granted"}

4. 从JWT载荷提取用户

from auth.dependencies import get_current_user

# 从JWT声明自动提取用户模型
@router.get("/me")
def get_me(user = Depends(get_current_user)):
    return {
        "email": user.email,
        "roles": user.roles,
        "is_active": user.is_active
    }

安全检查清单

[ ] 短过期时间 + 刷新：访问令牌在15-30分钟内过期；为长会话实现刷新令牌流程
[ ] 无敏感数据：切勿在JWT声明中放入密码、个人身份信息或秘密
[ ] 黑名单无效令牌：为登出实现令牌黑名单（见revoked_tokens集合）
[ ] HS256算法：使用HMAC-SHA256；切勿使用algorithm="none"
[ ] 验证过期时间：始终检查exp声明；拒绝过期令牌

令牌结构

头部：
{
  "alg": "HS256",
  "typ": "JWT"
}

载荷：
{
  "sub": "user@example.com",
  "roles": ["user", "editor"],
  "exp": 1704067200,
  "iat": 1704063600
}

签名：HMAC-SHA256(密钥, 头部.载荷)

用户模型

class User:
    email: str
    roles: List[str]
    is_active: bool = True

    @classmethod
    def from_payload(cls, payload: dict) -> "User":
        """从解码的JWT载荷提取用户。"""
        return cls(
            email=payload.get("sub", ""),
            roles=payload.get("roles", []),
            is_active=payload.get("is_active", True)
        )

与@auth-integration前端集成

后端JWT实现与前端身份验证集成技能配对：

后端：auth/jwt.py和auth/dependencies.py
前端：使用auth-integration技能进行React/Next.js身份验证上下文
令牌流程：
- 前端登录后将令牌存储在内存/存储中
- 前端包含Authorization: Bearer <token>头部
- 后端HTTPBearer()依赖验证并提取用户
- 验证失败返回401未授权

文件输出

文件	用途
`auth/jwt.py`	令牌创建、编码、密钥配置
`auth/dependencies.py`	用于验证和用户提取的FastAPI依赖

配置

设置以下环境变量：

JWT_SECRET_KEY：长随机字符串（至少32个字符）
JWT_ALGORITHM：“HS256”（默认）
JWT_EXPIRATION_MINUTES：15（推荐）

质量门控

完成前检查：

[ ] 令牌使用HS256算法
[ ] 过期时间设置为15-30分钟
[ ] 声明中无敏感数据
[ ] 为登出实现黑名单机制
[ ] 与auth-integration前端技能的集成已记录