django-amzn-oidc-auth 1.0.0rc1

Django middleware and auth backend for OIDC authentication via AWS ALB

django-amzn-oidc-auth

Django middleware and authentication backend for apps deployed behind an AWS Application Load Balancer (ALB) with OIDC authentication enabled.

How it works

When an ALB is configured with OIDC, it handles the full OAuth2 flow and injects a signed JWT into every upstream request via the x-amzn-oidc-data header. This package:

1. Validates the JWT signature using the ALB's region-specific public key (fetched from AWS and cached)
2. Maps the decoded claims to a Django User (creating one on first login if configured)
3. Establishes a normal Django session — groups, permissions, @login_required, and request.user all work as usual

Installation

pip install django-amzn-oidc-auth

or

uv add django-amzn-oidc-auth

Setup

Add to INSTALLED_APPS, MIDDLEWARE, and AUTHENTICATION_BACKENDS:

INSTALLED_APPS = [
    ...
    "django_amzn_oidc_auth",
]

MIDDLEWARE = [
    "django.contrib.sessions.middleware.SessionMiddleware",
    "django.contrib.auth.middleware.AuthenticationMiddleware",
    "django_amzn_oidc_auth.middleware.AmznOidcMiddleware",
    ...
]

AUTHENTICATION_BACKENDS = [
    "django_amzn_oidc_auth.backends.AmznOidcAuthBackend",
    "django.contrib.auth.backends.ModelBackend",
]

Settings

Setting	Default	Description
AWS_REGION	required	Region used to fetch ALB public keys
AMZN_OIDC_BYPASS_VALIDATION	False	Skip JWT signature check — dev only
AMZN_OIDC_AUTO_CREATE_USERS	True	Create Django users on first login
AMZN_OIDC_EXEMPT_PATHS	[]	Paths that skip OIDC auth (e.g. health checks)
AMZN_OIDC_USERNAME_CLAIM	sub	OIDC claim to use as the Django username. Defaults to sub. Set this if your IdP uses a different stable identifier (e.g. "preferred_username"). Changing this on an existing deployment will break logins for users whose accounts were created under the old claim value.
AMZN_OIDC_AUDIENCE	None	Expected value of the JWT aud claim. When set, tokens whose aud does not match are rejected — recommended when multiple applications share the same ALB to prevent cross-application token replay. When unset, audience validation is skipped.

Usage in views

Once the middleware is active, every authenticated request has a populated request.user (a standard Django User instance) and request.oidc_claims (the raw decoded JWT payload).

Function-based views

from django.contrib.auth.decorators import login_required
from django.http import JsonResponse

@login_required
def profile(request):
    return JsonResponse({
        "username": request.user.username,
        "email": request.user.email,
    })

def debug_claims(request):
    # Raw OIDC payload — useful during development
    return JsonResponse(request.oidc_claims)

Class-based views

from django.contrib.auth.mixins import LoginRequiredMixin
from django.views import View
from django.http import JsonResponse

class ProfileView(LoginRequiredMixin, View):
    def get(self, request):
        return JsonResponse({"username": request.user.username})

LoginRequiredMixin and @login_required both work because the middleware establishes a normal Django session — the auth decorators don't know or care that authentication came from an ALB header.

Checking permissions and groups

Standard Django permission checks work unchanged:

@login_required
def admin_only(request):
    if not request.user.has_perm("myapp.change_widget"):
        return HttpResponseForbidden()
    ...

Health check / unauthenticated paths

Add paths that should bypass OIDC to AMZN_OIDC_EXEMPT_PATHS. The middleware passes these through without checking the x-amzn-oidc-data header, so load-balancer health checks and similar endpoints keep working even before a session exists:

AMZN_OIDC_EXEMPT_PATHS = ["/healthcheck/", "/readyz/"]

Accessing raw OIDC claims

request.oidc_claims contains the full decoded JWT payload from the ALB. This is useful when your OIDC provider includes custom claims (e.g. roles, tenant ID) beyond what Django's User model stores.

Authorising based on a custom claim

from django.http import HttpResponseForbidden

def admin_dashboard(request):
    roles = request.oidc_claims.get("custom:roles", [])
    if "admin" not in roles:
        return HttpResponseForbidden()
    ...

Multi-tenant routing

def my_view(request):
    tenant = request.oidc_claims.get("custom:tenant_id")
    queryset = Widget.objects.filter(tenant=tenant)
    ...

Using a claim as the Django username

If your IdP uses preferred_username (or another claim) as the stable account identifier instead of sub, configure it via AMZN_OIDC_USERNAME_CLAIM:

# settings.py
AMZN_OIDC_USERNAME_CLAIM = "preferred_username"

Note: Only set this on a fresh deployment, or when you are prepared to migrate existing User rows. Changing the claim on an existing deployment means Django will look up users by the new claim value and won't find accounts that were created under the old one.

Enriching the user model from claims

If you need to store extra claim data on first login (e.g. a department or employee ID), subclass the backend:

from django_amzn_oidc_auth.backends import AmznOidcAuthBackend

class MyBackend(AmznOidcAuthBackend):
    def _sync_user_fields(self, user, claims):
        super()._sync_user_fields(user, claims)
        # profile is a OneToOneField added by your app
        user.profile.department = claims.get("custom:department", "")
        user.profile.save()

Register MyBackend in place of (or in addition to) the default in AUTHENTICATION_BACKENDS.

Local development

Set AMZN_OIDC_BYPASS_VALIDATION = True and send an unsigned JWT in the x-amzn-oidc-data header:

python -c "
import jwt, time
print(jwt.encode({'sub': 'dev-user', 'email': '[e-mail]',
    'iss': 'https://example.com', 'exp': int(time.time()) + 3600},
    'ignored', algorithm='HS256'))
"