django-jwt-auth：Django 的 JWT 认证方案

在 Django 项目中实现 API 认证，django-jwt-auth 是一个轻量方案。这个项目目前获得 170 Star，基于 Django REST Framework JWT Auth 开发。

django-jwt-auth 为 Django 项目提供 JSON Web Token 认证支持。JWT 是一种开放标准，用于在双方之间安全传输信息，常见于无状态的 API 认证场景。相比传统的 Session 认证，JWT 将认证信息存储在 token 中，服务端无需维护会话状态，更适合分布式和微服务架构。

安装

django-jwt-auth 发布在 PyPI 上，通过 pip 即可安装：

pip install django-jwt-auth

基本使用

安装完成后，在项目的 urls.py 中添加两条路由，分别用于获取 token 和刷新 token：

from rest_framework_jwt.views import obtain_jwt_token, refresh_jwt_token

urlpatterns = [
    url(r'api-token-auth/', obtain_jwt_token),
    url(r'api-token-refresh/', refresh_jwt_token),
]

配置好路由后，可以用 curl 测试接口是否正常工作。假设已创建一个用户名为 admin、密码为 abc123 的账户：

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

请求成功后会返回 JWT token。后续访问受保护的 API 时，需要在请求头中携带该 token：

curl -H "Authorization: Bearer <your_token>" http://localhost:8000/protected-url/

配置项

django-jwt-auth 提供丰富的配置选项，开发者可以根据需求进行覆盖。所有配置项的默认值如下：

JWT_ENCODE_HANDLER = 'jwt_auth.utils.jwt_encode_handler'
JWT_DECODE_HANDLER = 'jwt_auth.utils.jwt_decode_handler'
JWT_PAYLOAD_HANDLER = 'jwt_auth.utils.jwt_payload_handler'
JWT_PAYLOAD_GET_USER_ID_HANDLER = 'jwt_auth.utils.jwt_get_user_id_from_payload_handler'
JWT_SECRET_KEY = SECRET_KEY
JWT_ALGORITHM = 'HS256'
JWT_VERIFY = True
JWT_VERIFY_EXPIRATION = True
JWT_LEEWAY = 0
JWT_EXPIRATION_DELTA = datetime.timedelta(seconds=300)
JWT_ALLOW_REFRESH = False
JWT_REFRESH_EXPIRATION_DELTA = datetime.timedelta(days=7)
JWT_AUTH_HEADER_PREFIX = 'Bearer'

下面介绍几个常用配置：

JWT_SECRET_KEY 是加密 token 的密钥，默认读取项目配置中的 SECRET_KEY。生产环境建议单独配置。

JWT_ALGORITHM 指定签名算法，可选值包括 HS256、HS384、HS512、RS256、RS384、RS512。其中 RS 系列算法需要使用 RSA 密钥对，私钥用于签名，公钥用于验证。默认值为 HS256。

JWT_VERIFY 控制是否验证签名。设为 False 时，即使密钥错误也能解析 payload，但会抛出 DecodeError。默认开启验证。

JWT_VERIFY_EXPIRATION 控制是否检查 token 是否过期。默认开启。

JWT_LEEWAY 用于设置过期时间的容错窗口，单位为秒。例如 token 过期时间为 30 秒后，将 leeway 设为 10 秒，则 40 秒内仍可接受。默认值为 0。

JWT_EXPIRATION_DELTA 定义 token 的有效期，使用 Python 的 datetime.timedelta 类型。默认值为 5 分钟。

JWT_ALLOW_REFRESH 启用后，已签发的 token 会包含 orig_iat 字段，支持在有效期内刷新。默认关闭。

JWT_REFRESH_EXPIRATION_DELTA 限制从原始 token 签发后多久内可以刷新，默认 7 天。

JWT_AUTH_HEADER_PREFIX 修改请求头中 token 的前缀，默认值为 Bearer。

该库底层使用 PyJWT 实现，对熟悉 Django 的开发者来说，接入成本较低。如果你正在为 Django 项目寻找一种无状态的认证方案，django-jwt-auth 是一个可考虑的选择。

实现，对熟悉 Django 的开发者来说，接入成本较低。如果你正在为 Django 项目寻找一种无状态的认证方案，django-jwt-auth 是一个可考虑的选择。