django-channels-jwt-stateless

Stateless JWT authentication middleware for Django Channels. Zero database queries on WebSocket handshake.

Existing Django Channels JWT packages call User.objects.get() on every WebSocket connect. Under burst traffic this saturates the connection pool and causes multi-second stalls. This package verifies the JWT signature and builds a lightweight HandshakeUser from the token claims instead.

Install

pip install django-channels-jwt-stateless

Quick Start

# asgi.py
from channels.routing import ProtocolTypeRouter, URLRouter
from django_channels_jwt_stateless import JWTAuthMiddleware

application = ProtocolTypeRouter({
    "http": django_application,
    "websocket": JWTAuthMiddleware(URLRouter(websocket_urlpatterns)),
})

Works out of the box with djangorestframework-simplejwt defaults (HS256, SECRET_KEY, user_id claim). Pass the token as ?token=<jwt> in the WebSocket URL.

JWTAuthMiddlewareStack

Use JWTAuthMiddlewareStack instead only when your consumers need scope["session"] or scope["cookies"]. Two things to know:

• The session user never reaches scope["user"]: this middleware always sets it first, so channels' AuthMiddleware only writes into an unread attribute. Session-cookie login is not a fallback.
• channels' get_user() still runs on every handshake (a database_sync_to_async hop, plus session and user DB queries for clients that carry a sessionid cookie), which partly defeats the purpose of this package. Prefer the bare middleware.

scope["user"]

On a valid token, scope["user"] is a HandshakeUser instance:

On an invalid, expired, or missing token it is AnonymousUser.

HandshakeUser is not a Django model instance: it has no _meta, so channels.auth.login(scope, user) raises AttributeError with it. Non-integer primary keys (e.g. UUID) arrive as strings, exactly as the JWT claim stores them; avoid == comparisons against uuid.UUID.

Configuration

Optional. Add to settings.py:

CHANNELS_JWT_STATELESS = {
    "ALGORITHM": "HS256",              # default
    "SIGNING_KEY": None,               # defaults to SECRET_KEY
    "USER_ID_CLAIM": "user_id",        # default
    "TOKEN_QUERY_PARAM": "token",      # default
    "IS_BLACKLISTED": None,            # dotted path to (jti) -> bool
    "TOKEN_DECODER": None,             # dotted path to (token) -> dict
    "SUBPROTOCOL_PREFIX": None,        # e.g. "access_token"
}

TOKEN_DECODER and IS_BLACKLISTED accept both sync and async callables.

Token Blacklisting

# myapp/auth.py
from django.core.cache import cache

async def is_blacklisted(jti: str) -> bool:
    return await cache.aget(f"blacklist:{jti}") is not None

# settings.py
CHANNELS_JWT_STATELESS = {
    "IS_BLACKLISTED": "myapp.auth.is_blacklisted",
}

Subprotocol Auth

To avoid leaking tokens in query strings:

CHANNELS_JWT_STATELESS = {"SUBPROTOCOL_PREFIX": "access_token"}

Client sends Sec-WebSocket-Protocol: access_token.<jwt>.

Compatibility

Python 3.10+, Django 4.2+, Channels 4+, PyJWT 2+.

License

MIT