Django REST Framework JWT

Warnings

• deprecated The original `jpadilla/django-rest-framework-jwt` project is officially unmaintained. This `Styria-Digital` fork, while available on PyPI, has not had a release since January 2022, indicating very limited ongoing maintenance.
  Fix: For actively maintained and modern JWT authentication, consider migrating to `djangorestframework-simplejwt`.
• gotcha The package requires specific versions of Python, Django, and Django REST Framework. Version 1.19.2 explicitly states Python 2.7, 3.4+, Django 1.11+, and DRF 3.7+.
  Fix: Ensure your project's environment matches these requirements. If using newer Django/DRF, migration to `djangorestframework-simplejwt` is highly recommended as it supports current versions.
• gotcha Security Warning: Always use SSL/TLS (HTTPS) for your API endpoints when using JWT. The token itself only verifies user identity; the request parameters are not signed and can be tampered with in transit if not encrypted.
  Fix: Deploy your application with HTTPS enabled. Ensure `SECURE_SSL_REDIRECT = True` and appropriate security headers are configured in production.
• gotcha Token storage on the client-side (e.g., `localStorage` for access tokens, `HttpOnly` cookies for refresh tokens) and proper handling of token expiration, rotation, and blacklisting are crucial security considerations often overlooked.
  Fix: Implement short-lived access tokens and longer-lived refresh tokens. Consider token rotation and blacklisting for improved security. Follow best practices for client-side token storage (e.g., `HttpOnly` cookies for refresh tokens to mitigate XSS risks).

Install

• pip install drf-jwt Install stable version

Imports

• JSONWebTokenAuthentication
  wrong:

  from rest_framework_simplejwt.authentication import JWTAuthentication

  correct:

  from rest_framework_jwt.authentication import JSONWebTokenAuthentication

  This is the authentication class for the `djangorestframework-jwt` package. Do not confuse it with `djangorestframework-simplejwt`'s `JWTAuthentication`.
• obtain_jwt_token
  wrong:

  from rest_framework_simplejwt.views import TokenObtainPairView

  correct:

  from rest_framework_jwt.views import obtain_jwt_token

  This view is used to obtain a JWT token by providing username and password. `simplejwt` uses `TokenObtainPairView`.
• refresh_jwt_token
  wrong:

  from rest_framework_simplejwt.views import TokenRefreshView

  correct:

  from rest_framework_jwt.views import refresh_jwt_token

  This view is used to refresh an existing JWT token. `simplejwt` uses `TokenRefreshView`.
• verify_jwt_token
  wrong:

  from rest_framework_simplejwt.views import TokenVerifyView

  correct:

  from rest_framework_jwt.views import verify_jwt_token

  This view is used to verify the validity of a JWT token. `simplejwt` uses `TokenVerifyView`.
• jwt_response_payload_handler

  from rest_framework_jwt.settings import api_settings

  Custom handler to modify the JWT response payload. Can be overridden in `settings.py`.

Quickstart

Configure `INSTALLED_APPS` and `REST_FRAMEWORK` settings. Add JWT-specific settings under `JWT_AUTH` for token expiration and refresh. Finally, include the `obtain_jwt_token`, `refresh_jwt_token`, and `verify_jwt_token` views in your project's `urls.py`.

import os
from datetime import datetime, timedelta

# settings.py
# Add 'rest_framework' and 'rest_framework_jwt' to INSTALLED_APPS
INSTALLED_APPS = [
    # ...
    'rest_framework',
    'rest_framework_jwt',
    # ...
]

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': (
        'rest_framework_jwt.authentication.JSONWebTokenAuthentication',
        'rest_framework.authentication.SessionAuthentication',
        'rest_framework.authentication.BasicAuthentication',
    ),
    'DEFAULT_PERMISSION_CLASSES': (
        'rest_framework.permissions.IsAuthenticated',
    ),
}

JWT_AUTH = {
    'JWT_EXPIRATION_DELTA': timedelta(seconds=int(os.environ.get('JWT_EXPIRATION_SECONDS', 3600))),
    'JWT_ALLOW_REFRESH': True,
    'JWT_REFRESH_EXPIRATION_DELTA': timedelta(days=int(os.environ.get('JWT_REFRESH_DAYS', 7))),
    'JWT_RESPONSE_PAYLOAD_HANDLER': 'your_app.utils.jwt_response_payload_handler',
    # 'JWT_SECRET_KEY': os.environ.get('DJANGO_SECRET_KEY', 'your_secret_key'), # Uses Django's SECRET_KEY by default
}

# urls.py
from django.urls import path
from rest_framework_jwt.views import obtain_jwt_token, refresh_jwt_token, verify_jwt_token

urlpatterns = [
    path('api-token-auth/', obtain_jwt_token),
    path('api-token-refresh/', refresh_jwt_token),
    path('api-token-verify/', verify_jwt_token),
    # ... other app URLs
]

# Example of a custom payload handler in your_app/utils.py
# def jwt_response_payload_handler(token, user=None, request=None):
#     return {
#         'token': token,
#         'user': user.username,
#         'id': user.id
#     }