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 |
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 |
userinfo_endpoint |
Optional[str]
|
Return |
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 |
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 |
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 |
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 |
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
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 |
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 |
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.