Django-EasyJWT

A Django package for implementing remote JWT authentication in microservice architectures. It provides a centralized authentication service with multiple client services authenticating against it.

Table of Contents

• Why Django-EasyJWT?
• Features
• Installation
• Architecture Overview
• Quick Start
  • Create an Auth-Service
  • Create a Client-Service
  • Standing up the Services
• Configuration Reference
• API Endpoints
• Testing the API
• Advanced Usage
  • Extra Data
  • Permissions
• Refresh-Token Cookies & CSRF
• Security
• Running Tests
• Changelog
• Acknowledgements
• License

Why Django-EasyJWT?

When managing multiple services with the same users, a centralized authentication service eliminates password confusion and provides a single source of truth. Django-EasyJWT was built for scenarios where:

• Multiple services share the same user base
• Different services require different access levels
• You need custom user data and permissions passed through authentication
• You want to keep your auth service lean and behind a private network

Features

• JWT Authentication: Access/refresh token pairs and sliding tokens
• Remote Auth: Client services authenticate against a central auth service
• Stateless Auth: Optional token-only authentication with no DB lookup (JWTStatelessUserAuthentication)
• Session Support: Authenticated users can access Django admin
• Custom User Model: Optional email-based user model included
• Token Blacklisting: Optional token revocation via outstanding/blacklist tracking
• Password Security: Django password validators enforced on create-user and password-change
• User Registration: Built-in create-user/ endpoint with email normalization
• Password Change: Built-in password-change/ endpoint with credential verification
• Sliding Tokens: Optional single-token JWT with embedded refresh window
• Extensible: Custom serializers for additional user data
• Configurable: HTTP timeouts, SSL verification, and configurable endpoint paths
• Production Warnings: Automatic logging when SSL or insecure HTTP is configured
• Refresh-Token Cookies: Optional HttpOnly cookie storage with CSRF protection and logout blacklisting for browser-based SPAs

Installation

uv add django-easyjwt

Or with pip:

pip install django-easyjwt

Architecture Overview

┌─────────────────┐         ┌─────────────────┐
│  Client-Service │ ──────► │   Auth-Service  │
│   (Port 8001)   │         │   (Port 8000)   │
├─────────────────┤         ├─────────────────┤
│ easyjwt_client  │         │  easyjwt_auth   │
│ easyjwt_user    │         │  easyjwt_user   │
└─────────────────┘         └─────────────────┘
        │                           │
        ▼                           ▼
   Local DB                     Auth DB
 (User copies)              (User source)

The package contains three sub-packages:

Quick Start

Create an Auth-Service

uv venv
source .venv/bin/activate
uv pip install django djangorestframework django_easyjwt
uv run django-admin startproject config
mv config auth-service
cd auth-service

Add to config/settings.py:

from datetime import timedelta

INSTALLED_APPS = [
    # ...
    'rest_framework',
    'easyjwt_auth',
    'easyjwt_user',
]

AUTH_USER_MODEL = "easyjwt_user.User"

REST_FRAMEWORK = {
    "DEFAULT_PERMISSION_CLASSES": ("rest_framework.permissions.IsAuthenticated",),
    "DEFAULT_AUTHENTICATION_CLASSES": (
        "rest_framework.authentication.SessionAuthentication",
        "easyjwt_auth.authentication.JWTAuthentication",
    ),
}

EASY_JWT = {
    "ACCESS_TOKEN_LIFETIME": timedelta(minutes=5),
    "REFRESH_TOKEN_LIFETIME": timedelta(days=1),
    "ROTATE_REFRESH_TOKENS": False,
    "BLACKLIST_AFTER_ROTATION": False,
    "UPDATE_LAST_LOGIN": False,
    "ALGORITHM": "HS256",
    "SIGNING_KEY": "d577273ff885c3f84dadb8578bb40000",  # Set properly for production!
    "VERIFYING_KEY": None,
    "AUDIENCE": None,
    "ISSUER": None,
    "JWK_URL": None,
    "LEEWAY": 0,
    "USER_ID_FIELD": "id",
    "USER_ID_CLAIM": "user_id",
    "USER_AUTHENTICATION_RULE": "easyjwt_auth.authentication.default_user_authentication_rule",
    "AUTH_TOKEN_CLASSES": ("easyjwt_auth.tokens.AccessToken",),
    "TOKEN_TYPE_CLAIM": "token_type",
    "TOKEN_USER_CLASS": "easyjwt_auth.models.TokenUser",
    "JTI_CLAIM": "jti",
    "CHECK_REVOKE_TOKEN": False,
    "SLIDING_TOKEN_REFRESH_EXP_CLAIM": "refresh_exp",
    "SLIDING_TOKEN_LIFETIME": timedelta(minutes=5),
    "SLIDING_TOKEN_REFRESH_LIFETIME": timedelta(days=1),
}

