Oauth2

Implements OAuth2 authoriser flows.

See specification for more info: https://auth0.com/docs/authenticate/protocols/oauth

Classes:

OAuth2Authoriser(token_request[, ...])	Abstract implementation of an Authoriser for OAuth2 authorisation flows.
ClientCredentialsFlow(token_request[, ...])	Authorises using OAuth2 specification following the 'Client Credentials' flow specification.
AuthorisationCodeFlow(user_request, ...[, ...])	Authorises using OAuth2 specification following the 'Authorization Code' flow specification.
AuthorisationCodePKCEFlow(user_request, ...)	Authorises using OAuth2 specification following the 'Authorization Code with PKCE' flow specification.

class aiorequestful.auth.oauth2.OAuth2Authoriser(token_request, service_name='unknown_service', response_handler=None, response_tester=None)

Bases: Authoriser

Abstract implementation of an Authoriser for OAuth2 authorisation flows.

Attributes:

is_token_valid	Check if the currently loaded token is valid
token_request	Request to exchange the authorisation code for an access token
response	Handles saving and loading token request responses and generates headers from a token request
tester	Tests the response given from the token request to ensure the token is valid

property is_token_valid: Awaitable[bool]

Check if the currently loaded token is valid

token_request

Request to exchange the authorisation code for an access token

response

Handles saving and loading token request responses and generates headers from a token request

tester

Tests the response given from the token request to ensure the token is valid

class aiorequestful.auth.oauth2.ClientCredentialsFlow(token_request, service_name='unknown_service', response_handler=None, response_tester=None)

Bases: OAuth2Authoriser

Authorises using OAuth2 specification following the ‘Client Credentials’ flow specification.

See more: https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-credentials-flow

Methods:

create(token_request_url, client_id, ...[, ...])	Initialises a basic object, generating core request objects from given arguments.
create_with_encoded_credentials(...[, ...])	Initialises a basic object, generating core request objects from given arguments.
authorise()	Authenticate and authorise, testing/refreshing/re-authorising as needed.

classmethod create(token_request_url, client_id, client_secret, service_name='unknown_service')

Initialises a basic object, generating core request objects from given arguments. Sets requests to send the credentials as parameters for each required request.

Parameters:

• service_name (str (default: 'unknown_service')) – The service name for which to authorise.

• token_request_url (str | URL) – The URL to call when requesting a new token.

• client_id (str) – The client ID.

• client_secret (str) – The client secret.

Returns:

Self – The initialised object.

classmethod create_with_encoded_credentials(token_request_url, client_id, client_secret, service_name='unknown_service')

Initialises a basic object, generating core request objects from given arguments. Encodes the client credentials in base64 format and sets requests to send the encoded credentials in the headers of each required request.

Parameters:

• service_name (str (default: 'unknown_service')) – The service name for which to authorise.

• token_request_url (str | URL) – The URL to call when requesting a new token.

• client_id (str) – The client ID.

• client_secret (str) – The client secret.

Returns:

Self – The initialised object.

async authorise()

Authenticate and authorise, testing/refreshing/re-authorising as needed.

Raises:

AuthoriserError – If the authorisation failed to generate valid a token if needed, or if the tests continue to fail despite authorising/re-authorising.

class aiorequestful.auth.oauth2.AuthorisationCodeFlow(user_request, token_request, refresh_request=None, service_name='unknown_service', socket_handler=None, redirect_uri=None, response_handler=None, response_tester=None)

Bases: OAuth2Authoriser

Authorises using OAuth2 specification following the ‘Authorization Code’ flow specification.

See more: https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow

Parameters:

• service_name (str (default: 'unknown_service')) – The service name for which to authorise.

• user_request (AuthRequest) – Request to initiate user authentication and authorisation through an /authorize endpoint.

• token_request (AuthRequest) – Request to exchange the authorisation code for an access token.

• refresh_request (AuthRequest | None (default: None)) – Request to refresh an access token using the refresh token from the token request response.

• redirect_uri (str | URL (default: None)) – The callback URL to apply to the user request to allow for the retrieval of the authorisation code. Also sent as a parameter to the token request as part of identity confirmation.

• socket_handler (SocketHandler (default: None)) – Opens a socket on localhost to listen for a request on the redirect_url.

• response_handler (AuthResponse (default: None)) – Handles manipulation and storing of the response from a token exchange.

• response_tester (AuthTester (default: None)) – Tests the response given from the token request to ensure the token is valid.

Methods:

create(user_request_url, token_request_url, ...)	Initialises a basic object, generating core request objects from given arguments.
create_with_encoded_credentials(...[, ...])	Initialises a basic object, generating core request objects from given arguments.
authorise()	Authenticate and authorise, testing/refreshing/re-authorising as needed.

