Django REST Framework 集成 simplejwt 实现 JWT 认证全流程指南

Nora

发布时间：2026-10-14 | 3人浏览过

原创

本文详细记录在 Django REST Framework 项目中集成 djangorestframework-simplejwt 库实现 JWT 身份认证的完整流程。内容涵盖从环境安装、Django 项目与 App 的基础搭建，到 settings.py 中的核心配置及 urls.py 的路由映射。通过具体代码示例演示如何获取访问令牌、测试受保护接口，并深入讲解如何自定义 Token 返回字段以及手动颁发 Token 以支持用户注册后直接返回凭证的高级用法。

本文档旨在记录如何在 Django REST Framework 项目中集成并使用 djangorestframework-simplejwt 库进行 JWT 登录认证。内容基于官方文档及实际开发经验整理。

环境安装与基础配置

1. 环境安装


pip install djangorestframework-simplejwt

2. 基础使用流程

首先，需要创建 Django 项目及其对应的应用（app）。


# 创建名为 simple 的工程
django-admin startproject simple
 
# 创建名为 users 的应用
cd simple
python manage.py startapp users

项目的目录结构应如下所示：

接下来，在 `simple/settings.py` 配置文件中添加必要的设置。


# simple/settings.py
 
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'users',                        # add
    'rest_framework',               # add
    'rest_framework_simplejwt',     # add
]
 
REST_FRAMEWORK = {                  # add
    'DEFAULT_AUTHENTICATION_CLASSES': (
        'rest_framework_simplejwt.authentication.JWTAuthentication',
    )
}

执行数据库同步命令，并创建一个超级用户以便后续测试。


# 同步数据库
python manage.py makemigrations
python manage.py migrate
 
# 创建超级用户
python manage.py createsuperuser

在 `simple/urls.py` 文件中配置 JWT 相关的路由规则。


# simple/urls.py
from django.contrib import admin
from django.urls import path
from rest_framework_simplejwt.views import TokenRefreshView, TokenVerifyView, TokenObtainPairView
 
urlpatterns = [
    path('admin/', admin.site.urls),
    path('login/', TokenObtainPairView.as_view(), name='token_obtain_pair'),
    path('refresh/', TokenRefreshView.as_view(), name='token_refresh'),
    path('verify/', TokenVerifyView.as_view(), name='token_verify'),
]

使用 Python 的 HTTP 客户端工具对接口进行初步测试。

http -f POST http://127.0.0.1:8000/login/ username=admin password=123456

受保护接口的测试与验证

3. 测试受保护的 API 接口

在 `users/views.py` 中编写需要身份验证的视图代码。


# users/views.py
from rest_framework import permissions
from rest_framework.response import Response
from rest_framework.views import APIView
 
 
class MyView(APIView):
    permission_classes = [permissions.IsAuthenticated]
 
    def get(self, request, *args, **kwargs):
        return Response("Get information successfully!")

随后，在 `simple/urls.py` 中注册该视图的路由。


# simple/urls.py
from users import views    # add
 
urlpatterns = [
    ...
    path('info/', views.MyView.as_view()),    # add
]

再次使用 Python HTTP 工具进行接口功能测试。

JWT 高级配置与自定义返回

4. 高级配置选项


# settings.py
 
from datetime import timedelta
 