Add to config/urls.py:

from django.urls import path, include

urlpatterns = [
    # ...
    path('auth/', include('easyjwt_auth.urls')),
    path('auth/', include('easyjwt_user.urls')),
]

Run migrations and create a superuser:

uv run python manage.py makemigrations
uv run python manage.py migrate
uv run python manage.py createsuperuser
uv run python manage.py runserver 0.0.0.0:8000

Create a Client-Service

cd ..
uv venv
source .venv/bin/activate
uv pip install django django_rest_framework django_easyjwt
uv run django-admin startproject config
mv config client-service
cd client-service

Add to config/settings.py:

INSTALLED_APPS = [
    # ...
    'rest_framework',
    'easyjwt_client',
    'easyjwt_user',
]

AUTH_USER_MODEL = "easyjwt_user.User"

REST_FRAMEWORK = {
    "DEFAULT_PERMISSION_CLASSES": ("rest_framework.permissions.IsAuthenticated",),
    "DEFAULT_AUTHENTICATION_CLASSES": (
        "easyjwt_client.authentication.EasyJWTAuthentication",
        "rest_framework.authentication.SessionAuthentication",
    ),
}

AUTHENTICATION_BACKENDS = [
    'django.contrib.auth.backends.ModelBackend',
    'easyjwt_client.authentication.RemoteAuthBackend',
]

EASY_JWT = {
    "AUTH_HEADER_TYPES": ("Bearer",),
    "AUTH_HEADER_NAME": "Authorization",
    "REMOTE_AUTH_SERVICE_URL": "http://127.0.0.1:8000",
    "REMOTE_AUTH_SERVICE_TOKEN_PATH": "/auth/token/",
    "REMOTE_AUTH_SERVICE_REFRESH_PATH": "/auth/token/refresh/",
    "REMOTE_AUTH_SERVICE_VERIFY_PATH": "/auth/token/verify/",
    "REMOTE_AUTH_SERVICE_USER_PATH": "/auth/user/",
    "REMOTE_AUTH_SERVICE_PASSWORD_CHANGE_PATH": "/auth/password-change/",
    "REMOTE_AUTH_REQUEST_TIMEOUT": 30,
    "REMOTE_AUTH_SSL_VERIFY": True,
    "USER_ID_FIELD": "id",
    "USER_ID_CLAIM": "user_id",
}

Add to config/urls.py:

from django.urls import path, include
from test_app.views import TestView

urlpatterns = [
    path('admin/', admin.site.urls),
    path('auth/', include("easyjwt_client.urls")),
    path('api/test/', TestView.as_view()),
]

Create test_app/views.py:

from rest_framework import generics
from rest_framework.response import Response

class TestView(generics.GenericAPIView):
    def get(self, request):
        return Response("success", status=200)

Run migrations:

uv run python manage.py makemigrations
uv run python manage.py migrate
uv run python manage.py runserver 0.0.0.0:8001

Standing up the Services

Run both services in separate terminals:

# Terminal 1 - Auth-Service
cd auth-service
source .venv/bin/activate
uv run python manage.py runserver 0.0.0.0:8000

# Terminal 2 - Client-Service
cd client-service
source .venv/bin/activate
uv run python manage.py runserver 0.0.0.0:8001

Configuration Reference

Auth-Service Settings

Client-Service Settings

API Endpoints

Auth-Service (easyjwt_auth.urls)

Client-Service (easyjwt_client.urls)

User (easyjwt_user.urls)

Testing the API

Obtain Token Pair

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"email": "user@test.com", "password": "user-pass"}' \
  http://127.0.0.1:8001/auth/token/