Attributes:

user_request	Request to initiate user authentication and authorisation through an /authorize endpoint
refresh_request	Request to refresh an access token using the refresh token from the token request response
redirect_uri	The callback URL to apply to the user request to allow for the retrieval of the authorisation code
socket_handler	Opens a socket on localhost to listen for a request on the redirect_url

classmethod create(user_request_url, token_request_url, client_id, client_secret, refresh_request_url=None, scope=(), service_name='unknown_service')

Initialises a basic object, generating core request objects from given arguments. Sets requests to send the credentials as parameters for each required request.

Parameters:

• service_name (str (default: 'unknown_service')) – The service name for which to authorise.

• user_request_url (str | URL) – The URL to configure for the user to authorise access to the application.

• token_request_url (str | URL) – The URL to call when requesting a new token.

• refresh_request_url (str | URL (default: None)) – The URL to call when refreshing a token.

• client_id (str) – The client ID.

• client_secret (str) – The client secret.

• scope (GenericAlias[str] (default: ())) – The scope/s to request access for from the user during user authorisation.

Returns:

Self – The initialised object.

classmethod create_with_encoded_credentials(user_request_url, token_request_url, client_id, client_secret, refresh_request_url=None, scope=(), service_name='unknown_service')

Initialises a basic object, generating core request objects from given arguments. Encodes the client credentials in base64 format and sets requests to send the encoded credentials in the headers of each required request.

Parameters:

• service_name (str (default: 'unknown_service')) – The service name for which to authorise.

• user_request_url (str | URL) – The URL to configure for the user to authorise access to the application.

• token_request_url (str | URL) – The URL to call when requesting a new token.

• refresh_request_url (str | URL (default: None)) – The URL to call when refreshing a token.

• client_id (str) – The client ID.

• client_secret (str) – The client secret.

• scope (GenericAlias[str] (default: ())) – The scope/s to request access for from the user during user authorisation.

Returns:

Self – The initialised object.

user_request

Request to initiate user authentication and authorisation through an /authorize endpoint

refresh_request

Request to refresh an access token using the refresh token from the token request response

redirect_uri

The callback URL to apply to the user request to allow for the retrieval of the authorisation code

socket_handler

Opens a socket on localhost to listen for a request on the redirect_url

async authorise()

Authenticate and authorise, testing/refreshing/re-authorising as needed.

Raises:

AuthoriserError – If the authorisation failed to generate valid a token if needed, or if the tests continue to fail despite authorising/re-authorising.

class aiorequestful.auth.oauth2.AuthorisationCodePKCEFlow(user_request, token_request, refresh_request=None, service_name='unknown_service', socket_handler=None, redirect_uri=None, response_handler=None, response_tester=None, pkce_code_length=128)

Bases: AuthorisationCodeFlow

Authorises using OAuth2 specification following the ‘Authorization Code with PKCE’ flow specification.

See more: https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce

Parameters:

• service_name (str (default: 'unknown_service')) – The service name for which to authorise.

• user_request (AuthRequest) – Request to initiate user authentication and authorisation through an /authorize endpoint.

• token_request (AuthRequest) – Request to exchange the authorisation code for an access token.

• refresh_request (AuthRequest | None (default: None)) – Request to refresh an access token using the refresh token from the token request response.

• redirect_uri (str | URL (default: None)) – The callback URL to apply to the user request to allow for the retrieval of the authorisation code. Also sent as a parameter to the token request as part of identity confirmation.

• socket_handler (SocketHandler (default: None)) – Opens a socket on localhost to listen for a request on the redirect_url.

• response_handler (AuthResponse (default: None)) – Handles manipulation and storing of the response from a token exchange.

• response_tester (AuthTester (default: None)) – Tests the response given from the token request to ensure the token is valid.

Methods:

create(user_request_url, token_request_url, ...)

Initialises a basic object, generating core request objects from given arguments.

Attributes:

code_verifier

classmethod create(user_request_url, token_request_url, client_id, refresh_request_url=None, scope=(), service_name='unknown_service', **__)

Initialises a basic object, generating core request objects from given arguments.

Parameters:

• service_name (str (default: 'unknown_service')) – The service name for which to authorise.

• user_request_url (str | URL) – The URL to configure for the user to authorise access to the application.

• token_request_url (str | URL) – The URL to call when requesting a new token.

• refresh_request_url (str | URL (default: None)) – The URL to call when refreshing a token.

• client_id (str) – The client ID.

• scope (GenericAlias[str] (default: ())) – The scope/s to request access for from the user during user authorisation.

Returns:

Self – The initialised object.

code_verifier