session_auth#

class litestar.security.session_auth.SessionAuth#

Bases: Generic[UserType, BaseSessionBackendT], AbstractSecurityConfig[UserType, Dict[str, Any]]

Session Based Security Backend.

session_backend_config: BaseBackendConfig[BaseSessionBackendT]#

A session backend config.

retrieve_user_handler: Callable[[Any, ASGIConnection], SyncOrAsyncUnion[Any | None]]#

Callable that receives the auth value from the authentication middleware and returns a user value.

Notes

  • User and Auth can be any arbitrary values specified by the security backend.

  • The User and Auth values will be set by the middleware as scope["user"] and scope["auth"] respectively. Once provided, they can access via the connection.user and connection.auth properties.

  • The callable can be sync or async. If it is sync, it will be wrapped to support async.

authentication_middleware_class#

alias of SessionAuthMiddleware

guards: Iterable[Guard] | None = None#

An iterable of guards to call for requests, providing authorization functionalities.

exclude: str | list[str] | None = None#

A pattern or list of patterns to skip in the authentication middleware.

exclude_opt_key: str = 'exclude_from_auth'#

An identifier to use on routes to disable authentication and authorization checks for a particular route.

__init__(session_backend_config: BaseBackendConfig[BaseSessionBackendT], retrieve_user_handler: Callable[[Any, ASGIConnection], SyncOrAsyncUnion[Any | None]], authentication_middleware_class: type[SessionAuthMiddleware] = <class 'litestar.security.session_auth.middleware.SessionAuthMiddleware'>, guards: Iterable[Guard] | None = None, exclude: str | list[str] | None = None, exclude_opt_key: str = 'exclude_from_auth', exclude_http_methods: Sequence[Method] | None = <factory>, scopes: Scopes | None = None, route_handlers: Iterable[ControllerRouterHandler] | None = None, dependencies: dict[str, Provide] | None = None, type_encoders: TypeEncodersMap | None = None) → None#
scopes: Scopes | None = None#

ASGI scopes processed by the authentication middleware, if None, both http and websocket will be processed.

route_handlers: Iterable[ControllerRouterHandler] | None = None#

An optional iterable of route handlers to register.

dependencies: dict[str, Provide] | None = None#

An optional dictionary of dependency providers.

type_encoders: TypeEncodersMap | None = None#

A mapping of types to callables that transform them into types supported for serialization.

property middleware: DefineMiddleware#

Use this property to insert the config into a middleware list on one of the application layers.

Examples

from typing import Any
from os import urandom

from litestar import Litestar, Request, get
from litestar_session import SessionAuth


async def retrieve_user_from_session(session: dict[str, Any]) -> Any:
    # implement logic here to retrieve a ``user`` datum given the session dictionary
    ...


session_auth_config = SessionAuth(
    secret=urandom(16), retrieve_user_handler=retrieve_user_from_session
)


@get("/")
def my_handler(request: Request) -> None: ...


app = Litestar(route_handlers=[my_handler], middleware=[session_auth_config.middleware])
Returns:

An instance of DefineMiddleware including self as the config kwarg value.

property session_backend: BaseSessionBackendT#

Create a session backend.

Returns:

A subclass of BaseSessionBackend

property openapi_components: Components#

Create OpenAPI documentation for the Session Authentication schema used.

Returns:

An Components instance.

property security_requirement: Dict[str, List[str]]#

Return OpenAPI 3.1.

SecurityRequirement for the auth backend.

Returns:

An OpenAPI 3.1 SecurityRequirement dictionary.

class litestar.security.session_auth.middleware.SessionAuthMiddleware#

Bases: AbstractAuthenticationMiddleware

Session Authentication Middleware.

__init__(app: ASGIApp, exclude: str | list[str] | None, exclude_http_methods: Sequence[Method] | None, exclude_opt_key: str, retrieve_user_handler: Callable[[dict[str, Any], ASGIConnection[Any, Any, Any, Any]], Awaitable[Any]], scopes: Scopes | None) → None#

Session based authentication middleware.

Parameters:

  • app – An ASGIApp, this value is the next ASGI handler to call in the middleware stack.

  • exclude – A pattern or list of patterns to skip in the authentication middleware.

  • exclude_http_methods – A sequence of http methods that do not require authentication.

  • exclude_opt_key – An identifier to use on routes to disable authentication and authorization checks for a particular route.

  • scopes – ASGI scopes processed by the authentication middleware.

  • retrieve_user_handler – Callable that receives the session value from the authentication middleware and returns a user value.

async authenticate_request(connection: ASGIConnection[Any, Any, Any, Any]) → AuthenticationResult#

Authenticate an incoming connection.

Parameters:

connection – An ASGIConnection instance.

Raises:

NotAuthorizedException – if session data is empty or user is not found.

Returns:

AuthenticationResult