JWT认证实现，PyJWT封装鉴权装饰器

本文深入剖析了在 Flask 中安全实现 JWT 认证的常见陷阱与最佳实践，指出直接调用 PyJWT 的 `encode()` 和 `decode()` 极易因密钥类型混淆、算法未显式声明、过期校验缺失等问题引发严重安全隐患；进而手把手教你构建健壮的 `@auth_required` 装饰器——支持多源 token 提取（Header/Query）、正确注入用户上下文到 `g` 对象、严格校验签名与有效期，并兼顾函数/类视图兼容性；同时澄清 Cookie 存储 JWT 的误区，强调 HttpOnly Cookie 仅用于 CSRF 防护，JWT 应由前端安全存于内存或 localStorage 并通过 Authorization Header 发送；最后揭秘刷新 Token 的核心原则：绝不能简单延长 exp，而需结合设备指纹、jti 黑名单与 Redis 精准管控，真正实现“一次换新、旧码作废”的安全续期机制。

为什么直接用 jwt.encode() 和 jwt.decode() 容易出错

PyJWT 库本身不处理 token 存储、刷新、黑名单或自动注入用户上下文，裸调用 jwt.encode() 很容易忽略密钥类型（str vs bytes）、算法显式声明、过期时间校验逻辑，导致 token 永不过期或解码时抛 InvalidSignatureError。更常见的是忘记在 jwt.decode() 中传 algorithms=['HS256']，Python 3.10+ 默认禁用弱算法后直接报 InvalidAlgorithmError。

实操建议：

• 密钥统一用 os.environ.get('SECRET_KEY').encode() 转为 bytes，避免 UnicodeEncodeError
• jwt.encode() 必须显式传 algorithm='HS256'，且 payload 中至少含 exp（用 datetime.utcnow() + timedelta(hours=1)）
• jwt.decode() 必须带 algorithms=['HS256'] 和 options={'verify_exp': True}，否则过期 token 仍能解码成功

如何写一个真正可用的 @auth_required 装饰器

Flask 的装饰器要兼容函数视图和类视图方法，还要能区分 token 来源（Authorization: Bearer xxx 或 query 参数），同时不能污染原函数的 __name__ 和 __doc__。

实操建议：

• 从 request.headers.get('Authorization') 提取 token，按空格分割后取第二项；没 header 就 fallback 到 request.args.get('token')
• 解码失败时统一返回 401 {'error': 'Invalid or expired token'}，不要暴露是签名错还是过期
• 用 functools.wraps(f) 包裹内层函数，否则 Flask 路由注册会丢掉函数元信息
• 把解码后的 user_id 注入 g.user_id，后续视图可直接用，别塞进 request 对象（它不是线程安全的）

示例片段：

from functools import wraps
from flask import g, request, jsonify
import jwt
from datetime import datetime
def auth_required(f):
@wraps(f)
def decorated_function(*args, *kwargs):
token = None
if 'Authorization' in request.headers:
auth_header = request.headers['Authorization']
if auth_header.startswith('Bearer '):
token = auth_header[7:]
if not token:
token = request.args.get('token')
if not token:
return jsonify({'error': 'Token missing'}), 401
try:
data = jwt.decode(token, current_app.config['SECRET_KEY'], 
algorithms=['HS256'], options={'verify_exp': True})
g.user_id = data['user_id']
except jwt.ExpiredSignatureError:
return jsonify({'error': 'Token expired'}), 401
except (jwt.InvalidTokenError, KeyError):
return jsonify({'error': 'Invalid token'}), 401
return f(args, **kwargs)
return decorated_function

为什么不能把 JWT 存在 Cookie 里还设 HttpOnly=False

前端 JavaScript 能读取的 Cookie（即 HttpOnly=False）和 localStorage 一样面临 XSS 攻击风险——恶意脚本可直接窃取 token 并转发给攻击者服务器。而 HttpOnly=True 又导致前端无法读取 token 做自动续期或显示用户名。

实操建议：

• 登录成功后，后端只通过 set_cookie(..., httponly=True, secure=True, samesite='Lax') 写一个短期 session cookie（如 15 分钟），仅用于 CSRF 防护
• JWT 本身走响应 body 返回 JSON，前端存 localStorage 或内存变量，配合 Authorization header 发送
• 必须配 secure=True（HTTPS only）和 samesite='Lax'，否则开发环境测试时 Chrome 会静默丢弃 Cookie

刷新 Token 的关键点：为什么不能只延长 exp

单纯对旧 token 调用 jwt.encode() 并改 exp 是危险的——攻击者若截获旧 token，可无限次“续期”，等于变相永不过期。真正的刷新必须绑定设备指纹或单次使用机制。

实操建议：

• 刷新接口（如 /auth/refresh）要求客户端提交当前 token + 用户 agent + IP（服务端比对是否与登录时一致）
• 签发新 token 时，在 payload 中加入 jti（JWT ID）字段，服务端维护一个 Redis 黑名单，记录已刷新的旧 jti，有效期设为原 token 过期时间 + 5 分钟
• 刷新成功后，旧 token 的 jti 立即加入黑名单，新 token 的 jti 不加入（否则无法连续刷新）
• 不要在刷新逻辑里验证旧 token 的 exp——它本就该过期了，重点是验证签名和黑名单

复杂点在于黑名单清理和 jti 生成：用 secrets.token_urlsafe(16) 生成 jti，Redis key 设为 blacklist:{jti}，TTL 设为 original_exp - now + 300 秒。

理论要掌握，实操不能落！以上关于《JWT认证实现，PyJWT封装鉴权装饰器》的详细介绍，大家都掌握了吧！如果想要继续提升自己的能力，那么就来关注golang学习网公众号吧！