jwt#

class litestar.security.jwt.BaseJWTAuth#

Bases: Generic[UserType], AbstractSecurityConfig[UserType, Token]

Base class for JWT Auth backends

token_secret: str#

Key with which to generate the token hash.

Notes

This value should be kept as a secret and the standard practice is to inject it into the environment.

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.

algorithm: str#: Algorithm to use for JWT hashing.

auth_header: str#

Request header key from which to retrieve the token.

E.g. Authorization or X-Api-Key.

default_token_expiration: timedelta#: The default value for token expiration.

openapi_security_scheme_name: str#: The value to use for the OpenAPI security scheme and security requirements.

description: str#: Description for the OpenAPI security scheme.

authentication_middleware_class: type[JWTAuthenticationMiddleware]#

The authentication middleware class to use.

Must inherit from JWTAuthenticationMiddleware

property openapi_components: Components#

Create OpenAPI documentation for the JWT auth schema used.

Returns:: An Components instance.

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

Return OpenAPI 3.1.

SecurityRequirement

Returns:: An OpenAPI 3.1 SecurityRequirement dictionary.

property middleware: DefineMiddleware#

Create JWTAuthenticationMiddleware wrapped in DefineMiddleware.

Returns:: An instance of DefineMiddleware.

login(identifier: str, *, response_body: Any = _EmptyEnum.EMPTY, response_media_type: str | MediaType = MediaType.JSON, response_status_code: int = 201, token_expiration: timedelta | None = None, token_issuer: str | None = None, token_audience: str | None = None, token_unique_jwt_id: str | None = None, token_extras: dict[str, Any] | None = None, send_token_as_response_body: bool = False) → Response[Any]#

Create a response with a JWT header.

Parameters:

identifier¶ – Unique identifier of the token subject. Usually this is a user ID or equivalent kind of value.
response_body¶ – An optional response body to send.
response_media_type¶ – An optional Content-Type. Defaults to application/json.
response_status_code¶ – An optional status code for the response. Defaults to 201.
token_expiration¶ – An optional timedelta for the token expiration.
token_issuer¶ – An optional value of the token iss field.
token_audience¶ – An optional value for the token aud field.
token_unique_jwt_id¶ – An optional value for the token jti field.
token_extras¶ – An optional dictionary to include in the token extras field.
send_token_as_response_body¶ – If True the response will be a dict including the token: { "token": <token> } will be returned as the response body. Note: if a response body is passed this setting will be ignored.

Returns:

A Response instance.

Create a Token instance from the passed in parameters, persists and returns it.

Parameters:

identifier¶ – Unique identifier of the token subject. Usually this is a user ID or equivalent kind of value.
token_expiration¶ – An optional timedelta for the token expiration.
token_issuer¶ – An optional value of the token iss field.
token_audience¶ – An optional value for the token aud field.
token_unique_jwt_id¶ – An optional value for the token jti field.
token_extras¶ – An optional dictionary to include in the token extras field.

Returns:

The created token.

format_auth_header(encoded_token: str) → str#

Format a token according to the specified OpenAPI scheme.

Parameters:: encoded_token¶ – An encoded JWT token
Returns:: The encoded token formatted for the HTTP headers

class litestar.security.jwt.JWTAuth#

Bases: Generic[UserType], BaseJWTAuth[UserType]

JWT Authentication Configuration.

This class is the main entry point to the library, and it includes methods to create the middleware, provide login functionality, and create OpenAPI documentation.

token_secret: str#

Key with which to generate the token hash.

Notes

This value should be kept as a secret and the standard practice is to inject it into the environment.

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.

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.

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.

algorithm: str = 'HS256'#: Algorithm to use for JWT hashing.

auth_header: str = 'Authorization'#

Request header key from which to retrieve the token.

E.g. Authorization or X-Api-Key.

default_token_expiration: timedelta#: The default value for token expiration.

openapi_security_scheme_name: str = 'BearerToken'#: The value to use for the OpenAPI security scheme and security requirements.

description: str = 'JWT api-key authentication and authorization.'#: Description for the OpenAPI security scheme.

authentication_middleware_class#: alias of JWTAuthenticationMiddleware

__init__(token_secret: str, retrieve_user_handler: Callable[[Any, ASGIConnection], SyncOrAsyncUnion[Any | None]], 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, algorithm: str = 'HS256', auth_header: str = 'Authorization', default_token_expiration: timedelta = <factory>, openapi_security_scheme_name: str = 'BearerToken', description: str = 'JWT api-key authentication and authorization.', authentication_middleware_class: type[JWTAuthenticationMiddleware] = <class 'litestar.security.jwt.middleware.JWTAuthenticationMiddleware'>) → None#

