crossauth_fastapi package

Submodules

crossauth_fastapi.fastapioauthclient module

class crossauth_fastapi.fastapioauthclient.BffEndpoint(url, methods, match_sub_urls)[source]

Bases: NamedTuple

match_sub_urls: bool

Alias for field number 2

methods: List[Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH']]

Alias for field number 1

url: str

Alias for field number 0

class crossauth_fastapi.fastapioauthclient.FastApiOAuthClient(server: FastApiServerBase, auth_server_base_url: str, options: FastApiOAuthClientOptions = {}, have_session_server: bool = False)[source]

Bases: OAuthClient

The FastAPI implementation of the OAuth client.

Makes requests to an authorization server, using a configurable set of flows, which sends back errors or tokens,

You cannot construct this class directly. It must be created through a FastApiServer instance.

:attr:`FastApiOAuthClientOptions.token_response_type`

  • send_json the token response is sent as-is in the reply to the FastApi

    request. In addition to the token endpoint response fields, ok: true and id_payload with the decoded payload of the ID token are retruned.

  • save_in_session_and_load the response fields are saved in the data

    field of the session ID in key storage. In addition, expires_at is set to the number of seconds since Epoch that the access token expires at. After saving, page defined in authorized_page is displayed. A consequence is the query parameters passed to the redirect Uri are displayed in the address bar, as the response is to the redirect to the redirect Uri.

  • save_in_session_and_redirect` same as save_in_session_and_load except that a redirect is done to the authorized_url rather than displaying authorized_page template.

  • send_in_page the token endpoint response is not saved in the session but just sent as template arguments when rendering the template in authorized_page. The JSON response fields are sent verbatim, with the additional fild of id_payload which is the decoded payload from the ID token, if present.

  • custom the function in

    FastApiOAuthClientOptions.receiveTokenFn is called.

:attr:`FastApiOAuthClientOptions.errorResponseType`

  • json_error a JSON response is sent with fields

    status, error_message,

    error_messages and error_code_name.

  • page_error the template in :attr:FastApiOAuthClientOptions.error_page` is displayed with template parameters status, error_message, error_messages and error_code_name.

  • custom FastApiOAuthClientOptions.error_fn is called.

Backend-for-Frontend (BFF)

This class supports the backend-for-frontend (BFF) model. You create an endpoint for every resource server endpoint you want to be able to call, by setting them in FastApiOAuthClientOptions.bffEbdpoints. You set the FastApiOAuthClientOptions.token_response_type to save_in_session_and_load or save_in_session_and_redirect so that tokens are saved in the session. You also set bffBaseUrl to the base URL of the resource server. When you want to call a resource server endpoint, you call site_url + prefix + bff_endpoint_name + `url`. The client will pull the access token from the session, put it in the Authorization header and called bff_base_url + `url` using fetch, and return the response verbatim.

This pattern avoids you having to store the access token in the frontend.

Middleware

This class provides middleware that works with the BFF method.

If an ID token is saved in the session and it is valid, the following state attributes are set in the request object:

  • id_payload the payload from the ID token

  • user a crossauth_backend.User object created from the ID

    token

  • auth_type set to oidc

Endpoints provided by this class

In addition to the BFF endpoints above, this class provides the following endpoints. The ENDPOINT column values can be overridden in FastApiOAuthClientOptions. All POST endpoints also require csrf_token. The Flow endpoints are only enabled if the corresponding flow is set in FastApiOAuthClientOptions.valid_flows. Token endpoints are only enabled if the corresponding endpoint is set in FastApiOAuthClientOptions.token_endpoints.

METHOD | ENDPOINT |Description | GET/BODY PARAMS | VARIABLES PASSED/RESPONSE | FILE |
—— | ——————–| ———————————————————— | ————————————————— | ——————————————————— | ———————— |
GET | authzcode | Redirect URI for receiving authz code | See OAuth authorization code flow spec | See docs for`tokenResponseType` | |
GET | passwordflow | Displays page to request username/password for password flow | scope | user, scope | passwordFlowPage |
POST | passwordflow | Initiates the password flow | See OAuth password flow spec | See docs for`tokenResponseType` | |
| | Requests an OTP from the user for the Password MFA OTP flow | mfa_token, scope, otp | mfa_token, scope, error, errorMessage | mfaOtpPage |
| | Requests an OOB from the user for the Password MFA OOB flow | mfa_token, oob_code, scope, oob | mfa_token, oob_code, scope, error, errorMessage | mfaOobPage |
POST | passwordotp | Token request with the MFA OTP | See Password MFA flow spec | See docs for`tokenResponseType` | |
POST | passwordoob | Token request with the MFA OOB | See Password MFA flow spec | See docs for`tokenResponseType` | |
POST | authzcodeflow | Initiates the authorization code flow | See OAuth authorization code flow spec | See docs for`tokenResponseType` | |
POST | authzcodeflowpkce | Initiates the authorization code flow with PKCE | See OAuth authorization code flow with PKCE spec | See docs for`tokenResponseType` | |
POST | clientcredflow | Initiates the client credentials flow | See OAuth client credentials flow spec | See docs for`tokenResponseType` | |
POST | refreshtokenflow | Initiates the refresh token flow | See OAuth refresh token flow spec | See docs for`tokenResponseType` | |
POST | devicecodeflow | Initiates the device code flow | See DeviceCodeBodyType | See DeviceCodeFlowResponse | deviceCodeFlowPage |
POST | api/devicecodeflow | Initiates the device code flow | See DeviceCodeBodyType | See DeviceCodeFlowResponse | |
POST | devicecodepoll | Initiates the device code flow | See DeviceCodePollBodyType | Authorization complete: See docs for`tokenResponseType`. Other cases, OAuthTokenResponse | |
POST | api/devicecodepoll | Initiates the device code flow | See DeviceCodePollBodyType | OAuthTokenResponse | |
POST | access_token | For BFF mode, returns the saved access token | decode, default true | Access token payload | |
POST | refresh_token | For BFF mode, returns the saved refresh token | decode, default true | token containing the refresh token | |
POST | id_token ` | For BFF mode, returns the saved ID token | `decode, default true | ID token payload | |
POST | have_access_token | For BFF mode, returns whether an acccess token is saved | | ok | |
POST | have_refresh_token`| For BFF mode, returns whether a refresh token is saved | | `ok | |
POST | have_id_token | For BFF mode, returns whether an ID token is saved | | ok | |
POST | tokens | For BFF mode, returns all the saved tokens | decode, default true | *Token payloads | |
POST | deletetokens | Deletes all BFF tokens and displays a page | None | ok | deleteTokensPage |
POST | api/deletetokens | Delertes all tokens and returns JSON | None | ok | |
property api_delete_tokens_post_url
property authorized_page
property authorized_url
property delete_tokens_get_url
property delete_tokens_page
property delete_tokens_post_url
property device_code_flow_page
property error_page
property id_token_match_field
property jwt_tokens
property mfa_oob_page
property mfa_otp_page
property password_flow_page
property server
property session_data_name
async store_session_data(session_data: Dict[str, Any], request: Request, response: Response | None)[source]
property templates
property user_creation_type
property user_match_field
class crossauth_fastapi.fastapioauthclient.FastApiOAuthClientOptions[source]

Bases: OAuthClientOptions

Options for FastApiOAuthClient.

api_delete_tokens_post_url: str

Whether to add the api/deletetokens POST endpoint.

Default undefined - don’t create the endpoint

audience: str
auth_server_base_url: str
authorized_page: str

The template file for telling the user that authorization was successful.

authorized_url: str

If the FastApiOAuthClientOptions.token_response_type() is save_in_session_and_redirect, this is the relative URL that the usder will be redirected to after authorization is complete.

bff_base_url: str

Base URL for resource server endpoints called through the BFF mechanism. See FastApiOAuthClient class documentation for full description.

bff_endpoint_name: str

Prefix for BFF endpoints. Default “bff”. See:class:FastApiOAuthClient class documentation for full description.

bff_endpoints: List[BffEndpoint]

Array of resource server endppints to serve through the BFF (backend-for-frontend) mechanism. See FastApiOAuthClient class documentation for full description.

client_id: str
client_secret: str
clock_tolerance: int
code_challenge_method: Literal['plain', 'S256']
delete_tokens_get_url: str

Tthe deletetokens GET endpoint.

Default undefined - don’t create the endpoint

delete_tokens_page: str

The template file to show the result in the deletetokens endpoint.

Default deletetokens.jinja2

delete_tokens_post_url: str

Whether to add the deletetokens POST endpoint.

Default undefined - don’t create the endpoint

device_authorization_url: str
device_code_flow_page: str

The template file to tell users the url to go to to complete the device code flow.

Default devicecodeflow.jinja2

device_code_flow_url: str

The URL to to create the device code flow under. Default devicecodeflow.

device_code_poll_url: str

The URL to to for polling until the device code flow completes. Default devicecodepoll.

error_fn: FastApiErrorFn

The function to call when there is an OAuth error and FastApiOAuthClientOptions.error_response_type is custom. See FastApiErrorFn.

error_page: str

The template file for rendering error messages when FastApiOAuthClientOptions.error_response_type is error_page.

error_response_type: Literal['json_error', 'page_error', 'custom']

What do do on receiving an OAuth error. See lass documentation for full description.

id_token_match_field: str

Field in ID token to to match with idToken when userCreationType is set to merge or embed. Default sub.

jwt_key_type: str
jwt_public_key: str
jwt_public_key_file: str
jwt_secret_key: str
jwt_secret_key_file: str
jwt_tokens: List[Literal['access', 'id', 'refresh']]

These token types will be treated as JWT. Default all of them

key_storage: KeyStorage | None
mfa_oob_page: str

The template file for asking the user for an OOB in the password MFA flow.

mfa_otp_page: str

The template file for asking the user for an OTP in the password MFA flow.

oauth_authorize_redirect: str | None
oauth_post_type: Literal['json', 'form']
oauth_use_user_info_endpoint: bool
oidc_config: OpenIdConfiguration | Dict[str, Any] | None
password_flow_page: str

The template file for asking the user for username and password in the password flow,

Default passwordflow.junja2

password_flow_url: str

The URL to create the password flow under. Default passwordflow.

password_oob_url: str

The URL to create the otp endpoint for the password mfa flow under. This endpoint asks the user for his or her OOB. Default passwordflowoob.

password_otp_url: str

The URL to create the otp endpoint for the password mfa flow under. This endpoint asks the user for his or her OTP. Default passwordflowotp.

persist_access_token: bool
prefix: str

The prefix between the siteUrl and endpoints created by this class. See FastApiOAuthClientOptions.siteUrl.

receive_token_fn: Callable[[OAuthTokenResponse, Self, Request, Response | None], Response | None]

This function is called after successful authorization to pass the new tokens to. - oauthResponse the response from the OAuth token endpoint. - client the fastify OAuth client - request the FastApi request - response the FastApi response - returns the FastApi response

redirect_uri: str
session_data_name: str

When using the BFF (backend-for-frontend) pattern, tokens are saved in the data field of the session ID. They are saved in the JSON object with this field name. Default oauth.

siteUrl: str

The base URL for endpoints served by this class. THe only endpoint that is created is the redirect Uri, which is siteUrl + prefix + authzcode,

state_length: int
token_endpoints: List[Literal['access_token', 'refresh_token', 'id_token', 'have_access_token', 'have_refresh_token', 'have_id_token']]

Endpoints to provide to acces tokens through the BFF mechanism, See FastApiOAuthClient class documentation for full description.

token_response_type: Literal['send_json', 'save_in_session_and_load', 'save_in_session_and_redirect', 'send_in_page', 'custom']

What to do when receiving tokens. See FastApiOAuthClient class documentation for full description.

user_creation_fn: Callable[[Dict[str, Any], UserStorage | None, str, str], Awaitable[User | None]]

Supply this function if you set userCreationType to custom. - id_token the response from the OAuth token endpoint. - user_storage the fastify OAuth client - user_match_field the FastApi response - id_token_match_field the FastApi request Returns the user if it exists and is active, None otherwise.

user_creation_type: Literal['idToken', 'merge', 'embed', 'custom']

If using the BFF method, you can also create a user in the sesion when the token is received, just like session management (event.locals.user for Sveltekit, request.user) for Fastify.

Set this field to merge to do this by merging the ID token fields with the User fields. embed will put the ID token fields in idToken in the user. custom will call the user-defined function userCreationFn. th user will be set to undefined; If it is set to idToken (the default) then a user object is created from the token without first checking for a user in storage.

Matching is done in the fields given in user_match_field and id_token_match_field.

Currently only idToken and custom are supported as user storage has not yet been implemented.

user_match_field: str

Field in user table to to match with idToken when userCreationType is set to merge or embed. Default username.

valid_flows: List[str]

´crossauth_backend.OAuthFlows`. Default none

Type:

List of flows to create endpoints for. See

Type:

class

verifier_length: int
class crossauth_fastapi.fastapioauthclient.OAuthTokenResponseWithExpiry[source]

Bases: OAuthTokenResponse

access_token: str
binding_method: str
challenge_type: str
error: str
error_description: str
expires_at: int
expires_in: int
id_payload: Mapping[str, Any]
id_token: str
mfa_token: str
name: str
oob_channel: str
oob_code: str
refresh_token: str
scope: str
token_type: str
crossauth_fastapi.fastapioauthclient.decode_payload(token: str | None) → Dict[str, Any] | None[source]
async crossauth_fastapi.fastapioauthclient.embedUserCreateFn(id_token: Dict[str, Any], user_storage: UserStorage | None, user_match_field: str, id_token_match_field: str)[source]
async crossauth_fastapi.fastapioauthclient.idTokenUserCreateFn(id_token: Dict[str, Any], user_storage: UserStorage | None, user_match_field: str, id_token_match_field: str)[source]
async crossauth_fastapi.fastapioauthclient.json_error(server: FastApiServerBase, request: Request, response: Response, ce: CrossauthError) → Response[source]
crossauth_fastapi.fastapioauthclient.log_tokens(oauth_response: OAuthTokenResponse | OAuthDeviceResponse, client: FastApiOAuthClient)[source]
async crossauth_fastapi.fastapioauthclient.mergeUserCreateFn(id_token: Dict[str, Any], user_storage: UserStorage | None, user_match_field: str, id_token_match_field: str)[source]
async crossauth_fastapi.fastapioauthclient.page_error(server: FastApiServerBase, request: Request, response: Response, ce: CrossauthError) → Response[source]
async crossauth_fastapi.fastapioauthclient.save_in_session_and_load(oauth_response: OAuthTokenResponse | OAuthDeviceResponse, client: FastApiOAuthClient, request: Request, response: Response | None = None) → Response | None[source]
async crossauth_fastapi.fastapioauthclient.save_in_session_and_redirect(oauth_response: OAuthTokenResponse | OAuthDeviceResponse, client: FastApiOAuthClient, request: Request, response: Response | None = None) → Response | None[source]
async crossauth_fastapi.fastapioauthclient.send_in_page(oauth_response: OAuthTokenResponse | OAuthDeviceResponse, client: FastApiOAuthClient, request: Request, response: Response | None = None) → Response | None[source]
async crossauth_fastapi.fastapioauthclient.send_json(oauth_response: OAuthTokenResponse | OAuthDeviceResponse, client: FastApiOAuthClient, request: Request, response: Response | None = None) → Response | None[source]
crossauth_fastapi.fastapioauthclient.string_is_true(val: str) → bool[source]
async crossauth_fastapi.fastapioauthclient.update_session_data(oauth_response: OAuthTokenResponse, client: FastApiOAuthClient, request: Request, response: Response | None = None)[source]

crossauth_fastapi.fastapiresserver module

class crossauth_fastapi.fastapiresserver.Authorization[source]

Bases: TypedDict

authorized: bool
error: str
error_description: str
token_payload: Mapping[str, Any]
user: User
class crossauth_fastapi.fastapiresserver.FastApiOAuthResourceServer(app: FastAPI, token_consumers: List[OAuthTokenConsumer], options: FastApiOAuthResourceServerOptions = {})[source]

Bases: OAuthResourceServer

OAuth resource server.

You can subclass this, simply instantiate it, or create it through FastApiServer.

There are two way of using this class. If you don’t set protected_endpoints in the constructor, then in your protected endpoints, call FastApiOAuthResourceServer.authorized to check if the access token is valid and get any user credentials.

If you do set protected_endpoints in the constructor then a preHandler iscreated.

** Middleware ** The middleware hook will set the access_token_payload, user and scope fields on the FastApi request object based on the content of the access token in the Authorization header if it is valid. It will also set auth_type to oauth. If a user storage is provided, it will be used to look the user up. Otherwise a minimal user object is created. If it is not valid it will set the auth_error and auth_error_description. If the access token is invalid, or there is an error, a 401 or 500 response is sent before executing your endpoint code. As per OAuth requirements, if the response is a 401, the WWW-Authenticate header is set. If a scope is required this is included in that header.

authenticate_header(request: Request) → str[source]
async authorized(request: Request) → Dict[str, Any] | None[source]

If there is no bearer token, returns undefinerd. If there is a bearer token and it is a valid access token, returns the token payload. If there was an error, returns it in OAuth form.

Parameters:

request (Request) – the FastAPI Request object

Returns:

an object with the following fiekds - authorized : true or false - tokenPayload : the token payload if the token is valid - error : if the token is not valid - error_description : if the token is not valid - user set if sub is defined in the token, a userStorage has

been defined and it matches

If there was no valid token, None is returned

async token_from_header(request: Request) → Dict[str, Any] | None[source]
async token_from_session(request: Request) → Dict[str, Any] | None[source]
class crossauth_fastapi.fastapiresserver.FastApiOAuthResourceServerOptions[source]

Bases: OAuthResourceServerOptions

Options for FastApiOAuthResourceServer

error_body: Mapping[str, Any]

If you enabled protected_endpoints in FastApiOAuthResourceServer and the access token is invalid, a 401 reply will be sent before your endpoint is hit. This will be the body, Default {}.

protected_endpoints: Mapping[str, ProtectedEndpoint]

If you define this, matching resource server endpoints will return a status code of 401 Access Denied if the key is invalid or the given scopes are not present.

session_adapter: FastApiSessionAdapter

If token_locations contains session, must provide a session adapter

session_data_name: str

If token_locations contains session, tokens are keyed on this name.

Default oauth

token_locations: List[Literal['beader', 'session']]

Where access tokens may be found (in this order).

If this contains session, must also provide the session adapter

Default header

user_storage: UserStorage

If you set this and your access tokens have a user (sub claim), the user field in the request will be populated with a valid access token.

Not currently supported

class crossauth_fastapi.fastapiresserver.ProtectedEndpoint[source]

Bases: TypedDict

accept_session_authorization: bool
scope: List[str]
suburls: bool

crossauth_fastapi.fastapiserver module

class crossauth_fastapi.fastapiserver.FastApiOAuthClientParams[source]

Bases: TypedDict

Parameters that are used to create an OAuth client

auth_server_base_url: Required[str]
options: FastApiOAuthClientOptions
class crossauth_fastapi.fastapiserver.FastApiOAuthResServerParams[source]

Bases: TypedDict

Parameters that are used to create an OAuth resource server

options: FastApiOAuthResourceServerOptions
class crossauth_fastapi.fastapiserver.FastApiServer(params: FastApiServerParams, options: FastApiServerOptions = {})[source]

Bases: FastApiServerBase

This class provides a complete (but without HTML files) auth backend server for FastApi applications

If you do not pass a FastAPI app to this class, it will create one. Pages are rendered with Jinja2.

By default, all views are expected to be in a directory called templates relative to the directory the server is started in. This can be overwritten by setting the templates option.

Note that templates, and the Jinja2 pages are not used by the API endpoints (those starting in /api). These just return JSON.

Component Servers

This class contains a number of servers which don’t all have to be created, depending on what authentication you want to support. If instantiated, they can work together.

  • session_server Session cookie management server. Uses sesion ID

    and CSRF cookies. See FastApiSessionServer.

  • session_adapter If you want an OAuth client but not want to use

    Crossauth’s session server, you can provide your own with this. Won’t work with auth server.

  • oauth_auth_server OAuth authorization server. See

    FastApiAuthorizationServer

  • oauth_client OAuth client. See FastApiOAuthClient.

  • oauth_clients An array of OAuthClients if you want more than one.

    Use either this or oAuthClient but not both. See FastApiOAuthClient.

  • o_uth_res_server OAuth resource server. See

    FastApiOAuthResourceServer.

There is also an API key server which is not available as a variable as it has no functions other than the hook it registers. See FastApiApiKeyServer.

For a list of user-level URLs that can be enabled, and their input and output requirements, see FastApiSessionServer. FOr a list of admin endpoints that can be enabled, see FastApiAdminEndpoints.

property app
async create_anonymous_session(request: Request, response: Response, data: Dict[str, Any] | None = None) → str[source]

See FastApiSessionServer.create_anonymous_session().

Only available if there is a session server, not if you just providfe a session adapter. In this case, None is returned.

async delete_session_data(request: Request, name: str)[source]

See FastApiSessionServer.delete_session_data().

This is also available if you use a session adapter instead of a session server.

async error_if_csrf_invalid(request: Request, response: Response, error_fn: FastApiErrorFn | None) → MaybeErrorResponse[source]

Calls the passed error function passed if the CSRF token in the request is invalid.

Use this to require a CSRF token in your endpoints.

Parameters:

  • request (Request) – the FastAPI request

  • response (Response) – the FastAPI response object

  • error_fn (FastApiErrorFn|None) – the error function to call if the CSRF token is invalid

Returns:

if no error, returns an object with error set to false and

response set to the passed reply object. Otherwise returns the reply from calling error_fn.

property error_page

See FastApiSessionServer.get_session_cookie_value().

Only available if there is a session server, not if you just providfe a session adapter. In this case, None is returned.

async get_session_data(request: Request, name: str) → Dict[str, Any] | None[source]

See FastApiSessionServer.get_session_data().

This is also available if you use a session adapter instead of a session server.

property have_session_adapter: bool
property have_session_server: bool
property oauth_client
property oauth_clients
property oauth_resserver
property session_adapter
property session_server
property templates
async update_session_data(request: Request, name: str, value: Any)[source]

See FastApiSessionServer.update_session_data().

This is also available if you use a session adapter instead of a session server.

class crossauth_fastapi.fastapiserver.FastApiServerOptions[source]

Bases: FastApiSessionServerOptions, FastApiOAuthClientOptions, FastApiOAuthResourceServerOptions

Options for FastApiServer and it’s component subservers

add_to_session: Callable[[Request], Mapping[str, str | int | float | datetime | None]]
admin_allowed_factor1: List[str]
admin_create_client_page: str
admin_create_user_page: str
admin_prefix: str
admin_select_user_page: str
allowed_factor2: List[str]
api_delete_tokens_post_url: str
app: FastAPI

You can pass your own FastAPI instance or omit this, in which case Crossauth will create one

audience: str
auth_server_base_url: str
authorized_page: str
authorized_url: str
bff_base_url: str
bff_endpoint_name: str
bff_endpoints: List[BffEndpoint]
change_factor2_page: str
change_password_page: str
client_id: str
client_secret: str
client_serach_dn: Callable[[str, OAuthClientStorage, str | int | NullType], List[OAuthClient]]
clock_tolerance: int
code_challenge_method: Literal['plain', 'S256']
configure_factor2_page: str
create_user_fn: Callable[[Request, Dict[str, Any], List[str], List[str]], UserInputFields]
delete_client_page: str
delete_tokens_get_url: str
delete_tokens_page: str
delete_tokens_post_url: str
delete_user_page: str
device_authorization_url: str
device_code_flow_page: str
device_code_flow_url: str
device_code_poll_url: str
edit_user_scope: str
email_from: NotRequired[str]
email_token_storage: KeyStorage
email_verification_html_body: NotRequired[str]
email_verification_subject: NotRequired[str]
email_verification_text_body: NotRequired[str]
email_verified_page: str
enable_admin_endpoints: bool
enable_email_verification: bool
enable_oauth_client_management: bool
enable_password_reset: bool
endpoints: List[str]
error_body: Mapping[str, Any]
error_fn: FastApiErrorFn
error_page: str
error_response_type: Literal['json_error', 'page_error', 'custom']
factor2_page: str
factor2_protected_api_endpoints: List[str]
factor2_protected_page_endpoints: List[str]
id_token_match_field: str
is_admin_fn: Callable[[User], bool]

Function to return whether given user is an admin. If not set, the admin field of the user is used, which is assumed to be bool

jwt_key_type: str
jwt_public_key: str
jwt_public_key_file: str
jwt_secret_key: str
jwt_secret_key_file: str
jwt_tokens: List[Literal['access', 'id', 'refresh']]
key_storage: KeyStorage | None
login_page: str
login_redirect: str
logout_redirect: str
mfa_oob_page: str
mfa_otp_page: str
oauth_authorize_redirect: str | None
oauth_post_type: Literal['json', 'form']
oauth_use_user_info_endpoint: bool
oidc_config: OpenIdConfiguration | Dict[str, Any] | None
password_flow_page: str
password_flow_url: str
password_oob_url: str
password_otp_url: str
password_reset_expires: NotRequired[int]
password_reset_html_body: NotRequired[str]
password_reset_subject: NotRequired[str]
password_reset_text_body: NotRequired[str]
persist_access_token: bool
prefix: str
protected_endpoints: Mapping[str, ProtectedEndpoint]
receive_token_fn: Callable[[OAuthTokenResponse, Self, Request, Response | None], Response | None]
redirect_uri: str
render: NotRequired[Callable[[str, Dict[str, Any]], str]]
request_reset_password_page: str
reset_password_page: str
secret: str
session_adapter: FastApiSessionAdapter
session_data_name: str
signup_page: str
siteUrl: str
site_url: str
smtp_host: NotRequired[str]
smtp_password: NotRequired[str]
smtp_port: NotRequired[int]
smtp_use_tls: NotRequired[bool]
smtp_username: NotRequired[str]
state_length: int
template_dir: str

If this is passed, it is registered as a Jinja2 view folder

token_endpoints: List[Literal['access_token', 'refresh_token', 'id_token', 'have_access_token', 'have_refresh_token', 'have_id_token']]
token_locations: List[Literal['beader', 'session']]
token_response_type: Literal['send_json', 'save_in_session_and_load', 'save_in_session_and_redirect', 'send_in_page', 'custom']
update_user_fn: Callable[[User, Request, Dict[str, Any], List[str]], User]
update_user_page: str
user_allowed_factor1: List[str]
user_creation_fn: Callable[[Dict[str, Any], UserStorage | None, str, str], Awaitable[User | None]]
user_creation_type: Literal['idToken', 'merge', 'embed', 'custom']
user_match_field: str
user_search_fn: Callable[[str, UserStorage], List[User]]
user_storage: UserStorage
valid_flows: List[str]
validate_session: Callable[[Key, User | None, Request], None]
validate_user_fn: Callable[[UserInputFields], List[str]]
verifier_length: int
verify_email_expires: NotRequired[int]
views: NotRequired[str]
class crossauth_fastapi.fastapiserver.FastApiServerParams[source]

Bases: TypedDict

Configuration for the FastAPI server - which services to instantiate

oauth_client: FastApiOAuthClientParams

Paramneters to create an OAuth client

oauth_clients: List[FastApiOAuthClientParams]

Paramneters to create an OAuth client

oauth_resserver: FastApiOAuthResServerParams

Paramneters to create an OAuth resource server

options: FastApiServerOptions

Global options which will be passed to all of the above (and be overridden by their own options if present)

session: FastApiSessionServerParams

Parameters to create a session server

session_adapter: FastApiSessionAdapter

If you are using a different session, implement FastApiSessionAdapter to use it, and pass it here

class crossauth_fastapi.fastapiserver.FastApiSessionServerParams[source]

Bases: TypedDict

Parameters that are used to create a session server

key_storage: Required[KeyStorage]
options: FastApiSessionServerOptions

crossauth_fastapi.fastapiserverbase module

class crossauth_fastapi.fastapiserverbase.FastApiServerBase[source]

Bases: ABC

This is an abstract base class for the FastApiServer which only exists to avoid cyclic references. You should not have to use it

abstract property app: FastAPI
abstractmethod async create_anonymous_session(request: Request, response: Response, data: Dict[str, Any] | None = None) → str[source]
abstractmethod async delete_session_data(request: Request, name: str)[source]
abstractmethod async error_if_csrf_invalid(request: Request, response: Response, error_fn: FastApiErrorFn | None) → MaybeErrorResponse[source]
abstract property error_page: str
abstractmethod async get_session_data(request: Request, name: str) → Dict[str, Any] | None[source]
abstract property have_session_adapter: bool
abstract property have_session_server: bool
is_admin() → bool

The function to determine if a user has admin rights can be set externally. This is the default function if none other is set. It returns true iff the admin field in the passed user is set to true.

Parameters:

user (crossauth_backend.User) – the user to test

:return true or false

static send_page_error(templates: Jinja2Templates, request: Request, reply: Response, status: int, error_page: str | None = None, error: str | None = None, e: Any | None = None) → Response[source]

Sends a reply by rendering the errorPage if present, or a standard error page if it isn’t.

The renderer configured for the reply object is called (Nunjucks by default) with the following data parameters: - errorCode See ErrorCode. - errorCodeName the text version of errorCode. - msg the error message - httpStatus the HTTP status code.

Parameters:

  • reply – the Fastify reply object

  • status – the HTTP status code to return

  • error_page – the error page to render.

  • error – an error message string. Ignored if e is defined.

  • e – optionally, an exception. This will be logged and the message will be sent to the error page.

Returns:

the reply from rendering the error page.

abstract property templates: Jinja2Templates
abstractmethod async update_session_data(request: Request, name: str, value: Any)[source]
class crossauth_fastapi.fastapiserverbase.MaybeErrorResponse(response, error)[source]

Bases: NamedTuple

error: bool

Alias for field number 1

response: Response

Alias for field number 0

crossauth_fastapi.fastapiserverbase.default_is_admin_fn(user: User) → bool[source]

The function to determine if a user has admin rights can be set externally. This is the default function if none other is set. It returns true iff the admin field in the passed user is set to true.

Parameters:

user (crossauth_backend.User) – the user to test

:return true or false

crossauth_fastapi.fastapisession module

class crossauth_fastapi.fastapisession.FastApiSessionServer(app: FastAPI, key_storage: KeyStorage, authenticators: Mapping[str, Authenticator], options: FastApiSessionServerOptions = {})[source]

Bases: FastApiSessionServerBase

This class adds user endpoints to the FastAPI session server.

Important Note This class is imcomplete. It supports only enough functionality to provide CSRF cookies and anonymous sessions (where there is no user). The rest of the functionality will come later.

You shouldn’t have create create this directly - it is created by FastApiServer.

Using your own FastAPI app

If you are serving other endpoints, or you want to use something other than Nunjucks, you can create and pass in your own FastAPI app.

Middleware

This class registers one middleware function to fill in the following fields in Request.state:

  • user a crossauch_backend.User object which currently is always None

  • auth_type: set to cookie or None (currently always None)

  • csrf_token: a CSRF token that can be used in POST requests

  • session_id a session ID if one is created with create_anonymous_session()

add_api_cancel_factor2_endpoints()[source]
add_api_getcsrftoken_endpoints()[source]
add_api_login_endpoints()[source]
add_api_login_factor2_endpoints()[source]
add_api_logout_endpoints()[source]
add_api_signup_endpoints()[source]
add_api_user_for_session_key_endpoints()[source]
add_endpoints()[source]
add_factor2_endpoints()[source]
add_login_endpoints()[source]
add_login_factor2_endpoints()[source]
add_logout_endpoints()[source]
add_signup_endpoints()[source]
property admin_allowed_factor1
property allowed_factor2
allowed_factor2_details() → List[AuthenticatorDetails][source]

For each of the authenticators passed to the constructor, returns some details about it @returns a list of AuthenticatorDetails objects.

property app
property authenticators
can_edit_user(request: Request) → bool[source]

A user can edit his or her account if they are logged in with session management, or are logged in with some other means and e`ditUserScope` has been set and is included in the user’s scopes. @param request the Fastify request @returns true or false

async cancel_factor2(request: Request, resp: Response, success_fn: Callable[[Response], Response]) → Response[source]
async create_anonymous_session(request: Request, response: Response, data: Dict[str, Any] | None = None) → str[source]

Creates and persists an anonymous session.

An anonymous session is one which is not associated with a user. This is needed when you need to save session state, despite a user not being logged in.

:param Request request the FastAPI Request object :param Response request the FastAPI Response object :param Dict[str, Any] data optionally, data to store in the session.

The top level keys should not conflict with anything that FastAPI itself stores

csrf_protection_enabled() → bool[source]

See :meth:`FastApiSessionAdapter.csrf_protection_enabled

async csrf_token(request: Request, form: JsonOrFormData, headers: Dict[str, str] | None = None, add_cookies: Dict[str, Tuple[str, CookieOptions]] | None = None, delete_cookies: Set[str] | None = None, response: Response | None = None) → str | None[source]

Validates the CSRF token in the header or csrfToken form or JSON field and cookie value.

If it is then request.state.csrf_token is set. If not it is cleared.

Does not raise an exception

async delete_session_data(request: Request, name: str)[source]

See :meth:`FastApiSessionAdapter.delete_session_data

property enable_csrf_protection
property enable_email_verification: bool
property error_page
error_status(e: Exception) → int[source]

Helper function that returns the http_status field of an Exception, first casting it to a crossauth_backend.CrossauthError (if it wasn’t already a CrossauthError, the status will be 500).

Returns the CSRF cookie value or None if there isn’t one

Parameters:

request (Request) – the FastAPI Request

get_csrf_token(request: Request) → str | None[source]

See :meth:`FastApiSessionAdapter.get_csrf_token

get_hash_of_session_id(request: Request) → str[source]

Returns the session cookie value or None if there isn’t one

Parameters:

request (Request) – the FastAPI Request

async get_session_data(request: Request, name: str) → Dict[str, Any] | None[source]

See :meth:`FastApiSessionAdapter.get_session_data

get_user(request: Request) → User | None[source]

See :meth:`FastApiSessionAdapter.get_user

handle_error(e: Exception, request: Request, form: JsonOrFormData | None, error_fn: Callable[[Dict[str, Any], CrossauthError], Response], password_invalid_ok: bool = False) → Response[source]

Calls your defined error_fn, first sanitising by changing UserNotExist and UsernameOrPasswordInvalid messages to UsernameOrPasswordInvalid. Also logs the error

static is_admin(user: User)[source]
is_session_user(request: Request) → bool[source]

Returns whether there is a user logged in with a cookie-based session

property login_redirect
async login_with_user(user: User, bypass_2fa: bool, request: Request, resp: Response, success_fn: Callable[[Response, User], Response]) → Response[source]

This is called after the user has been validated to log the user in

send_json_error(request: Request, response: Response, status: int, error: str | None = None, e: Exception | None = None) → Response[source]

Returns an error as a FastAPI JSONResponse object, also logging it.

send_page_error(request: Request, response: Response, status: int, error: str | None = None, e: Exception | None = None) → Response[source]
property session_manager
property templates
async update_many_session_data(request: Request, data_array: List[KeyDataEntry])[source]

See :meth:`FastApiSessionAdapter.update_many_session_data

async update_session_data(request: Request, name: str, value: Any)[source]

See :meth:`FastApiSessionAdapter.update_session_data

static user(request: Request) → User | None[source]
property user_allowed_factor1
property user_storage
static username(request: Request) → str | None[source]
validate_csrf_token(request: Request) → str | None[source]

Validates the CSRF token in the Request.state and cookie value.

Parameters:

request (Request) – the FastAPI Request

Returns:

the CSRF cookie value if there is one

Raises:

crossauth_backend.CrossauthError with crossauth_backend.ErrorCode of `InvalidCsrf

async crossauth_fastapi.fastapisession.create_body(request: Request) → MutableMapping[str, Any][source]
crossauth_fastapi.fastapisession.default_create_user(request: Request, body: Dict[str, Any], userEditableFields: List[str], allowableFactor1: List[str]) → UserInputFields[source]

Default function for creating users. Can be overridden.

Takes any field beginning with user_ and that is also in userEditableFields (without the user_ prefix).

Parameters:

  • request – the fastify request

  • userEditableFields – the fields a user may edit

  • allowableFactor1 – allowable factor1 values

Returns:

the new user

crossauth_fastapi.fastapisession.default_update_user(user: User, request: Request, body: Dict[str, Any], userEditableFields: List[str]) → User[source]

Default function for creating users. Can be overridden.

Takes any field beginning with user_ and that is also in userEditableFields (without the user_ prefix).

Parameters:

  • user – the user to update

  • request – the fastify request

  • userEditableFields – the fields a user may edit

Returns:

the new user

crossauth_fastapi.fastapisession.default_user_validator(user: UserInputFields) → List[str][source]

Default User validator. Doesn’t validate password

Username must be at least two characters. :param password The password to validate :return an array of errors. If there were no errors, returns an empty array

async crossauth_fastapi.fastapisession.get_body(request: Request) → bytes[source]
async crossauth_fastapi.fastapisession.set_body(request: Request, body: bytes)[source]
crossauth_fastapi.fastapisession.toFastApiCookieOptions(options: CookieOptions)[source]

crossauth_fastapi.fastapisessionadapter module

class crossauth_fastapi.fastapisessionadapter.FastApiSessionAdapter[source]

Bases: ABC

This class provides a minimal API that Crossauth needs from a cookie-based session management.

Its own FastApiSessionServer implements this.

If you want to your your favourite frameworks’ own session management, implement this adapter to use it and pass it to FastApiServer as session_adapter instead of session_manager.

abstractmethod csrf_protection_enabled() → bool[source]

Returns whether CSRF protection has been enabled,. Some backends provide this automatically in which case you can return False in your adapter. If your backend does not do this automatically, you should always implement it and return True

abstractmethod async delete_session_data(request: Request, name: str) → None[source]

Deletes a field from the session data in the key storage record,

The data field is assumed to be JSON. Just the field with the given name is updated and the rest is unchanged. :param request: the FastAPI request :param name: the field within data to update

abstractmethod get_csrf_token(request: Request) → str | None[source]

Return the CSRF token if one has been set or None

abstractmethod async get_session_data(request: Request, name: str) → Dict[str, Any] | None[source]

Return data stored in the session with key name or None if not present :param request: the FastAPI request :param name: name of the data to fetch

Returns:

a dictionary of the data, or None

abstractmethod get_user(request: Request) → User | None[source]

Return the logged in user if there is one or None

abstractmethod async update_many_session_data(request: Request, data_array: List[KeyDataEntry])[source]

Same as update_data but updates many within same transaction

The data field is assumed to be JSON. Just the field with the given name is updated and the rest is unchanged. :param request: the FastAPI request :param data_array: data to update

abstractmethod async update_session_data(request: Request, name: str, value: Any) → None[source]

Updates a field in the session data in the key storage record,

The data field is assumed to be JSON. Just the field with the given name is updated and the rest is unchanged. :param request: the FastAPI request :param name: the field within data to update :param value: the value to set it to

Module contents

class crossauth_fastapi.BffEndpoint(url, methods, match_sub_urls)[source]

Bases: NamedTuple

match_sub_urls: bool

Alias for field number 2

methods: List[Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH']]

Alias for field number 1

url: str

Alias for field number 0

class crossauth_fastapi.FastApiOAuthClient(server: FastApiServerBase, auth_server_base_url: str, options: FastApiOAuthClientOptions = {}, have_session_server: bool = False)[source]

Bases: OAuthClient

The FastAPI implementation of the OAuth client.

Makes requests to an authorization server, using a configurable set of flows, which sends back errors or tokens,

You cannot construct this class directly. It must be created through a FastApiServer instance.

:attr:`FastApiOAuthClientOptions.token_response_type`

  • send_json the token response is sent as-is in the reply to the FastApi

    request. In addition to the token endpoint response fields, ok: true and id_payload with the decoded payload of the ID token are retruned.

  • save_in_session_and_load the response fields are saved in the data

    field of the session ID in key storage. In addition, expires_at is set to the number of seconds since Epoch that the access token expires at. After saving, page defined in authorized_page is displayed. A consequence is the query parameters passed to the redirect Uri are displayed in the address bar, as the response is to the redirect to the redirect Uri.

  • save_in_session_and_redirect` same as save_in_session_and_load except that a redirect is done to the authorized_url rather than displaying authorized_page template.

  • send_in_page the token endpoint response is not saved in the session but just sent as template arguments when rendering the template in authorized_page. The JSON response fields are sent verbatim, with the additional fild of id_payload which is the decoded payload from the ID token, if present.

  • custom the function in

    FastApiOAuthClientOptions.receiveTokenFn is called.

:attr:`FastApiOAuthClientOptions.errorResponseType`

  • json_error a JSON response is sent with fields

    status, error_message,

    error_messages and error_code_name.

  • page_error the template in :attr:FastApiOAuthClientOptions.error_page` is displayed with template parameters status, error_message, error_messages and error_code_name.

  • custom FastApiOAuthClientOptions.error_fn is called.

Backend-for-Frontend (BFF)

This class supports the backend-for-frontend (BFF) model. You create an endpoint for every resource server endpoint you want to be able to call, by setting them in FastApiOAuthClientOptions.bffEbdpoints. You set the FastApiOAuthClientOptions.token_response_type to save_in_session_and_load or save_in_session_and_redirect so that tokens are saved in the session. You also set bffBaseUrl to the base URL of the resource server. When you want to call a resource server endpoint, you call site_url + prefix + bff_endpoint_name + `url`. The client will pull the access token from the session, put it in the Authorization header and called bff_base_url + `url` using fetch, and return the response verbatim.

This pattern avoids you having to store the access token in the frontend.

Middleware

This class provides middleware that works with the BFF method.

If an ID token is saved in the session and it is valid, the following state attributes are set in the request object:

  • id_payload the payload from the ID token

  • user a crossauth_backend.User object created from the ID

    token

  • auth_type set to oidc

Endpoints provided by this class

In addition to the BFF endpoints above, this class provides the following endpoints. The ENDPOINT column values can be overridden in FastApiOAuthClientOptions. All POST endpoints also require csrf_token. The Flow endpoints are only enabled if the corresponding flow is set in FastApiOAuthClientOptions.valid_flows. Token endpoints are only enabled if the corresponding endpoint is set in FastApiOAuthClientOptions.token_endpoints.

METHOD | ENDPOINT |Description | GET/BODY PARAMS | VARIABLES PASSED/RESPONSE | FILE |
—— | ——————–| ———————————————————— | ————————————————— | ——————————————————— | ———————— |
GET | authzcode | Redirect URI for receiving authz code | See OAuth authorization code flow spec | See docs for`tokenResponseType` | |
GET | passwordflow | Displays page to request username/password for password flow | scope | user, scope | passwordFlowPage |
POST | passwordflow | Initiates the password flow | See OAuth password flow spec | See docs for`tokenResponseType` | |
| | Requests an OTP from the user for the Password MFA OTP flow | mfa_token, scope, otp | mfa_token, scope, error, errorMessage | mfaOtpPage |
| | Requests an OOB from the user for the Password MFA OOB flow | mfa_token, oob_code, scope, oob | mfa_token, oob_code, scope, error, errorMessage | mfaOobPage |
POST | passwordotp | Token request with the MFA OTP | See Password MFA flow spec | See docs for`tokenResponseType` | |
POST | passwordoob | Token request with the MFA OOB | See Password MFA flow spec | See docs for`tokenResponseType` | |
POST | authzcodeflow | Initiates the authorization code flow | See OAuth authorization code flow spec | See docs for`tokenResponseType` | |
POST | authzcodeflowpkce | Initiates the authorization code flow with PKCE | See OAuth authorization code flow with PKCE spec | See docs for`tokenResponseType` | |
POST | clientcredflow | Initiates the client credentials flow | See OAuth client credentials flow spec | See docs for`tokenResponseType` | |
POST | refreshtokenflow | Initiates the refresh token flow | See OAuth refresh token flow spec | See docs for`tokenResponseType` | |
POST | devicecodeflow | Initiates the device code flow | See DeviceCodeBodyType | See DeviceCodeFlowResponse | deviceCodeFlowPage |
POST | api/devicecodeflow | Initiates the device code flow | See DeviceCodeBodyType | See DeviceCodeFlowResponse | |
POST | devicecodepoll | Initiates the device code flow | See DeviceCodePollBodyType | Authorization complete: See docs for`tokenResponseType`. Other cases, OAuthTokenResponse | |
POST | api/devicecodepoll | Initiates the device code flow | See DeviceCodePollBodyType | OAuthTokenResponse | |
POST | access_token | For BFF mode, returns the saved access token | decode, default true | Access token payload | |
POST | refresh_token | For BFF mode, returns the saved refresh token | decode, default true | token containing the refresh token | |
POST | id_token ` | For BFF mode, returns the saved ID token | `decode, default true | ID token payload | |
POST | have_access_token | For BFF mode, returns whether an acccess token is saved | | ok | |
POST | have_refresh_token`| For BFF mode, returns whether a refresh token is saved | | `ok | |
POST | have_id_token | For BFF mode, returns whether an ID token is saved | | ok | |
POST | tokens | For BFF mode, returns all the saved tokens | decode, default true | *Token payloads | |
POST | deletetokens | Deletes all BFF tokens and displays a page | None | ok | deleteTokensPage |
POST | api/deletetokens | Delertes all tokens and returns JSON | None | ok | |
property api_delete_tokens_post_url
property authorized_page
property authorized_url
property delete_tokens_get_url
property delete_tokens_page
property delete_tokens_post_url
property device_code_flow_page
property error_page
property id_token_match_field
property jwt_tokens
property mfa_oob_page
property mfa_otp_page
property password_flow_page
property server
property session_data_name
async store_session_data(session_data: Dict[str, Any], request: Request, response: Response | None)[source]
property templates
property user_creation_type
property user_match_field
class crossauth_fastapi.FastApiOAuthClientOptions[source]

Bases: OAuthClientOptions

Options for FastApiOAuthClient.

api_delete_tokens_post_url: str

Whether to add the api/deletetokens POST endpoint.

Default undefined - don’t create the endpoint

audience: str
auth_server_base_url: str
authorized_page: str

The template file for telling the user that authorization was successful.

authorized_url: str

If the FastApiOAuthClientOptions.token_response_type() is save_in_session_and_redirect, this is the relative URL that the usder will be redirected to after authorization is complete.

bff_base_url: str

Base URL for resource server endpoints called through the BFF mechanism. See FastApiOAuthClient class documentation for full description.

bff_endpoint_name: str

Prefix for BFF endpoints. Default “bff”. See:class:FastApiOAuthClient class documentation for full description.

bff_endpoints: List[BffEndpoint]

Array of resource server endppints to serve through the BFF (backend-for-frontend) mechanism. See FastApiOAuthClient class documentation for full description.

client_id: str
client_secret: str
clock_tolerance: int
code_challenge_method: Literal['plain', 'S256']
delete_tokens_get_url: str

Tthe deletetokens GET endpoint.

Default undefined - don’t create the endpoint

delete_tokens_page: str

The template file to show the result in the deletetokens endpoint.

Default deletetokens.jinja2

delete_tokens_post_url: str

Whether to add the deletetokens POST endpoint.

Default undefined - don’t create the endpoint

device_authorization_url: str
device_code_flow_page: str

The template file to tell users the url to go to to complete the device code flow.

Default devicecodeflow.jinja2

device_code_flow_url: str

The URL to to create the device code flow under. Default devicecodeflow.

device_code_poll_url: str

The URL to to for polling until the device code flow completes. Default devicecodepoll.

error_fn: FastApiErrorFn

The function to call when there is an OAuth error and FastApiOAuthClientOptions.error_response_type is custom. See FastApiErrorFn.

error_page: str

The template file for rendering error messages when FastApiOAuthClientOptions.error_response_type is error_page.

error_response_type: Literal['json_error', 'page_error', 'custom']

What do do on receiving an OAuth error. See lass documentation for full description.

id_token_match_field: str

Field in ID token to to match with idToken when userCreationType is set to merge or embed. Default sub.

jwt_key_type: str
jwt_public_key: str
jwt_public_key_file: str
jwt_secret_key: str
jwt_secret_key_file: str
jwt_tokens: List[Literal['access', 'id', 'refresh']]

These token types will be treated as JWT. Default all of them

key_storage: KeyStorage | None
mfa_oob_page: str

The template file for asking the user for an OOB in the password MFA flow.

mfa_otp_page: str

The template file for asking the user for an OTP in the password MFA flow.

oauth_authorize_redirect: str | None
oauth_post_type: Literal['json', 'form']
oauth_use_user_info_endpoint: bool
oidc_config: OpenIdConfiguration | Dict[str, Any] | None
password_flow_page: str

The template file for asking the user for username and password in the password flow,

Default passwordflow.junja2

password_flow_url: str

The URL to create the password flow under. Default passwordflow.

password_oob_url: str

The URL to create the otp endpoint for the password mfa flow under. This endpoint asks the user for his or her OOB. Default passwordflowoob.

password_otp_url: str

The URL to create the otp endpoint for the password mfa flow under. This endpoint asks the user for his or her OTP. Default passwordflowotp.

persist_access_token: bool
prefix: str

The prefix between the siteUrl and endpoints created by this class. See FastApiOAuthClientOptions.siteUrl.

receive_token_fn: Callable[[OAuthTokenResponse, Self, Request, Response | None], Response | None]

This function is called after successful authorization to pass the new tokens to. - oauthResponse the response from the OAuth token endpoint. - client the fastify OAuth client - request the FastApi request - response the FastApi response - returns the FastApi response

redirect_uri: str
session_data_name: str

When using the BFF (backend-for-frontend) pattern, tokens are saved in the data field of the session ID. They are saved in the JSON object with this field name. Default oauth.

siteUrl: str

The base URL for endpoints served by this class. THe only endpoint that is created is the redirect Uri, which is siteUrl + prefix + authzcode,

state_length: int
token_endpoints: List[Literal['access_token', 'refresh_token', 'id_token', 'have_access_token', 'have_refresh_token', 'have_id_token']]

Endpoints to provide to acces tokens through the BFF mechanism, See FastApiOAuthClient class documentation for full description.

token_response_type: Literal['send_json', 'save_in_session_and_load', 'save_in_session_and_redirect', 'send_in_page', 'custom']

What to do when receiving tokens. See FastApiOAuthClient class documentation for full description.

user_creation_fn: Callable[[Dict[str, Any], UserStorage | None, str, str], Awaitable[User | None]]

Supply this function if you set userCreationType to custom. - id_token the response from the OAuth token endpoint. - user_storage the fastify OAuth client - user_match_field the FastApi response - id_token_match_field the FastApi request Returns the user if it exists and is active, None otherwise.

user_creation_type: Literal['idToken', 'merge', 'embed', 'custom']

If using the BFF method, you can also create a user in the sesion when the token is received, just like session management (event.locals.user for Sveltekit, request.user) for Fastify.

Set this field to merge to do this by merging the ID token fields with the User fields. embed will put the ID token fields in idToken in the user. custom will call the user-defined function userCreationFn. th user will be set to undefined; If it is set to idToken (the default) then a user object is created from the token without first checking for a user in storage.

Matching is done in the fields given in user_match_field and id_token_match_field.

Currently only idToken and custom are supported as user storage has not yet been implemented.

user_match_field: str

Field in user table to to match with idToken when userCreationType is set to merge or embed. Default username.

valid_flows: List[str]

´crossauth_backend.OAuthFlows`. Default none

Type:

List of flows to create endpoints for. See

Type:

class

verifier_length: int
class crossauth_fastapi.FastApiOAuthClientParams[source]

Bases: TypedDict

Parameters that are used to create an OAuth client

auth_server_base_url: Required[str]
options: FastApiOAuthClientOptions
class crossauth_fastapi.FastApiOAuthResServerParams[source]

Bases: TypedDict

Parameters that are used to create an OAuth resource server

options: FastApiOAuthResourceServerOptions
class crossauth_fastapi.FastApiOAuthResourceServer(app: FastAPI, token_consumers: List[OAuthTokenConsumer], options: FastApiOAuthResourceServerOptions = {})[source]

Bases: OAuthResourceServer

OAuth resource server.

You can subclass this, simply instantiate it, or create it through FastApiServer.

There are two way of using this class. If you don’t set protected_endpoints in the constructor, then in your protected endpoints, call FastApiOAuthResourceServer.authorized to check if the access token is valid and get any user credentials.

If you do set protected_endpoints in the constructor then a preHandler iscreated.

** Middleware ** The middleware hook will set the access_token_payload, user and scope fields on the FastApi request object based on the content of the access token in the Authorization header if it is valid. It will also set auth_type to oauth. If a user storage is provided, it will be used to look the user up. Otherwise a minimal user object is created. If it is not valid it will set the auth_error and auth_error_description. If the access token is invalid, or there is an error, a 401 or 500 response is sent before executing your endpoint code. As per OAuth requirements, if the response is a 401, the WWW-Authenticate header is set. If a scope is required this is included in that header.

authenticate_header(request: Request) → str[source]
async authorized(request: Request) → Dict[str, Any] | None[source]

If there is no bearer token, returns undefinerd. If there is a bearer token and it is a valid access token, returns the token payload. If there was an error, returns it in OAuth form.

Parameters:

request (Request) – the FastAPI Request object

Returns:

an object with the following fiekds - authorized : true or false - tokenPayload : the token payload if the token is valid - error : if the token is not valid - error_description : if the token is not valid - user set if sub is defined in the token, a userStorage has

been defined and it matches

If there was no valid token, None is returned

async token_from_header(request: Request) → Dict[str, Any] | None[source]
async token_from_session(request: Request) → Dict[str, Any] | None[source]
class crossauth_fastapi.FastApiOAuthResourceServerOptions[source]

Bases: OAuthResourceServerOptions

Options for FastApiOAuthResourceServer

error_body: Mapping[str, Any]

If you enabled protected_endpoints in FastApiOAuthResourceServer and the access token is invalid, a 401 reply will be sent before your endpoint is hit. This will be the body, Default {}.

protected_endpoints: Mapping[str, ProtectedEndpoint]

If you define this, matching resource server endpoints will return a status code of 401 Access Denied if the key is invalid or the given scopes are not present.

session_adapter: FastApiSessionAdapter

If token_locations contains session, must provide a session adapter

session_data_name: str

If token_locations contains session, tokens are keyed on this name.

Default oauth

token_locations: List[Literal['beader', 'session']]

Where access tokens may be found (in this order).

If this contains session, must also provide the session adapter

Default header

user_storage: UserStorage

If you set this and your access tokens have a user (sub claim), the user field in the request will be populated with a valid access token.

Not currently supported

class crossauth_fastapi.FastApiServer(params: FastApiServerParams, options: FastApiServerOptions = {})[source]

Bases: FastApiServerBase

This class provides a complete (but without HTML files) auth backend server for FastApi applications

If you do not pass a FastAPI app to this class, it will create one. Pages are rendered with Jinja2.

By default, all views are expected to be in a directory called templates relative to the directory the server is started in. This can be overwritten by setting the templates option.

Note that templates, and the Jinja2 pages are not used by the API endpoints (those starting in /api). These just return JSON.

Component Servers

This class contains a number of servers which don’t all have to be created, depending on what authentication you want to support. If instantiated, they can work together.

  • session_server Session cookie management server. Uses sesion ID

    and CSRF cookies. See FastApiSessionServer.

  • session_adapter If you want an OAuth client but not want to use

    Crossauth’s session server, you can provide your own with this. Won’t work with auth server.

  • oauth_auth_server OAuth authorization server. See

    FastApiAuthorizationServer

  • oauth_client OAuth client. See FastApiOAuthClient.

  • oauth_clients An array of OAuthClients if you want more than one.

    Use either this or oAuthClient but not both. See FastApiOAuthClient.

  • o_uth_res_server OAuth resource server. See

    FastApiOAuthResourceServer.

There is also an API key server which is not available as a variable as it has no functions other than the hook it registers. See FastApiApiKeyServer.

For a list of user-level URLs that can be enabled, and their input and output requirements, see FastApiSessionServer. FOr a list of admin endpoints that can be enabled, see FastApiAdminEndpoints.

property app
async create_anonymous_session(request: Request, response: Response, data: Dict[str, Any] | None = None) → str[source]

See FastApiSessionServer.create_anonymous_session().

Only available if there is a session server, not if you just providfe a session adapter. In this case, None is returned.

async delete_session_data(request: Request, name: str)[source]

See FastApiSessionServer.delete_session_data().

This is also available if you use a session adapter instead of a session server.

async error_if_csrf_invalid(request: Request, response: Response, error_fn: FastApiErrorFn | None) → MaybeErrorResponse[source]

Calls the passed error function passed if the CSRF token in the request is invalid.

Use this to require a CSRF token in your endpoints.

Parameters:

  • request (Request) – the FastAPI request

  • response (Response) – the FastAPI response object

  • error_fn (FastApiErrorFn|None) – the error function to call if the CSRF token is invalid

Returns:

if no error, returns an object with error set to false and

response set to the passed reply object. Otherwise returns the reply from calling error_fn.

property error_page

See FastApiSessionServer.get_session_cookie_value().

Only available if there is a session server, not if you just providfe a session adapter. In this case, None is returned.

async get_session_data(request: Request, name: str) → Dict[str, Any] | None[source]

See FastApiSessionServer.get_session_data().

This is also available if you use a session adapter instead of a session server.

property have_session_adapter: bool
property have_session_server: bool
property oauth_client
property oauth_clients
property oauth_resserver
property session_adapter
property session_server
property templates
async update_session_data(request: Request, name: str, value: Any)[source]

See FastApiSessionServer.update_session_data().

This is also available if you use a session adapter instead of a session server.

class crossauth_fastapi.FastApiServerBase[source]

Bases: ABC

This is an abstract base class for the FastApiServer which only exists to avoid cyclic references. You should not have to use it

abstract property app: FastAPI
abstractmethod async create_anonymous_session(request: Request, response: Response, data: Dict[str, Any] | None = None) → str[source]
abstractmethod async delete_session_data(request: Request, name: str)[source]
abstractmethod async error_if_csrf_invalid(request: Request, response: Response, error_fn: FastApiErrorFn | None) → MaybeErrorResponse[source]
abstract property error_page: str
abstractmethod async get_session_data(request: Request, name: str) → Dict[str, Any] | None[source]
abstract property have_session_adapter: bool
abstract property have_session_server: bool
is_admin() → bool

The function to determine if a user has admin rights can be set externally. This is the default function if none other is set. It returns true iff the admin field in the passed user is set to true.

Parameters:

user (crossauth_backend.User) – the user to test

:return true or false

static send_page_error(templates: Jinja2Templates, request: Request, reply: Response, status: int, error_page: str | None = None, error: str | None = None, e: Any | None = None) → Response[source]

Sends a reply by rendering the errorPage if present, or a standard error page if it isn’t.

The renderer configured for the reply object is called (Nunjucks by default) with the following data parameters: - errorCode See ErrorCode. - errorCodeName the text version of errorCode. - msg the error message - httpStatus the HTTP status code.

Parameters:

  • reply – the Fastify reply object

  • status – the HTTP status code to return

  • error_page – the error page to render.

  • error – an error message string. Ignored if e is defined.

  • e – optionally, an exception. This will be logged and the message will be sent to the error page.

Returns:

the reply from rendering the error page.

abstract property templates: Jinja2Templates
abstractmethod async update_session_data(request: Request, name: str, value: Any)[source]
class crossauth_fastapi.FastApiServerOptions[source]

Bases: FastApiSessionServerOptions, FastApiOAuthClientOptions, FastApiOAuthResourceServerOptions

Options for FastApiServer and it’s component subservers

add_to_session: Callable[[Request], Mapping[str, str | int | float | datetime | None]]
admin_allowed_factor1: List[str]
admin_create_client_page: str
admin_create_user_page: str
admin_prefix: str
admin_select_user_page: str
allowed_factor2: List[str]
api_delete_tokens_post_url: str
app: FastAPI

You can pass your own FastAPI instance or omit this, in which case Crossauth will create one

audience: str
auth_server_base_url: str
authorized_page: str
authorized_url: str
bff_base_url: str
bff_endpoint_name: str
bff_endpoints: List[BffEndpoint]
change_factor2_page: str
change_password_page: str
client_id: str
client_secret: str
client_serach_dn: Callable[[str, OAuthClientStorage, str | int | NullType], List[OAuthClient]]
clock_tolerance: int
code_challenge_method: Literal['plain', 'S256']
configure_factor2_page: str
create_user_fn: Callable[[Request, Dict[str, Any], List[str], List[str]], UserInputFields]
delete_client_page: str
delete_tokens_get_url: str
delete_tokens_page: str
delete_tokens_post_url: str
delete_user_page: str
device_authorization_url: str
device_code_flow_page: str
device_code_flow_url: str
device_code_poll_url: str
edit_user_scope: str
email_from: NotRequired[str]
email_token_storage: KeyStorage
email_verification_html_body: NotRequired[str]
email_verification_subject: NotRequired[str]
email_verification_text_body: NotRequired[str]
email_verified_page: str
enable_admin_endpoints: bool
enable_email_verification: bool
enable_oauth_client_management: bool
enable_password_reset: bool
endpoints: List[str]
error_body: Mapping[str, Any]
error_fn: FastApiErrorFn
error_page: str
error_response_type: Literal['json_error', 'page_error', 'custom']
factor2_page: str
factor2_protected_api_endpoints: List[str]
factor2_protected_page_endpoints: List[str]
id_token_match_field: str
is_admin_fn: Callable[[User], bool]

Function to return whether given user is an admin. If not set, the admin field of the user is used, which is assumed to be bool

jwt_key_type: str
jwt_public_key: str
jwt_public_key_file: str
jwt_secret_key: str
jwt_secret_key_file: str
jwt_tokens: List[Literal['access', 'id', 'refresh']]
key_storage: KeyStorage | None
login_page: str
login_redirect: str
logout_redirect: str
mfa_oob_page: str
mfa_otp_page: str
oauth_authorize_redirect: str | None
oauth_post_type: Literal['json', 'form']
oauth_use_user_info_endpoint: bool
oidc_config: OpenIdConfiguration | Dict[str, Any] | None
password_flow_page: str
password_flow_url: str
password_oob_url: str
password_otp_url: str
password_reset_expires: NotRequired[int]
password_reset_html_body: NotRequired[str]
password_reset_subject: NotRequired[str]
password_reset_text_body: NotRequired[str]
persist_access_token: bool
prefix: str
protected_endpoints: Mapping[str, ProtectedEndpoint]
receive_token_fn: Callable[[OAuthTokenResponse, Self, Request, Response | None], Response | None]
redirect_uri: str
render: NotRequired[Callable[[str, Dict[str, Any]], str]]
request_reset_password_page: str
reset_password_page: str
secret: str
session_adapter: FastApiSessionAdapter
session_data_name: str
signup_page: str
siteUrl: str
site_url: str
smtp_host: NotRequired[str]
smtp_password: NotRequired[str]
smtp_port: NotRequired[int]
smtp_use_tls: NotRequired[bool]
smtp_username: NotRequired[str]
state_length: int
template_dir: str

If this is passed, it is registered as a Jinja2 view folder

token_endpoints: List[Literal['access_token', 'refresh_token', 'id_token', 'have_access_token', 'have_refresh_token', 'have_id_token']]
token_locations: List[Literal['beader', 'session']]
token_response_type: Literal['send_json', 'save_in_session_and_load', 'save_in_session_and_redirect', 'send_in_page', 'custom']
update_user_fn: Callable[[User, Request, Dict[str, Any], List[str]], User]
update_user_page: str
user_allowed_factor1: List[str]
user_creation_fn: Callable[[Dict[str, Any], UserStorage | None, str, str], Awaitable[User | None]]
user_creation_type: Literal['idToken', 'merge', 'embed', 'custom']
user_match_field: str
user_search_fn: Callable[[str, UserStorage], List[User]]
user_storage: UserStorage
valid_flows: List[str]
validate_session: Callable[[Key, User | None, Request], None]
validate_user_fn: Callable[[UserInputFields], List[str]]
verifier_length: int
verify_email_expires: NotRequired[int]
views: NotRequired[str]
class crossauth_fastapi.FastApiServerParams[source]

Bases: TypedDict

Configuration for the FastAPI server - which services to instantiate

oauth_client: FastApiOAuthClientParams

Paramneters to create an OAuth client

oauth_clients: List[FastApiOAuthClientParams]

Paramneters to create an OAuth client

oauth_resserver: FastApiOAuthResServerParams

Paramneters to create an OAuth resource server

options: FastApiServerOptions

Global options which will be passed to all of the above (and be overridden by their own options if present)

session: FastApiSessionServerParams

Parameters to create a session server

session_adapter: FastApiSessionAdapter

If you are using a different session, implement FastApiSessionAdapter to use it, and pass it here

class crossauth_fastapi.FastApiSessionAdapter[source]

Bases: ABC

This class provides a minimal API that Crossauth needs from a cookie-based session management.

Its own FastApiSessionServer implements this.

If you want to your your favourite frameworks’ own session management, implement this adapter to use it and pass it to FastApiServer as session_adapter instead of session_manager.

abstractmethod csrf_protection_enabled() → bool[source]

Returns whether CSRF protection has been enabled,. Some backends provide this automatically in which case you can return False in your adapter. If your backend does not do this automatically, you should always implement it and return True

abstractmethod async delete_session_data(request: Request, name: str) → None[source]

Deletes a field from the session data in the key storage record,

The data field is assumed to be JSON. Just the field with the given name is updated and the rest is unchanged. :param request: the FastAPI request :param name: the field within data to update

abstractmethod get_csrf_token(request: Request) → str | None[source]

Return the CSRF token if one has been set or None

abstractmethod async get_session_data(request: Request, name: str) → Dict[str, Any] | None[source]

Return data stored in the session with key name or None if not present :param request: the FastAPI request :param name: name of the data to fetch

Returns:

a dictionary of the data, or None

abstractmethod get_user(request: Request) → User | None[source]

Return the logged in user if there is one or None

abstractmethod async update_many_session_data(request: Request, data_array: List[KeyDataEntry])[source]

Same as update_data but updates many within same transaction

The data field is assumed to be JSON. Just the field with the given name is updated and the rest is unchanged. :param request: the FastAPI request :param data_array: data to update

abstractmethod async update_session_data(request: Request, name: str, value: Any) → None[source]

Updates a field in the session data in the key storage record,

The data field is assumed to be JSON. Just the field with the given name is updated and the rest is unchanged. :param request: the FastAPI request :param name: the field within data to update :param value: the value to set it to

class crossauth_fastapi.FastApiSessionServer(app: FastAPI, key_storage: KeyStorage, authenticators: Mapping[str, Authenticator], options: FastApiSessionServerOptions = {})[source]

Bases: FastApiSessionServerBase

This class adds user endpoints to the FastAPI session server.

Important Note This class is imcomplete. It supports only enough functionality to provide CSRF cookies and anonymous sessions (where there is no user). The rest of the functionality will come later.

You shouldn’t have create create this directly - it is created by FastApiServer.

Using your own FastAPI app

If you are serving other endpoints, or you want to use something other than Nunjucks, you can create and pass in your own FastAPI app.

Middleware

This class registers one middleware function to fill in the following fields in Request.state:

  • user a crossauch_backend.User object which currently is always None

  • auth_type: set to cookie or None (currently always None)

  • csrf_token: a CSRF token that can be used in POST requests

  • session_id a session ID if one is created with create_anonymous_session()

add_api_cancel_factor2_endpoints()[source]
add_api_getcsrftoken_endpoints()[source]
add_api_login_endpoints()[source]
add_api_login_factor2_endpoints()[source]
add_api_logout_endpoints()[source]
add_api_signup_endpoints()[source]
add_api_user_for_session_key_endpoints()[source]
add_endpoints()[source]
add_factor2_endpoints()[source]
add_login_endpoints()[source]
add_login_factor2_endpoints()[source]
add_logout_endpoints()[source]
add_signup_endpoints()[source]
property admin_allowed_factor1
property allowed_factor2
allowed_factor2_details() → List[AuthenticatorDetails][source]

For each of the authenticators passed to the constructor, returns some details about it @returns a list of AuthenticatorDetails objects.

property app
property authenticators
can_edit_user(request: Request) → bool[source]

A user can edit his or her account if they are logged in with session management, or are logged in with some other means and e`ditUserScope` has been set and is included in the user’s scopes. @param request the Fastify request @returns true or false

async cancel_factor2(request: Request, resp: Response, success_fn: Callable[[Response], Response]) → Response[source]
async create_anonymous_session(request: Request, response: Response, data: Dict[str, Any] | None = None) → str[source]

Creates and persists an anonymous session.

An anonymous session is one which is not associated with a user. This is needed when you need to save session state, despite a user not being logged in.

:param Request request the FastAPI Request object :param Response request the FastAPI Response object :param Dict[str, Any] data optionally, data to store in the session.

The top level keys should not conflict with anything that FastAPI itself stores

csrf_protection_enabled() → bool[source]

See :meth:`FastApiSessionAdapter.csrf_protection_enabled

async csrf_token(request: Request, form: JsonOrFormData, headers: Dict[str, str] | None = None, add_cookies: Dict[str, Tuple[str, CookieOptions]] | None = None, delete_cookies: Set[str] | None = None, response: Response | None = None) → str | None[source]

Validates the CSRF token in the header or csrfToken form or JSON field and cookie value.

If it is then request.state.csrf_token is set. If not it is cleared.

Does not raise an exception

async delete_session_data(request: Request, name: str)[source]

See :meth:`FastApiSessionAdapter.delete_session_data

property enable_csrf_protection
property enable_email_verification: bool
property error_page
error_status(e: Exception) → int[source]

Helper function that returns the http_status field of an Exception, first casting it to a crossauth_backend.CrossauthError (if it wasn’t already a CrossauthError, the status will be 500).

Returns the CSRF cookie value or None if there isn’t one

Parameters:

request (Request) – the FastAPI Request

get_csrf_token(request: Request) → str | None[source]

See :meth:`FastApiSessionAdapter.get_csrf_token

get_hash_of_session_id(request: Request) → str[source]

Returns the session cookie value or None if there isn’t one

Parameters:

request (Request) – the FastAPI Request

async get_session_data(request: Request, name: str) → Dict[str, Any] | None[source]

See :meth:`FastApiSessionAdapter.get_session_data

get_user(request: Request) → User | None[source]

See :meth:`FastApiSessionAdapter.get_user

handle_error(e: Exception, request: Request, form: JsonOrFormData | None, error_fn: Callable[[Dict[str, Any], CrossauthError], Response], password_invalid_ok: bool = False) → Response[source]

Calls your defined error_fn, first sanitising by changing UserNotExist and UsernameOrPasswordInvalid messages to UsernameOrPasswordInvalid. Also logs the error

static is_admin(user: User)[source]
is_session_user(request: Request) → bool[source]

Returns whether there is a user logged in with a cookie-based session

property login_redirect
async login_with_user(user: User, bypass_2fa: bool, request: Request, resp: Response, success_fn: Callable[[Response, User], Response]) → Response[source]

This is called after the user has been validated to log the user in

send_json_error(request: Request, response: Response, status: int, error: str | None = None, e: Exception | None = None) → Response[source]

Returns an error as a FastAPI JSONResponse object, also logging it.

send_page_error(request: Request, response: Response, status: int, error: str | None = None, e: Exception | None = None) → Response[source]
property session_manager
property templates
async update_many_session_data(request: Request, data_array: List[KeyDataEntry])[source]

See :meth:`FastApiSessionAdapter.update_many_session_data

async update_session_data(request: Request, name: str, value: Any)[source]

See :meth:`FastApiSessionAdapter.update_session_data

static user(request: Request) → User | None[source]
property user_allowed_factor1
property user_storage
static username(request: Request) → str | None[source]
validate_csrf_token(request: Request) → str | None[source]

Validates the CSRF token in the Request.state and cookie value.

Parameters:

request (Request) – the FastAPI Request

Returns:

the CSRF cookie value if there is one

Raises:

crossauth_backend.CrossauthError with crossauth_backend.ErrorCode of `InvalidCsrf

class crossauth_fastapi.FastApiSessionServerOptions[source]

Bases: SessionManagerOptions

Options for FastApiSessionServer.

add_to_session: Callable[[Request], Mapping[str, str | int | float | datetime | None]]

Called when a new session token is going to be saved Add additional fields to your session storage here. Return a map of keys to values

admin_allowed_factor1: List[str]

When admins create a user, they may choose any of these. Default: [“localpassword”]

admin_create_client_page: str

The temaplte file for the admin creating a user. Default admin/createuser.njk

admin_create_user_page: str

The temaplte file for the admin create user page. Default admin/createuser.njk

admin_prefix: str

Admin URLs will be prefixed with this Default `admin/

admin_select_user_page: str

The temaplte file for the admin selecting a user. Default admin/selectuser.njk

allowed_factor2: List[str]
change_factor2_page: str

Page to render for selecting a different 2FA. See the class documentation for {@link FastifyServer} for more info. efaults to “changepassword.njk”.

change_password_page: str

Page to render for password changing. See the class documentation for {@link FastifyServer} for more info. efaults to “changepassword.njk”.

client_serach_dn: Callable[[str, OAuthClientStorage, str | int | NullType], List[OAuthClient]]

Admin pages provide functionality for searching for OAuth clients. By default the search string must exactly match the client_name. Override this behaviour with this function :param searchTerm the search term :param clientStorage the client storage to search :param userid if defined and non null, only clients owned by that

user ID will be returned. If null, only clients not owned by a user will be returned. If undefined, all matching clients will be returned

:return array of matching clients

configure_factor2_page: str

Page to set up 2FA after sign up

create_user_fn: Callable[[Request, Dict[str, Any], List[str], List[str]], UserInputFields]

Function that creates a user from form fields. Default one takes fields that begin with user_, removing the user_ prefix and filtering out anything not in the userEditableFields list in the user storage.

delete_client_page: str
delete_user_page: str

Confirm deleting a user

edit_user_scope: str

This parameter affects users who are not logged in with a session ID ut with an OAuth access token. Such users can only update their user ecord if the scoped named in this variable has been authorized by hat user for the client.

y default, no scopes are authorized to edit the user.

email_from: NotRequired[str]
email_token_storage: KeyStorage
email_verification_html_body: NotRequired[str]
email_verification_subject: NotRequired[str]
email_verification_text_body: NotRequired[str]
email_verified_page: str

Page to render for to confirm email has been verified. Only created if enableEmailVerification is true. ee the class documentation for {@link FastifyServer} for more info. efaults to “emailverified.njk”

enable_admin_endpoints: bool
enable_email_verification: bool

Turns on email verification. This will cause the verification tokens to e sent when the account s activated and when email is changed. Default false.

enable_oauth_client_management: bool

If true, all endpoints for managing OAuth clients (including he admin ones if enableAdminEndpoints is also true). If you explicitly name which endpoints to enable with the endpoints option, this is ignored. Default false

enable_password_reset: bool
endpoints: List[str]

List of endpoints to add to the server (“login”, “api/login”, etc, prefixed by the prefix parameter. Empty for allMinusOAuth. Default allMinusOAuth.

error_page: str

Page to render error messages, including failed login. See the class documentation for FastApiServer for more info. Defaults to “error.jinja2”.

factor2_page: str

Template file containing the page for getting the 2nd factor for 2FA protected pages. See the class documentation for {@link FastifyServer} for more info. Defaults to “factor2.njk”.

factor2_protected_api_endpoints: List[str]

These page endpoints need the second factor to be entered. Making a call to these endpoints results in a response of {“ok”: true, “factor2Required”: true }. The user should then make a call to `/api/factor2. If the credetials are correct, the response will be that of the original request.

You probably want to do this for things like changing password. The

default is

/api/requestpasswordreset, /api/updateuser, /api/changepassword, /api/resetpassword, /api/changefactor2,

factor2_protected_page_endpoints: List[str]

These page endpoints need the second factor to be entered. Visiting the page redirects the user to the factor2 page.

You probably want to do this for things like changing password. The

default is

/requestpasswordreset, /updateuser, /changepassword, /resetpassword, /changefactor2,

login_page: str

Template file containing the login page (with without error messages). See the class documentation for {@link FastifyServer} for more info. Defaults to “login.njk”.

login_redirect: str

Page to redirect to after successful login, default “/”

logout_redirect: str

Page to redirect to after successful logout, default “/”

password_reset_expires: NotRequired[int]
password_reset_html_body: NotRequired[str]
password_reset_subject: NotRequired[str]
password_reset_text_body: NotRequired[str]
prefix: str

All endpoint URLs will be prefixed with self. Default /

render: NotRequired[Callable[[str, Dict[str, Any]], str]]
request_reset_password_page: str

Page to ask user for email and reset his/her password. See the class documentation for {@link FastifyServer} for more info. efaults to “requestpasswordreset.njk”.

reset_password_page: str

Page to render for password reset, after the emailed token has been validated. ee the class documentation for {@link FastifyServer} for more info. efaults to “resetpassword.njk”.

secret: str
signup_page: str

Template file containing the signup page (with without error messages). See the class documentation for {@link FastifyServer} for more info. Defaults to “signup.njk”. Signup form should contain at least username and password and may also contain repeatPassword. If you have additional fields in your user table you want to pass from your form, prefix them with user_, eg user_email. If you want to enable email verification, set enable_email_verification and set checkEmailVerified on the user storage.

site_url: str
smtp_host: NotRequired[str]
smtp_password: NotRequired[str]
smtp_port: NotRequired[int]
smtp_use_tls: NotRequired[bool]
smtp_username: NotRequired[str]
update_user_fn: Callable[[User, Request, Dict[str, Any], List[str]], User]

Function that updates a user from form fields. Default one takes fields that begin with user_, removing the user_

prefix and filtering out anything not in the userEditableFields list in

the user storage.

update_user_page: str

Page to render for updating user details. See the class documentation for {@link FastifyServer} for more info. efaults to “updateuser.njk”.

user_allowed_factor1: List[str]

When signing up themselves, users may choose any of these. Default: [“localpassword”]

user_search_fn: Callable[[str, UserStorage], List[User]]

Admin pages provide functionality for searching for users. By default the search string must exactly match a username or email address (depending on the storage, after normalizing and lowercasing). Override this behaviour with this function :param searchTerm the search term :param userStorage the user storage to search :return array of matching users

user_storage: UserStorage
validate_session: Callable[[Key, User | None, Request], None]

Called after the session ID is validated. Use this to add additional checks based on the request. Throw an exception if cecks fail

validate_user_fn: Callable[[UserInputFields], List[str]]

crossauth_backend.common.CrossauthError} with :class: crossauth_backend.common.ErrorCode FormEnty if the user doesn’t confirm to local rules. Doesn’t validate passwords

Type:

Function that raises a

Type:

class

verify_email_expires: NotRequired[int]
views: NotRequired[str]
class crossauth_fastapi.FastApiSessionServerParams[source]

Bases: TypedDict

Parameters that are used to create a session server

key_storage: Required[KeyStorage]
options: FastApiSessionServerOptions
class crossauth_fastapi.ProtectedEndpoint[source]

Bases: TypedDict

accept_session_authorization: bool
scope: List[str]
suburls: bool