Django API#

Django integration for py-oidc-auth.

Requires Django 4.1+ async views and an ASGI server (e.g. uvicorn, daphne, hypercorn). The broker verify() call is synchronous.

Install:

pip install py-oidc-auth[django]
conda install -c conda-forge py-oidc-auth-django

Usage:

# views.py
from django.http import JsonResponse
from py_oidc_auth.django_auth import DjangoOIDCAuth

auth = DjangoOIDCAuth(
    client_id="my-client",
    discovery_url="https://kc.example.com/realms/myrealm/.well-known/openid-configuration",
    scopes="myscope profile email",
    broker_mode=True,
    broker_store_url="postgresql+asyncpg://user:pw@db/myapp",
)

@auth.required()
async def protected(request, token):
    return JsonResponse({"sub": token.sub})

# urls.py
from django.urls import path, include

urlpatterns = [
    path("api/myapp/", include(auth.get_urlpatterns())),
    path("protected", protected),
]
class py_oidc_auth.django_auth.DjangoOIDCAuth(client_id: str = '', discovery_url: str = '', client_secret: str | None = None, scopes: str = 'profile email', audience: str | None = None, appname: str = 'py-oidc-auth', proxy: str = '', claims: Dict[str, Any] | None = None, offline_access: bool = True, timeout_sec: int = 10, jwks_uri: str | None = None, issuer: str | None = None, broker_mode: bool = False, broker_store_url: str | None = None, broker_store_obj: BrokerStore | None = None, broker_audience: str = 'py-oidc-auth', trusted_issuers: list[str] | None = None, broker_jwks_path: str = '/auth/v2/.well-known/jwks.json')#

Reusable OIDC authentication wrapper for Django async views.

  • Use required() / optional() as view decorators.

  • Call get_urlpatterns() for a list of Django URL patterns with the standard OIDC endpoints. When broker_mode=True the token view issues broker JWTs and a JWKS view is included automatically.

required(claims: Dict[str, Any] | None = None, scopes: str = '') → Callable[[F], F]#

Enforce authentication on a Django async view.

The decorated view receives the validated IDToken as an extra argument after request.

Parameters:

  • claims – Optional claim constraints (passthrough mode only).

  • scopes – Space-separated scope names.

Returns:

Decorator for Django async views.

Example

@auth.required()
async def protected(request, token):
    return JsonResponse({"sub": token.sub})
optional(claims: Dict[str, Any] | None = None, scopes: str = '') → Callable[[F], F]#

Allow anonymous access.

The view receives IDToken | None as an extra argument.

Parameters:

  • claims – Optional claim constraints (passthrough mode only).

  • scopes – Space-separated scope names.

Returns:

Decorator for Django async views.

get_urlpatterns(login: str = 'auth/v2/login', callback: str = 'auth/v2/callback', token: str = 'auth/v2/token', device_flow: str | None = 'auth/v2/device', logout: str | None = 'auth/v2/logout', userinfo: str | None = 'auth/v2/userinfo', jwks: str | None = 'auth/v2/.well-known/jwks.json') → List[django.urls.URLPattern]#

Return a list of Django URL patterns for standard OIDC routes.

Parameters:

  • login – Path for login.

  • callback – Path for callback.

  • token – Path for token exchange / broker JWT issuance.

  • device_flow – Path for starting the device flow.

  • logout – Path for logout.

  • userinfo – Path for userinfo.

  • jwks – Path for JWKS (broker mode only).

Returns:

List of django.urls.URLPattern.

Raises:

ValueError – When broker_mode=True and token is falsy.

Usage:

from django.urls import path, include
urlpatterns = [
    path("api/myapp/", include(auth.get_urlpatterns())),
]

Note: route paths should not have a leading slash — Django convention uses relative paths inside include().