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 认证流程，包括令牌的签发、刷新和验证功能，是构建现代 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 项目的认证需求。

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