Response:

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

Make Authenticated Request

export ACCESS_TOKEN=<your_access_token>

curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  http://127.0.0.1:8001/api/test/

Response: "success"

Refresh Token

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"refresh": "${REFRESH_TOKEN}"}' \
  http://127.0.0.1:8001/auth/token/refresh/

Verify Token

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"token": "${ACCESS_TOKEN}"}' \
  http://127.0.0.1:8001/auth/token/verify/

Create User (Auth-Service)

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"email": "newuser@test.com", "password": "S3cure!P@ssw0rd"}' \
  http://127.0.0.1:8000/auth/create-user/

Response:

{
  "id": 1,
  "email": "newuser@test.com",
  "first_name": "",
  "last_name": "",
  "phone": null
}

Change Password (Auth-Service)

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"email": "user@test.com", "password": "old-pass", "new_password": "N3wP@ss!2026"}' \
  http://127.0.0.1:8000/auth/password-change/

Get User Profile

curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  http://127.0.0.1:8000/auth/user/

Response:

{
  "id": 1,
  "email": "user@test.com",
  "first_name": "Test",
  "last_name": "User"
}

Advanced Usage

Extra Data

You can pass additional user data from the auth-service to client-services using custom serializers.

Auth-Service Configuration

models.py:

class AccessGroup(models.Model):
    user = models.OneToOneField(User, related_name="accessgroup", on_delete=models.CASCADE)
    user_type = models.TextField()

serializers.py:

class AccessGroupSerializer(serializers.ModelSerializer):
    class Meta:
        model = AccessGroup
        fields = ("user_type",)

class TokenUserSerializer(serializers.ModelSerializer):
    accessgroup = AccessGroupSerializer()

    class Meta:
        model = User
        fields = ("id", "email", "first_name", "last_name", "accessgroup")

Add to EASY_JWT settings:

"USER_MODEL_SERIALIZER": "userdata.serializers.TokenUserSerializer",

Client-Service Configuration

Use the same model and serializer, but override create() and update() methods:

class TokenUserSerializer(serializers.ModelSerializer):
    accessgroup = AccessGroupSerializer()

    class Meta:
        model = User
        fields = ("id", "email", "first_name", "last_name", "accessgroup")

    def create(self, validated_data):
        accessgroup = validated_data.pop("accessgroup")
        user, _ = User.objects.get_or_create(
            email=validated_data.pop("email"),
            defaults=validated_data
        )
        AccessGroup.objects.update_or_create(user=user, defaults=accessgroup)
        return user

    def update(self, instance, validated_data):
        accessgroup = validated_data.pop("accessgroup")
        for attr, value in validated_data.items():
            setattr(instance, attr, value)
        instance.save()
        AccessGroup.objects.update_or_create(user=instance, defaults=accessgroup)
        return instance

Permissions

Use custom permission classes to control access based on user data:

from rest_framework import permissions

class AccessGroupPermission(permissions.BasePermission):
    message = "You do not have permission to this service"

    def has_permission(self, request, view):
        return (
            not request.user.is_anonymous
            and hasattr(request.user, 'accessgroup')
            and view.access_level.startswith(request.user.accessgroup.user_type)
        )

Refresh-Token Cookies & CSRF

By default, refresh tokens are returned in the JSON response body — suitable for mobile apps and server-to-server clients. For browser-based SPAs, enable cookie mode so the refresh token is stored in an HttpOnly cookie and never exposed to JavaScript:

EASY_JWT = {
    ...,
    "REFRESH_TOKEN_IN_COOKIE": True,
}

When enabled:

• Login (token/) sets the refresh token as an HttpOnly cookie and removes it from the JSON body (XSS protection — JavaScript cannot read it).
• Refresh (token/refresh/) reads the refresh token from the cookie (not the body) and rotates the cookie if ROTATE_REFRESH_TOKENS is enabled on the auth-service.
• Logout (token/logout/) clears the cookie and best-effort blacklists the token server-side.
• CSRF protection is automatically applied to all three endpoints.

Non-browser clients should leave REFRESH_TOKEN_IN_COOKIE = False and continue reading refresh tokens from the JSON body.

Cookie Settings

CSRF Requirements