class litestar.security.jwt.JWTAuthenticationMiddleware#

Bases: AbstractAuthenticationMiddleware

JWT Authentication middleware.

This class provides JWT authentication functionalities.

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

Check incoming requests for an encoded token in the auth header specified, and if present retrieve the user from persistence using the provided function.

Parameters:

algorithm¶ – JWT hashing algorithm to use.
app¶ – An ASGIApp, this value is the next ASGI handler to call in the middleware stack.
auth_header¶ – Request header key from which to retrieve the token. E.g. Authorization or X-Api-Key.
exclude¶ – A pattern or list of patterns to skip.
exclude_opt_key¶ – An identifier to use on routes to disable authentication for a particular route.
exclude_http_methods¶ – A sequence of http methods that do not require authentication.
retrieve_user_handler¶ – A function that receives a Token and returns a user, which can be any arbitrary value.
scopes¶ – ASGI scopes processed by the authentication middleware.
token_secret¶ – Secret for decoding the JWT token. This value should be equivalent to the secret used to encode it.

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

Given an HTTP Connection, parse the JWT api key stored in the header and retrieve the user correlating to the token from the DB.

Parameters:: connection¶ – An Litestar HTTPConnection instance.
Returns:: AuthenticationResult
Raises:: NotAuthorizedException – If token is invalid or user is not found.

async authenticate_token(encoded_token: str, connection: ASGIConnection[Any, Any, Any, Any]) → AuthenticationResult#

Given an encoded JWT token, parse, validate and look up sub within token.

Parameters:

encoded_token¶ – Encoded JWT token.
connection¶ – An ASGI connection instance.

Raises:

NotAuthorizedException – If token is invalid or user is not found.

Returns:

AuthenticationResult

class litestar.security.jwt.JWTCookieAuth#

Bases: Generic[UserType], BaseJWTAuth[UserType]

JWT Cookie Authentication Configuration.

This class is an alternate entry point to the library, and it includes all the functionality of the JWTAuth class and adds support for passing JWT tokens HttpOnly cookies.

token_secret: str#

Key with which to generate the token hash.

Notes

This value should be kept as a secret and the standard practice is to inject it into the environment.

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.

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.

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.

algorithm: str = 'HS256'#: Algorithm to use for JWT hashing.

auth_header: str = 'Authorization'#

Request header key from which to retrieve the token.

E.g. Authorization or X-Api-Key.

default_token_expiration: timedelta#: The default value for token expiration.

openapi_security_scheme_name: str = 'BearerToken'#: The value to use for the OpenAPI security scheme and security requirements.

key: str = 'token'#: Key for the cookie.

path: str = '/'#

Path fragment that must exist in the request url for the cookie to be valid.

Defaults to /.

__init__(token_secret: str, retrieve_user_handler: Callable[[Any, ASGIConnection], SyncOrAsyncUnion[Any | None]], guards: Iterable[Guard] | None = None, exclude: str | list[str] | None = None, exclude_opt_key: str = 'exclude_from_auth', scopes: Scopes | None = None, exclude_http_methods: Sequence[Method] | None = <factory>, route_handlers: Iterable[ControllerRouterHandler] | None = None, dependencies: dict[str, Provide] | None = None, type_encoders: TypeEncodersMap | None = None, algorithm: str = 'HS256', auth_header: str = 'Authorization', default_token_expiration: timedelta = <factory>, openapi_security_scheme_name: str = 'BearerToken', key: str = 'token', path: str = '/', domain: str | None = None, secure: bool | None = None, samesite: Literal['lax', 'strict', 'none'] = 'lax', description: str = 'JWT cookie-based authentication and authorization.', authentication_middleware_class: type[JWTCookieAuthenticationMiddleware] = <class 'litestar.security.jwt.middleware.JWTCookieAuthenticationMiddleware'>) → None#

domain: str | None = None#: Domain for which the cookie is valid.

secure: bool | None = None#: Https is required for the cookie.

samesite: Literal['lax', 'strict', 'none'] = 'lax'#: Controls whether or not a cookie is sent with cross-site requests. Defaults to lax.

description: str = 'JWT cookie-based authentication and authorization.'#: Description for the OpenAPI security scheme.

authentication_middleware_class#: alias of JWTCookieAuthenticationMiddleware

property openapi_components: Components#

