Litestar API

Litestar integration for py oidc auth.

Litestar is an async framework with dependency injection. This adapter integrates authentication using Litestar’s litestar.di.Provide.

Install:

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

Usage

from litestar import Litestar, get
from py_oidc_auth.litestar_auth import LitestarOIDCAuth
from py_oidc_auth.schema import IDToken

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

@get("/protected", dependencies={"token": auth.required()})
async def protected(token: IDToken) -> dict:
    return {"sub": token.sub}

app = Litestar(route_handlers=[auth.create_auth_router(prefix="/api"), protected])

class py_oidc_auth.litestar_auth.LitestarOIDCAuth(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 OpenID Connect helper for Litestar.

The public surface is:

• required() and optional() for dependency injection

• create_auth_router() for standard auth routes. When

broker_mode=True the providers verify broker JWTs and the router token endpoint issues broker JWTs instead of passing IDP tokens through.

required(claims: Dict[str, Any] | None = None, scopes: str = '') → litestar.di.Provide

Return a litestar.di.Provide that enforces authentication.

Parameters:

• claims – Optional claim constraints.

• scopes – Space separated scope names.

Returns:

Provide instance usable in dependencies.

Example

@get("/protected", dependencies={"token": auth.required(scopes="admin")})
async def protected(token: IDToken) -> dict:
    return {"sub": token.sub}

optional(claims: Dict[str, Any] | None = None, scopes: str = '') → litestar.di.Provide

Return a litestar.di.Provide that allows anonymous access.

Parameters:

• claims – Optional claim constraints.

• scopes – Space separated scope names.

Returns:

Provide instance.

create_auth_router(prefix: str = '', login: str | None = '/auth/v2/login', callback: str | None = '/auth/v2/callback', token: str | None = '/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') → litestar.Router

Build a Litestar litestar.Router with standard auth routes.

Parameters:

• prefix – URL prefix for all routes.

• 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:

Router instance.

Raises:

ValueError – When broker_mode=True and token is falsy.

Request example

GET /auth/v2/userinfo HTTP/1.1
Host: app.example.org
Authorization: Bearer <access token>