Django REST framework SimpleJWT 黑名单功能详解

Django REST framework SimpleJWT 黑名单功能详解

djangorestframework-simplejwt A JSON Web Token authentication plugin for the Django REST Framework. 项目地址: https://gitcode.com/gh_mirrors/dj/djangorestframework-simplejwt

概述

在基于JWT(JSON Web Token)的身份验证系统中，令牌一旦签发就无法直接撤销，这在某些场景下会带来安全隐患。Django REST framework SimpleJWT项目提供了一个黑名单应用(token_blacklist)，专门用于解决JWT令牌的撤销问题。

安装与配置

要使用黑名单功能，首先需要在Django项目中安装并配置该应用：

1. 在settings.py文件中添加应用到INSTALLED_APPS列表：

INSTALLED_APPS = [
    ...
    'rest_framework_simplejwt.token_blacklist',
    ...
]

2. 执行数据库迁移命令以创建必要的表结构：

python manage.py migrate

工作原理

黑名单应用通过两个核心模型实现功能：

1. OutstandingToken：记录所有已签发的令牌
2. BlacklistedToken：记录被加入黑名单的令牌

当配置了黑名单应用后，SimpleJWT会自动：

• 将新生成的刷新令牌或滑动令牌添加到OutstandingToken列表
• 在验证令牌时检查该令牌是否存在于BlacklistedToken列表中

使用方式

1. 通过Django Admin管理黑名单

在Django管理后台中，你可以：

1. 查看所有已签发的令牌(OutstandingToken)
2. 将特定令牌加入黑名单(创建BlacklistedToken记录)

2. 通过代码黑名单令牌

from rest_framework_simplejwt.tokens import RefreshToken

# 获取令牌对象
token = RefreshToken("base64编码的令牌字符串")
# 将令牌加入黑名单
token.blacklist()

此方法会根据令牌的JTI声明(或JTI_CLAIM设置指定的声明)创建对应的黑名单记录。

3. 通过API端点黑名单令牌

你可以在URL配置中添加黑名单端点：

from rest_framework_simplejwt.views import TokenBlacklistView

urlpatterns = [
    ...
    path('api/token/blacklist/', TokenBlacklistView.as_view(), name='token_blacklist'),
    ...
]

客户端可以通过POST请求将刷新令牌加入黑名单：

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"refresh":"令牌字符串"}' \
  http://yourdomain/api/token/blacklist/

维护建议

黑名单应用提供了一个管理命令flushexpiredtokens，用于清理已过期的令牌记录。建议设置一个定时任务(如cron job)每天执行此命令：

python manage.py flushexpiredtokens

这可以防止数据库因存储过多过期令牌而膨胀。

安全最佳实践

1. 定期清理：确保定时运行flushexpiredtokens命令
2. 敏感操作后立即撤销：在用户修改密码、注销或检测到可疑活动时，应立即将相关令牌加入黑名单
3. 监控黑名单大小：异常大量的黑名单记录可能表明有安全事件发生
4. 结合其他安全措施：黑名单功能应与适当的令牌有效期设置、HTTPS传输等安全措施配合使用

通过合理使用SimpleJWT的黑名单功能，你可以为基于JWT的身份验证系统增加一层重要的安全防护，有效应对令牌泄露等安全威胁。

djangorestframework-simplejwt A JSON Web Token authentication plugin for the Django REST Framework. 项目地址: https://gitcode.com/gh_mirrors/dj/djangorestframework-simplejwt