SIMPLE_JWT = {
    'ACCESS_TOKEN_LIFETIME': timedelta(minutes=5),  # 访问令牌的有效时间
    'REFRESH_TOKEN_LIFETIME': timedelta(days=1),    # 刷新令牌的有效时间
 
    'ROTATE_REFRESH_TOKENS': False,     # 若为True，则刷新后新的refresh_token有更新的有效时间
    'BLACKLIST_AFTER_ROTATION': True,   # 若为True，刷新后的token将添加到黑名单中, 
                                        # When True,'rest_framework_simplejwt.token_blacklist',should add to INSTALLED_APPS
 
    'ALGORITHM': 'HS256',       # 对称算法：HS256 HS384 HS512  非对称算法：RSA
    'SIGNING_KEY': SECRET_KEY,
    'VERIFYING_KEY': None,      # if signing_key, verifying_key will be ignore.
    'AUDIENCE': None,
    'ISSUER': None,
 
    'AUTH_HEADER_TYPES': ('Bearer',),           # Authorization: Bearer <token>
    'AUTH_HEADER_NAME': 'HTTP_AUTHORIZATION',   # if HTTP_X_ACCESS_TOKEN, X_ACCESS_TOKEN: Bearer <token>
    'USER_ID_FIELD': 'id',                      # 使用唯一不变的数据库字段,将包含在生成的令牌中以标识用户
    'USER_ID_CLAIM': 'user_id',
 
    # 'AUTH_TOKEN_CLASSES': ('rest_framework_simplejwt.tokens.AccessToken',),   # default: access
    # 'TOKEN_TYPE_CLAIM': 'token_type',         # 用于存储令牌唯一标识符的声明名称 value:'access','sliding','refresh'
    #
    # 'JTI_CLAIM': 'jti',
    #
    # 'SLIDING_TOKEN_REFRESH_EXP_CLAIM': 'refresh_exp',     # 滑动令牌是既包含到期声明又包含刷新到期声明的令牌
    # 'SLIDING_TOKEN_LIFETIME': timedelta(minutes=5),       # 只要滑动令牌的到期声明中的时间戳未通过，就可以用来证明身份验证
    # 'SLIDING_TOKEN_REFRESH_LIFETIME': timedelta(days=1),  # path('token|refresh', TokenObtainSlidingView.as_view())
}

5. 自定义 Token 返回信息

在 `users/serializers.py` 中定义自定义的 Token 序列化器。


# simple/serializers.py
from rest_framework_simplejwt.serializers import TokenObtainPairSerializer
 
 
class MyTokenObtainPairSerializer(TokenObtainPairSerializer):
 
    def validate(self, attrs):
        data = super().validate(attrs)
        refresh = self.get_token(self.user)
        data['refresh'] = str(refresh)
        data['access'] = str(refresh.access_token)
        data['username'] = self.user.username
        return data

在 `users/views.py` 及 `simple/urls.py` 中应用自定义序列化器。


# users/views.py
from rest_framework_simplejwt.views import TokenObtainPairView
from users.serializers import MyTokenObtainPairSerializer
 
 
class MyTokenObtainPairView(TokenObtainPairView):
    serializer_class = MyTokenObtainPairSerializer
 
# simple/urls.py
from users.views import MyTokenObtainPairView
 
urlpatterns = [
    ...
    # modify
    path('login/', MyTokenObtainPairView.as_view(), name='token_obtain_pair'),
]

测试 API 接口，验证返回信息中是否包含新增的 username 字段。

http -f POST :8000/login/ username=admin password=123456

手动颁发 Token 的实现

6. 手动颁发 Token

手动颁发 Token 的场景主要出现在用户注册环节，目的是在用户注册成功后直接返回访问令牌，提升用户体验。

以下代码展示了如何针对一个现有的 user 对象手动生成并返回 Token。对于用户注册流程，只需将 user 对象替换为注册后创建的用户实例即可。


# users/views.py
 
class MyView(APIView):
    permission_classes = [permissions.IsAuthenticated]
 
    def get(self, request, *args, **kwargs):
        return Response("Get information successfully!")
 
    def post(self, request, *args, **kwargs):
        refresh = RefreshToken.for_user(request.user)
        content = {
            'refresh': str(refresh),
            'access': str(refresh.access_token),
        }
        return Response(content)

至此，关于 Django REST Framework 使用 simplejwt 进行登录认证的完整记录介绍完毕。如需了解更多相关内容，建议查阅本站过往文章或继续浏览后续资源，感谢支持。