django-auth-external

JWT token generation and validation for Django. Built for architectures where one service issues tokens and multiple services validate them using a shared secret.

This library handles only the cryptographic layer: signing, verification, and expiry. Session invalidation and revocation are the responsibility of the consuming application.

install

pip install django-auth-external

With Django REST Framework support:

pip install django-auth-external[drf]

quick start

Define the token schema in settings.py:

AUTH_EXTERNAL = {
    "SECRET_KEY": "your-secret-key",
    "CLAIMS": ["user_id", "email", "modules"],
    "TOKEN_TTL_SECONDS": 28800,  # 8 hours
}

Add the middleware:

MIDDLEWARE = [
    ...
    "django_auth_external.middleware.AuthExternalMiddleware",
]

Generate a token (in the authentication service):

from django_auth_external import TokenConfig, generate_token

config = TokenConfig(secret_key="your-secret-key", claims=["user_id", "email", "modules"])
token = generate_token(
    {"user_id": "abc-123", "email": "user@example.com", "modules": ["api", "admin"]},
    config,
)

Validate in a view:

def my_view(request):
    if request.auth_payload is None:
        return HttpResponse(status=401)
    user_id = request.auth_payload["user_id"]
    ...

configuration

token generation

generate_token validates that the payload contains all configured claims before signing:

from django_auth_external import TokenConfig, generate_token
from django_auth_external.exceptions import MissingClaim

config = TokenConfig(secret_key="secret", claims=["user_id", "email"])

generate_token({"user_id": "abc"}, config)                          # raises MissingClaim: email
generate_token({"user_id": "abc", "email": "x@y.com"}, config)     # ok

Extra fields in the payload are included in the token without modification.

DRF integration

REST_FRAMEWORK = {
    "DEFAULT_AUTHENTICATION_CLASSES": [
        "django_auth_external.drf.ExternalTokenAuthentication",
    ],
}

request.user will be the token payload dict. request.auth will be the raw token string.

exceptions

All inherit from AuthExternalError.

license

MIT