Django REST Framework SimpleJWT 入门指南

Django REST Framework SimpleJWT 入门指南

项目简介

Django REST Framework SimpleJWT 是一个为 Django REST Framework 提供 JSON Web Token 认证支持的扩展库。它实现了完整的 JWT 认证流程，包括令牌的签发、刷新和验证功能，是构建现代 API 服务的理想选择。

环境要求

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

• Python 版本：3.8、3.9、3.10 或 3.11
• Django 框架版本：3.2、4.1 或 4.2
• Django REST Framework 版本：3.12、3.13 或 3.14

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

安装步骤

安装 SimpleJWT 非常简单，只需使用 pip 包管理工具执行以下命令：

pip install djangorestframework-simplejwt

可选加密依赖

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

pip install djangorestframework-simplejwt[crypto]

这种安装方式会将 cryptography 作为必需依赖安装，避免在项目依赖管理中被误认为无用依赖而删除。

项目配置

认证类配置

在 Django 项目的 settings.py 文件中，需要将 JWTAuthentication 添加到 REST_FRAMEWORK 的认证类列表中：

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

URL 路由配置

在项目的根 urls.py 文件中，添加 SimpleJWT 提供的视图路由：

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'),
]

这三个端点分别用于：

1. 获取令牌对（访问令牌和刷新令牌）
2. 刷新访问令牌
3. 验证令牌有效性

应用配置（可选）

如果需要使用本地化/国际化功能，还需将 SimpleJWT 添加到 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/

成功响应将返回包含访问令牌和刷新令牌的 JSON 数据：

{
    "access": "eyJhbGciOi...很长的JWT字符串...",
    "refresh": "eyJhbGciOi...很长的JWT字符串..."
}

使用访问令牌

获取到访问令牌后，可以将其用于认证受保护的 API 端点：

curl -H "Authorization: Bearer eyJhbGciOi...访问令牌..." \
     http://localhost:8000/api/protected-resource/

刷新访问令牌

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

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

响应将包含新的访问令牌：

{
    "access": "eyJhbGciOi...新的JWT字符串..."
}

最佳实践建议

1. 令牌有效期：在生产环境中，应根据安全需求合理设置访问令牌和刷新令牌的有效期。访问令牌通常设置为较短时间（如15分钟），刷新令牌可以设置较长时间（如7天）。

2. HTTPS：所有令牌传输必须通过 HTTPS 进行，以防止中间人攻击。

3. 令牌存储：前端应用应将访问令牌存储在内存中，刷新令牌可存储在 HttpOnly 的 Cookie 中以提高安全性。

4. 令牌撤销：考虑实现令牌黑名单机制，以便在用户登出或检测到可疑活动时能够立即撤销令牌。

通过以上配置和使用方法，您已经可以在 Django REST Framework 项目中轻松实现基于 JWT 的安全认证系统。SimpleJWT 的设计简洁而强大，能够满足大多数 API 项目的认证需求。