Django REST framework Simple JWT 入门指南

Django REST framework Simple JWT 入门指南

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

项目简介

Django REST framework Simple JWT 是一个为 Django REST 框架提供 JSON Web Token 认证支持的扩展库。它实现了完整的 JWT 认证流程，包括令牌的获取、刷新和验证功能，是构建现代 API 认证系统的理想选择。

环境要求

在开始使用前，请确保您的开发环境满足以下要求：

• Python 版本：3.9、3.10、3.11、3.12 或 3.13
• Django 版本：4.2、5.0 或 5.1
• Django REST Framework 版本：3.14 或 3.15

虽然官方仅支持上述版本组合，但其他版本通常也能正常工作。如需使用其他版本，可以自行测试兼容性。

安装步骤

安装 Simple JWT 非常简单，只需执行以下 pip 命令：

pip install djangorestframework-simplejwt

可选加密依赖

如果您计划使用 RSA 或 ECDSA 等数字签名算法来编码或解码令牌，需要额外安装 cryptography 库。推荐以下安装方式：

pip install djangorestframework-simplejwt[crypto]

这种安装方式会在项目依赖文件中明确标注加密功能的需求，避免后续维护时误删必要的加密依赖。

项目配置

认证类配置

在 Django 项目的 settings.py 文件中，添加 JWT 认证类：

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': (
        # 其他认证类...
        'rest_framework_simplejwt.authentication.JWTAuthentication',
    )
}

URL 路由配置

在项目的 urls.py 文件中，添加令牌获取和刷新端点：

from rest_framework_simplejwt.views import (
    TokenObtainPairView,
    TokenRefreshView,
    TokenVerifyView
)

urlpatterns = [
    # 其他路由...
    path('api/token/', TokenObtainPairView.as_view(), name='token_obtain_pair'),
    path('api/token/refresh/', TokenRefreshView.as_view(), name='token_refresh'),
    path('api/token/verify/', TokenVerifyView.as_view(), name='token_verify'),
]

应用配置（可选）

如需使用本地化/翻译功能，需将 Simple JWT 添加到 INSTALLED_APPS：

INSTALLED_APPS = [
    # 其他应用...
    'rest_framework_simplejwt',
]

基本使用示例

获取令牌

使用用户名和密码获取访问令牌和刷新令牌：

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"username": "your_username", "password": "your_password"}' \
  http://localhost:8000/api/token/

响应示例：

{
  "access": "eyJhbGciOiJIUzI1NiIs...",
  "refresh": "eyJhbGciOiJIUzI1NiIs..."
}

使用访问令牌

将获取的访问令牌添加到请求头中访问受保护资源：

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  http://localhost:8000/api/protected-resource/

刷新访问令牌

当访问令牌过期时，使用刷新令牌获取新的访问令牌：

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"refresh":"eyJhbGciOiJIUzI1NiIs..."}' \
  http://localhost:8000/api/token/refresh/

响应示例：

{
  "access": "eyJhbGciOiJIUzI1NiIs..."
}

令牌验证

验证令牌的有效性（不返回令牌信息，仅返回状态码）：

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"token":"eyJhbGciOiJIUzI1NiIs..."}' \
  http://localhost:8000/api/token/verify/

工作原理解析

Simple JWT 实现了标准的 JWT 认证流程：

1. 令牌获取：用户提供凭据获取访问令牌和刷新令牌
2. 访问令牌：短期有效，用于访问受保护资源
3. 刷新令牌：长期有效，用于获取新的访问令牌
4. 令牌验证：验证令牌签名和有效期

这种双令牌机制既保证了安全性（访问令牌短期有效），又提供了良好的用户体验（无需频繁重新登录）。

最佳实践建议

1. 生产环境：务必使用 HTTPS 协议传输令牌
2. 令牌存储：前端应安全存储令牌（如 HttpOnly Cookie）
3. 密钥管理：使用强密钥并定期轮换
4. 令牌有效期：根据安全需求合理设置令牌有效期

通过以上配置和使用方法，您可以在 Django REST 框架项目中快速实现基于 JWT 的安全认证系统。

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