Create OpenAPI documentation for the JWT Cookie auth scheme.

Returns:: A Components instance.

property middleware: DefineMiddleware#

Create JWTCookieAuthenticationMiddleware wrapped in: DefineMiddleware.

Returns:: An instance of DefineMiddleware.

login(identifier: str, *, response_body: Any = _EmptyEnum.EMPTY, response_media_type: str | MediaType = MediaType.JSON, response_status_code: int = 201, token_expiration: timedelta | None = None, token_issuer: str | None = None, token_audience: str | None = None, token_unique_jwt_id: str | None = None, token_extras: dict[str, Any] | None = None, send_token_as_response_body: bool = False) → Response[Any]#

Create a response with a JWT header.

Parameters:

identifier¶ – Unique identifier of the token subject. Usually this is a user ID or equivalent kind of value.
response_body¶ – An optional response body to send.
response_media_type¶ – An optional ‘Content-Type’. Defaults to ‘application/json’.
response_status_code¶ – An optional status code for the response. Defaults to ‘201 Created’.
token_expiration¶ – An optional timedelta for the token expiration.
token_issuer¶ – An optional value of the token iss field.
token_audience¶ – An optional value for the token aud field.
token_unique_jwt_id¶ – An optional value for the token jti field.
token_extras¶ – An optional dictionary to include in the token extras field.
send_token_as_response_body¶ – If True the response will be a dict including the token: { "token": <token> } will be returned as the response body. Note: if a response body is passed this setting will be ignored.

Returns:

A Response instance.

class litestar.security.jwt.JWTCookieAuthenticationMiddleware#

Bases: JWTAuthenticationMiddleware

Cookie based JWT authentication middleware.

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

Check incoming requests for an encoded token in the auth header or cookie name specified, and if present retrieves the user from persistence using the provided function.

Parameters:

algorithm¶ – JWT hashing algorithm to use.
app¶ – An ASGIApp, this value is the next ASGI handler to call in the middleware stack.
auth_cookie_key¶ – Cookie name from which to retrieve the token. E.g. token or accessToken.
auth_header¶ – Request header key from which to retrieve the token. E.g. Authorization or X-Api-Key.
exclude¶ – A pattern or list of patterns to skip.
exclude_opt_key¶ – An identifier to use on routes to disable authentication for a particular route.
exclude_http_methods¶ – A sequence of http methods that do not require authentication.
retrieve_user_handler¶ – A function that receives a Token and returns a user, which can be any arbitrary value.
scopes¶ – ASGI scopes processed by the authentication middleware.
token_secret¶ – Secret for decoding the JWT token. This value should be equivalent to the secret used to encode it.

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

Given an HTTP Connection, parse the JWT api key stored in the header and retrieve the user correlating to the token from the DB.

Parameters:: connection¶ – An Litestar HTTPConnection instance.
Raises:: NotAuthorizedException – If token is invalid or user is not found.
Returns:: AuthenticationResult

class litestar.security.jwt.OAuth2Login#

Bases: object

OAuth2 Login DTO

__init__(access_token: str, token_type: str, refresh_token: str | None = None, expires_in: int | None = None) → None#

access_token: str#: Valid JWT access token

token_type: str#: Type of the OAuth token used

refresh_token: str | None = None#: Optional valid refresh token JWT

expires_in: int | None = None#: Expiration time of the token in seconds.

class litestar.security.jwt.OAuth2PasswordBearerAuth#

Bases: Generic[UserType], BaseJWTAuth[UserType]

OAUTH2 Schema for Password Bearer Authentication.

This class implements an OAUTH2 authentication flow entry point to the library, and it includes all the functionality of the JWTAuth class and adds support for passing JWT tokens HttpOnly cookies.

token_url is the only additional argument that is required, and it should point at your login route

__init__(token_secret: str, token_url: str, retrieve_user_handler: Callable[[Any, ASGIConnection], SyncOrAsyncUnion[Any | None]], 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, algorithm: str = 'HS256', auth_header: str = 'Authorization', default_token_expiration: timedelta = <factory>, openapi_security_scheme_name: str = 'BearerToken', oauth_scopes: dict[str, str] | None = None, key: str = 'token', path: str = '/', domain: str | None = None, secure: bool | None = None, samesite: Literal['lax', 'strict', 'none'] = 'lax', description: str = 'OAUTH2 password bearer authentication and authorization.', authentication_middleware_class: type[JWTCookieAuthenticationMiddleware] = <class 'litestar.security.jwt.middleware.JWTCookieAuthenticationMiddleware'>) → None#