Cookie mode requires django.middleware.csrf.CsrfViewMiddleware in MIDDLEWARE (enforced by the E002 system check). The library ships a bootstrap endpoint:

1. SPA calls GET <client>/csrf/ — Django emits the csrftoken cookie.
2. SPA reads the csrftoken cookie from document.cookie.
3. SPA sends it in the X-CSRFToken header on POST requests to token/, token/refresh/, and token/logout/.

W002 warning: CSRF_COOKIE_HTTPONLY=True is incompatible with this bootstrap pattern — JavaScript cannot read the cookie. If you need HttpOnly CSRF cookies, deliver the token via a rendered {% csrf_token %} tag in HTML instead.

Deployment Tiers

ALLOWED_AUTH_ORIGINS performs defense-in-depth Origin validation; it does not by itself make cross-origin cookie authentication work — CORS and CSRF_TRUSTED_ORIGINS configuration is required for tier B.

Auth-Service Prerequisites

The logout blacklist call requires:

1. easyjwt_auth.token_blacklist in INSTALLED_APPS on the auth-service.
2. The token/blacklist/ route (wired by default in easyjwt_auth/urls.py).
3. ROTATE_REFRESH_TOKENS=True on the auth-service for refresh-token rotation to rewrite the cookie. BLACKLIST_AFTER_ROTATION=True is recommended to revoke the previous refresh token but is not required for the cookie rewrite.

Logout Caveats

• Blacklisting a refresh token does not invalidate an already-issued access JWT — keep access tokens short-lived.
• The frontend must also discard its in-memory access token on logout.
• The blacklist call is best-effort: if the auth-service is unreachable, the cookie is still cleared (logged out on the client), but a copied refresh token remains valid until its natural expiry.

Security

• Password Validation: Django's AUTH_PASSWORD_VALIDATORS are enforced on both the create-user/ and password-change/ endpoints
• Email Normalization: User creation uses UserManager.create_user() which normalizes and lowercases email addresses
• Credential Verification: Password change requires the current password — old credentials are verified before accepting a new password
• Error Sanitization: Remote auth error responses do not leak upstream server details (raw response bodies, tracebacks) to clients
• SSL/HTTP Warnings: The client app logs a warning at startup when DEBUG=False and either SSL_VERIFY=False or REMOTE_AUTH_SERVICE_URL uses http://
• Token Revocation: Optional CHECK_REVOKE_TOKEN invalidates all outstanding JWTs when a user changes their password
• Token Blacklisting: Optional easyjwt_auth.token_blacklist app provides server-side token revocation with outstanding token tracking

Running Tests

uv pip install -e ".[dev]"
uv run pytest

Or with coverage:

uv run pytest --cov=easyjwt_auth --cov=easyjwt_client --cov=easyjwt_user

Changelog

See CHANGELOG.md for full version history.

v1.0.6+

• Fixed TOKEN_USER_CLASS default pointing to wrong module path
• CreateUserSerializer now uses create_user() for email normalization
• Added REMOTE_AUTH_SERVICE_PASSWORD_CHANGE_PATH setting (was hardcoded)
• TokenViewBase serializer classes resolved at runtime, not import time
• Added catch-all requests.RequestException handler for unhandled HTTP errors
• Merged CI publish workflow into version workflow (fixes [skip ci] blocking PyPI)

v1.0.5+

• Security hardening — 21 review issues fixed across security, bugs, design, and test coverage
• Removed dead jwt_secret field (migration 0002)
• Unified settings access via api_settings across all modules
• RemoteAuthBackend inherits BaseBackend (correct Django signature)
• Added comprehensive test coverage (61% → 88%, 155 tests)
• Password confirmation check, response sanitization, admin password validation
• SSL/HTTP production warning in client apps.py

v1.0.0

• Replaced MD5 with SHA-256 for password hashing
• Renamed ModelBackend to RemoteAuthBackend
• Added configurable HTTP request timeouts
• Made SSL verification configurable
• Consolidated HTTP error handling
• Added __all__ exports to public modules

Acknowledgements

This package is heavily based on djangorestframework-simplejwt and influenced by SimpleJWT.

An example implementation is available at django-easyjwt-example.

License

MIT License - see LICENCE file.