fastapi_sso.sso.base

SSO login base dependency.

Classes:

Name	Description
`DiscoveryDocument`	Discovery document.
`OpenID`	Class (schema) to represent information got from sso provider in a common form.
`ReusedOauthClientWarning`	Warning about reused oauth client instance.
`SSOBase`	Base class for all SSO providers.
`SSOLoginError`	Raised when any login-related error ocurrs.
`SecurityWarning`	Raised when insecure usage is detected
`UnsetStateWarning`	Warning about unset state parameter.

`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.

Methods:

Name	Description
`__init__`	Base class (mixin) for all SSO providers.
`get_discovery_document`	Retrieves the discovery document containing useful URLs.
`get_login_redirect`	Constructs and returns a redirect response to the login page of OAuth SSO provider.
`get_login_url`	Generates and returns the prepared login URL.
`openid_from_response`	Converts a response from the provider's user info endpoint to an OpenID object.
`openid_from_token`	Converts an ID token from the provider's token endpoint to an OpenID object.
`process_login`	Processes login from the callback endpoint to verify the user and request user info endpoint.
`verify_and_process`	Processes the login given a FastAPI (Starlette) Request object. This should be used for the /callback path.

Attributes:

Name	Type	Description
`access_token`	`Optional[str]`	Retrieves the access token from token endpoint.
`authorization_endpoint`	`Optional[str]`	Return `authorization_endpoint` from discovery document.
`id_token`	`Optional[str]`	Retrieves the id token if returned from provider.
`oauth_client`	`WebApplicationClient`	Retrieves the OAuth Client to aid in generating requests and parsing responses.
`refresh_token`	`Optional[str]`	Retrieves the refresh token if returned from provider.
`state`	`Optional[str]`	Retrieves the state as it was returned from the server.
`token_endpoint`	`Optional[str]`	Return `token_endpoint` from discovery document.
`userinfo_endpoint`	`Optional[str]`	Return `userinfo_endpoint` from discovery document.

`access_token` `property`

Retrieves the access token from token endpoint.

Returns:

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

`authorization_endpoint` `async` `property`

Return authorization_endpoint from discovery document.

`id_token` `property`

Retrieves the id token if returned from provider.

Returns:

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

`oauth_client` `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` `property`

Retrieves the refresh token if returned from provider.

Returns:

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

`state` `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` `async` `property`

Return token_endpoint from discovery document.

`userinfo_endpoint` `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.

`openid_from_token(id_token, session=None)` `async`

Converts an ID token from the provider's token endpoint to an OpenID object.

Parameters:

Name	Type	Description	Default
`id_token`	`dict`	The id token data retrieved from the token endpoint.	required
`session`	`Optional[AsyncClient]`	(Optional[httpx.AsyncClient]): The HTTPX AsyncClient session.	`None`

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`

Python

process_login(
    code: str,
    request: Request,
    *,
    params: Optional[dict[str, Any]] = None,
    additional_headers: Optional[dict[str, Any]] = None,
    redirect_uri: Optional[str] = None,
    pkce_code_verifier: Optional[str] = None,
    convert_response: Literal[True] = True
) -> Optional[OpenID]

Python

process_login(
    code: str,
    request: Request,
    *,
    params: Optional[dict[str, Any]] = None,
    additional_headers: Optional[dict[str, Any]] = None,
    redirect_uri: Optional[str] = None,
    pkce_code_verifier: Optional[str] = None,
    convert_response: Literal[False]
) -> Optional[dict[str, Any]]

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`

Python

verify_and_process(
    request: Request,
    *,
    params: Optional[dict[str, Any]] = None,
    headers: Optional[dict[str, Any]] = None,
    redirect_uri: Optional[str] = None,
    convert_response: Literal[True] = True
) -> Optional[OpenID]

Python

verify_and_process(
    request: Request,
    *,
    params: Optional[dict[str, Any]] = None,
    headers: Optional[dict[str, Any]] = None,
    redirect_uri: Optional[str] = None,
    convert_response: Literal[False]
) -> Optional[dict[str, Any]]

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.

`SecurityWarning`

Bases: UserWarning

Raised when insecure usage is detected

`UnsetStateWarning`

Bases: UserWarning

Warning about unset state parameter.

fastapi_sso.sso.base

DiscoveryDocument

OpenID

ReusedOauthClientWarning

SSOBase

access_token property

authorization_endpoint async property

id_token property

oauth_client property

refresh_token property

state property

token_endpoint async property

userinfo_endpoint async property

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

get_discovery_document() async

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

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

openid_from_response(response, session=None) async

openid_from_token(id_token, session=None) async

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

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

SSOLoginError

SecurityWarning

UnsetStateWarning

`DiscoveryDocument`

`OpenID`

`ReusedOauthClientWarning`

`SSOBase`

`access_token` `property`

`authorization_endpoint` `async` `property`

`id_token` `property`

`oauth_client` `property`

`refresh_token` `property`

`state` `property`

`token_endpoint` `async` `property`

`userinfo_endpoint` `async` `property`

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

`get_discovery_document()` `async`

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

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

`openid_from_response(response, session=None)` `async`

`openid_from_token(id_token, session=None)` `async`

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

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

`SSOLoginError`

`SecurityWarning`

`UnsetStateWarning`