token_secret: str#

Key with which to generate the token hash.

Notes

This value should be kept as a secret and the standard practice is to inject it into the environment.

token_url: str#: The URL for retrieving a new token.

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.

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.

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.

algorithm: str = 'HS256'#: Algorithm to use for JWT hashing.

auth_header: str = 'Authorization'#

Request header key from which to retrieve the token.

E.g. Authorization or ‘X-Api-Key’.

default_token_expiration: timedelta#: The default value for token expiration.

openapi_security_scheme_name: str = 'BearerToken'#: The value to use for the OpenAPI security scheme and security requirements.

oauth_scopes: dict[str, str] | None = None#: Oauth Scopes available for the token.

key: str = 'token'#: Key for the cookie.

path: str = '/'#

Path fragment that must exist in the request url for the cookie to be valid.

Defaults to /.

domain: str | None = None#: Domain for which the cookie is valid.

secure: bool | None = None#: Https is required for the cookie.

samesite: Literal['lax', 'strict', 'none'] = 'lax'#: Controls whether or not a cookie is sent with cross-site requests. Defaults to lax.

description: str = 'OAUTH2 password bearer authentication and authorization.'#: Description for the OpenAPI security scheme.

authentication_middleware_class#: alias of JWTCookieAuthenticationMiddleware

property middleware: DefineMiddleware#

Create JWTCookieAuthenticationMiddleware wrapped in: DefineMiddleware.

Returns:: An instance of DefineMiddleware.

property oauth_flow: OAuthFlow#

Create an OpenAPI OAuth2 flow for the password bearer authentication scheme.

Returns:: An OAuthFlow instance.

property openapi_components: Components#

Create OpenAPI documentation for the OAUTH2 Password bearer auth scheme.

Returns:: An Components instance.

login(identifier: str, *, response_body: Any = _EmptyEnum.EMPTY, response_media_type: str | MediaType = MediaType.JSON, response_status_code: int = 201, token_expiration: timedelta | None = None, token_issuer: str | None = None, token_audience: str | None = None, token_unique_jwt_id: str | None = None, token_extras: dict[str, Any] | None = None, send_token_as_response_body: bool = True) → Response[Any]#

Create a response with a JWT header.

Parameters:

identifier¶ – Unique identifier of the token subject. Usually this is a user ID or equivalent kind of value.
response_body¶ – An optional response body to send.
response_media_type¶ – An optional Content-Type. Defaults to application/json.
response_status_code¶ – An optional status code for the response. Defaults to 201.
token_expiration¶ – An optional timedelta for the token expiration.
token_issuer¶ – An optional value of the token iss field.
token_audience¶ – An optional value for the token aud field.
token_unique_jwt_id¶ – An optional value for the token jti field.
token_extras¶ – An optional dictionary to include in the token extras field.
send_token_as_response_body¶ – If True the response will be an oAuth2 token response dict. Note: if a response body is passed this setting will be ignored.

Returns:

A Response instance.

class litestar.security.jwt.Token#

Bases: object

JWT Token DTO.

exp: datetime#: Expiration - datetime for token expiration.

sub: str#: Subject - usually a unique identifier of the user or equivalent entity.

iat: datetime#: Issued at - should always be current now.

iss: str | None = None#: Issuer - optional unique identifier for the issuer.

aud: str | None = None#: Audience - intended audience.

__init__(exp: ~datetime.datetime, sub: str, iat: ~datetime.datetime = <factory>, iss: str | None = None, aud: str | None = None, jti: str | None = None, extras: dict[str, typing.Any] = <factory>) → None#

jti: str | None = None#: JWT ID - a unique identifier of the JWT between different issuers.

extras: dict[str, Any]#: Extra fields that were found on the JWT token.

classmethod decode(encoded_token: str, secret: str | dict[str, str], algorithm: str) → Self#

Decode a passed in token string and returns a Token instance.

Parameters:

encoded_token¶ – A base64 string containing an encoded JWT.
secret¶ – The secret with which the JWT is encoded. It may optionally be an individual JWK or JWS set dict
algorithm¶ – The algorithm used to encode the JWT.

Returns:

A decoded Token instance.

Raises:

NotAuthorizedException – If the token is invalid.

encode(secret: str, algorithm: str) → str#

Encode the token instance into a string.

Parameters:

secret¶ – The secret with which the JWT is encoded.
algorithm¶ – The algorithm used to encode the JWT.

Returns:

An encoded token string.

Raises:

ImproperlyConfiguredException – If encoding fails.