Authorization Code Grant with PKCE

OAuth 2.0 Authorization Code Grant with Proof Key for Code Exchange (RFC 7636).

PKCE Utilities

generate_code_verifier(length=_DEFAULT_VERIFIER_LENGTH)

Generate a cryptographically random code verifier.

Parameters:

Name	Type	Description	Default
length	int	Verifier length in characters (43-128 per RFC 7636).	_DEFAULT_VERIFIER_LENGTH

Returns:

Type	Description
str	URL-safe random string suitable for use as a PKCE code verifier.

Raises:

Type	Description
ValueError	If length is outside the allowed range.

generate_code_challenge(verifier, method='S256')

Derive a code challenge from a code verifier.

Parameters:

Name	Type	Description	Default
verifier	str	The code verifier string.	required
method	str	Challenge method — "S256" (recommended) or "plain".	'S256'

Returns:

Type	Description
str	The code challenge string.

Raises:

Type	Description
ValueError	If method is not "S256" or "plain", or if verifier length is outside the 43-128 range (RFC 7636).

generate_pkce_pair(method='S256', verifier_length=_DEFAULT_VERIFIER_LENGTH)

Generate a PKCE code verifier and challenge pair.

Parameters:

Name	Type	Description	Default
method	str	Challenge method — "S256" (default) or "plain".	'S256'
verifier_length	int	Length of the generated verifier (43-128).	_DEFAULT_VERIFIER_LENGTH

Returns:

Type	Description
tuple[str, str]	(code_verifier, code_challenge) tuple.

Authorization URL

build_authorization_url(authorization_endpoint, client_id, redirect_uri, scope='openid', response_type='code', state=None, nonce=None, code_challenge=None, code_challenge_method=None, **extra_params)

Build an OAuth 2.0 / OIDC authorization endpoint URL.

Constructs a URL with query parameters for redirecting the user to the authorization server. PKCE parameters (code_challenge and code_challenge_method) are included when provided.

Parameters:

Name	Type	Description	Default
authorization_endpoint	str	The authorization server's authorize URL (typically from the discovery document).	required
client_id	str	The registered client identifier.	required
redirect_uri	str	The callback URL registered with the authorization server.	required
scope	str	Space-delimited scopes (default "openid").	'openid'
response_type	str	OAuth 2.0 response type (default "code").	'code'
state	str | None	Opaque CSRF protection value.	None
nonce	str | None	OpenID Connect nonce for replay protection.	None
code_challenge	str | None	PKCE code challenge (from :func:generate_code_challenge).	None
code_challenge_method	str | None	PKCE method — "S256" or "plain".	None
**extra_params	str	Additional query parameters.	{}

Returns:

Type	Description
str	The full authorization URL ready for redirect.

Raises:

Type	Description
ValueError	If extra_params contains a reserved OAuth parameter, if code_challenge is given without code_challenge_method (or vice versa per RFC 7636 §4.3), if authorization_endpoint is empty, or if code_challenge_method is not "S256" or "plain".

Token Exchange

AuthorizationCodeTokenRequest(address, client_id, code, redirect_uri, code_verifier=None, client_secret=None, scope=None) dataclass

Bases: BaseRequest

Request for exchanging an authorization code for tokens.

Attributes:

Name	Type	Description
address	str	The token endpoint URL.
client_id	str	The client identifier.
code	str	The authorization code received from the callback.
redirect_uri	str	The same redirect URI used in the authorization request.
code_verifier	str | None	PKCE code verifier (required when PKCE was used).
client_secret	str | None	Client secret (optional for public clients per RFC 7636).
scope	str | None	Space-delimited list of requested scopes (optional).

AuthorizationCodeTokenResponse(is_successful, error=None, token=None) dataclass

Bases: BaseResponse

Response from an authorization code token exchange.

Check is_successful before accessing token. The token dict typically contains access_token, token_type, expires_in, refresh_token, and optionally id_token.