fastapi_sso.sso.base

SSO login base dependency.

DiscoveryDocument

Bases: TypedDict

Discovery document.

OpenID

Bases: BaseModel

Class (schema) to represent information got from sso provider in a common form.

ReusedOauthClientWarning

Bases: UserWarning

Warning about reused oauth client instance.

SSOBase

Base class for all SSO providers.

access_token: Optional[str] property

Retrieves the access token from token endpoint.

Returns:

Type	Description
Optional[str]	Optional[str]: The access token if available.

authorization_endpoint: Optional[str] async property

Return authorization_endpoint from discovery document.

id_token: Optional[str] property

Retrieves the id token if returned from provider.

Returns:

Type	Description
Optional[str]	Optional[str]: The id token if available.

oauth_client: WebApplicationClient property

Retrieves the OAuth Client to aid in generating requests and parsing responses.

Raises:

Type	Description
NotImplementedError	If the provider is not supported or client_id is not set.

Returns:

Name	Type	Description
WebApplicationClient	WebApplicationClient	OAuth client instance.

refresh_token: Optional[str] property

Retrieves the refresh token if returned from provider.

Returns:

Type	Description
Optional[str]	Optional[str]: The refresh token if available.

state: Optional[str] property

Retrieves the state as it was returned from the server.

Warning

This will emit a warning if the state is unset, implying either that the server didn't return a state or verify_and_process hasn't been called yet.

Returns:

Type	Description
Optional[str]	Optional[str]: The state parameter returned from the server.

token_endpoint: Optional[str] async property

Return token_endpoint from discovery document.

userinfo_endpoint: Optional[str] async property

Return userinfo_endpoint from discovery document.

__init__(client_id, client_secret, redirect_uri=None, allow_insecure_http=False, use_state=False, scope=None)

Base class (mixin) for all SSO providers.

get_discovery_document() async

Retrieves the discovery document containing useful URLs.

Raises:

Type	Description
NotImplementedError	If the provider is not supported.

Returns:

Name	Type	Description
DiscoveryDocument	DiscoveryDocument	A dictionary containing important endpoints like authorization, token and userinfo.

get_login_redirect(*, redirect_uri=None, params=None, state=None) async

Constructs and returns a redirect response to the login page of OAuth SSO provider.

Parameters:

Name	Type	Description	Default
redirect_uri	Optional[str]	Overrides the redirect_uri specified on this instance.	None
params	Optional[Dict[str, Any]]	Additional query parameters to add to the login request.	None
state	Optional[str]	The state parameter for the OAuth 2.0 authorization request.	None

Returns:

Name	Type	Description
RedirectResponse	RedirectResponse	A Starlette response directing to the login page of the OAuth SSO provider.

get_login_url(*, redirect_uri=None, params=None, state=None) async

Generates and returns the prepared login URL.

Parameters:

Name	Type	Description	Default
redirect_uri	Optional[str]	Overrides the redirect_uri specified on this instance.	None
params	Optional[Dict[str, Any]]	Additional query parameters to add to the login request.	None
state	Optional[str]	The state parameter for the OAuth 2.0 authorization request.	None

Raises:

Type	Description
ValueError	If redirect_uri is not provided either at construction or request time.

Returns:

Name	Type	Description
str	str	The prepared login URL.

openid_from_response(response, session=None) async

Converts a response from the provider's user info endpoint to an OpenID object.

Parameters:

Name	Type	Description	Default
response	dict	The response from the user info endpoint.	required
session	Optional[AsyncClient]	The HTTPX AsyncClient session.	None

Raises:

Type	Description
NotImplementedError	If the provider is not supported.

Returns:

Name	Type	Description
OpenID	OpenID	The user information in a standardized format.

process_login(code, request, *, params=None, additional_headers=None, redirect_uri=None, pkce_code_verifier=None, convert_response=True) async

Processes login from the callback endpoint to verify the user and request user info endpoint. It's a lower-level method, typically, you should use verify_and_process instead.

Parameters:

Name	Type	Description	Default
code	str	The authorization code.	required
request	Request	FastAPI or Starlette request object.	required
params	Optional[Dict[str, Any]]	Additional query parameters to pass to the provider.	None
additional_headers	Optional[Dict[str, Any]]	Additional headers to be added to all requests.	None
redirect_uri	Optional[str]	Overrides the redirect_uri specified on this instance.	None
pkce_code_verifier	Optional[str]	A PKCE code verifier sent to the server to verify the login request.	None
convert_response	bool	If True, userinfo response is converted to OpenID object.	True

Raises:

Type	Description
ReusedOauthClientWarning	If the SSO object is reused, which is not safe and caused security issues.

Returns:

Type	Description
Union[Optional[OpenID], Optional[Dict[str, Any]]]	Optional[OpenID]: User information in OpenID format if the login was successful (convert_response == True).
Union[Optional[OpenID], Optional[Dict[str, Any]]]	Optional[Dict[str, Any]]: Original userinfo API endpoint response.

verify_and_process(request, *, params=None, headers=None, redirect_uri=None, convert_response=True) async

Processes the login given a FastAPI (Starlette) Request object. This should be used for the /callback path.

Parameters:

Name	Type	Description	Default
request	Request	FastAPI or Starlette request object.	required
params	Optional[Dict[str, Any]]	Additional query parameters to pass to the provider.	None
headers	Optional[Dict[str, Any]]	Additional headers to pass to the provider.	None
redirect_uri	Optional[str]	Overrides the redirect_uri specified on this instance.	None
convert_response	bool	If True, userinfo response is converted to OpenID object.	True

Raises:

Type	Description
SSOLoginError	If the 'code' parameter is not found in the callback request.

Returns:

Type	Description
Union[Optional[OpenID], Optional[Dict[str, Any]]]	Optional[OpenID]: User information as OpenID instance (if convert_response == True)
Union[Optional[OpenID], Optional[Dict[str, Any]]]	Optional[Dict[str, Any]]: The original JSON response from the API.

SSOLoginError

Bases: HTTPException

Raised when any login-related error ocurrs.

Such as when user is not verified or if there was an attempt for fake login.

UnsetStateWarning

Bases: UserWarning

Warning about unset state parameter.