Django REST Framework SimpleJWT 配置详解

Django REST Framework SimpleJWT 配置详解

djangorestframework-simplejwt 项目地址: https://gitcode.com/gh_mirrors/dja/djangorestframework-simplejwt

概述

Django REST Framework SimpleJWT 是一个为 Django REST Framework 提供 JSON Web Token 认证支持的扩展库。通过合理的配置，开发者可以灵活地控制 JWT 的行为，满足各种安全需求和业务场景。本文将全面解析 SimpleJWT 的各项配置参数，帮助开发者深入理解并正确使用这个强大的认证工具。

基础配置

令牌有效期设置

"ACCESS_TOKEN_LIFETIME": timedelta(minutes=5),  # 访问令牌有效期
"REFRESH_TOKEN_LIFETIME": timedelta(days=1),    # 刷新令牌有效期

这两个参数分别控制访问令牌和刷新令牌的有效期。访问令牌通常设置较短的有效期（如5分钟），而刷新令牌可以设置较长的有效期（如1天）。这种设计既保证了安全性，又避免了用户频繁登录。

令牌刷新机制

"ROTATE_REFRESH_TOKENS": False,  # 是否在刷新时生成新刷新令牌
"BLACKLIST_AFTER_ROTATION": False,  # 是否在刷新后将旧令牌加入黑名单

当 ROTATE_REFRESH_TOKENS 为 True 时，每次使用刷新令牌获取新访问令牌时，系统会同时返回一个新的刷新令牌。结合 BLACKLIST_AFTER_ROTATION 可以增强安全性，防止刷新令牌被重复使用。

安全相关配置

签名算法与密钥

"ALGORITHM": "HS256",  # 签名算法
"SIGNING_KEY": settings.SECRET_KEY,  # 签名密钥
"VERIFYING_KEY": "",  # 验证密钥

SimpleJWT 支持多种签名算法：

• HMAC 系列：HS256、HS384、HS512（对称加密）
• RSA 系列：RS256、RS384、RS512（非对称加密）

对于生产环境，建议：

1. 不要直接使用 Django 的 SECRET_KEY 作为签名密钥
2. 考虑使用 RSA 算法实现更安全的非对称加密
3. 定期轮换密钥

令牌声明验证

"AUDIENCE": None,  # 目标受众验证
"ISSUER": None,  # 签发者验证
"JWK_URL": None,  # JWK 公钥集URL

这些参数用于验证令牌的标准声明（claims），适用于需要严格验证令牌来源的场景，如微服务架构中的服务间认证。

用户认证配置

用户标识相关

"USER_ID_FIELD": "id",  # 用户模型中用作标识的字段
"USER_ID_CLAIM": "user_id",  # 令牌中存储用户标识的声明名

最佳实践：

• USER_ID_FIELD 应选择不会变更的字段（如主键）
• 避免使用可能变更的字段（如用户名、邮箱）

认证头设置

"AUTH_HEADER_TYPES": ("Bearer",),  # 认证头类型
"AUTH_HEADER_NAME": "HTTP_AUTHORIZATION",  # 认证头名称

这些配置决定了客户端应如何发送令牌。例如，默认配置要求请求头格式为：

Authorization: Bearer <token>

高级功能配置

滑动令牌

"SLIDING_TOKEN_LIFETIME": timedelta(minutes=5),  # 滑动令牌有效期
"SLIDING_TOKEN_REFRESH_LIFETIME": timedelta(days=1),  # 滑动令牌可刷新期

滑动令牌是一种特殊类型的令牌，它在每次使用时自动延长有效期（类似会话机制），适用于需要长时间保持登录状态的场景。

序列化器定制

"TOKEN_OBTAIN_SERIALIZER": "rest_framework_simplejwt.serializers.TokenObtainPairSerializer",
"TOKEN_REFRESH_SERIALIZER": "rest_framework_simplejwt.serializers.TokenRefreshSerializer",

开发者可以通过覆盖这些默认序列化器来实现自定义的令牌获取、刷新逻辑，例如添加额外的用户信息到令牌响应中。

安全注意事项

1. 密钥管理：签名密钥应妥善保管，定期轮换
2. 令牌有效期：根据业务需求平衡安全性与用户体验
3. 黑名单功能：对于高安全要求的应用，应启用令牌黑名单
4. HTTPS：生产环境必须使用 HTTPS 传输令牌
5. 日志记录：记录令牌颁发和刷新操作，便于审计

最佳实践配置示例

SIMPLE_JWT = {
    "ACCESS_TOKEN_LIFETIME": timedelta(minutes=15),
    "REFRESH_TOKEN_LIFETIME": timedelta(days=7),
    "ROTATE_REFRESH_TOKENS": True,
    "BLACKLIST_AFTER_ROTATION": True,
    "ALGORITHM": "RS256",
    "SIGNING_KEY": "-----BEGIN PRIVATE KEY-----\n...",
    "VERIFYING_KEY": "-----BEGIN PUBLIC KEY-----\n...",
    "AUTH_HEADER_TYPES": ("Bearer",),
    "USER_ID_FIELD": "id",
    "USER_ID_CLAIM": "user_id",
    "AUTH_TOKEN_CLASSES": ("rest_framework_simplejwt.tokens.AccessToken",),
}

通过合理配置 Django REST Framework SimpleJWT，开发者可以构建既安全又用户友好的认证系统。建议根据实际业务需求和安全要求，仔细调整各项参数。

djangorestframework-simplejwt 项目地址: https://gitcode.com/gh_mirrors/dja/djangorestframework-simplejwt