Authorize Callback

Parse OAuth 2.0 / OIDC authorization callback redirect URIs and validate the state parameter for CSRF protection.

These functions are pure (no I/O) and available identically from both sync and async modules.

Response Model

AuthorizeCallbackResponse(is_successful, raw, values, code=None, access_token=None, identity_token=None, token_type=None, expires_in=None, scope=None, refresh_token=None, state=None, session_state=None, issuer=None, error=None, error_description=None) dataclass

Bases: _GuardedResponseMixin

Parsed OAuth 2.0 / OIDC authorization callback response.

Fields like code and access_token are guarded: accessing them raises FailedResponseAccessError when is_successful is False. The state field is not guarded, per RFC 6749 Section 4.1.2.1 which requires state in error responses so callers can correlate errors with the original request.

.. warning::

The raw field contains the full redirect URI and values contains all parsed parameters. For implicit/hybrid flows these may include access_token in cleartext. Avoid logging, serializing, or persisting these fields in production.

__repr__()

Redact sensitive fields to prevent token leakage in logs.

Parsing

parse_authorize_callback_response(redirect_uri)

Parse an OAuth 2.0 / OIDC authorization callback redirect URI.

Extracts parameters from the URL fragment (implicit / hybrid flows) or query string (authorization code flow). Fragment takes precedence when both are present, matching standard browser behavior where the authorization server places parameters in one location.

Parameters:

Name	Type	Description	Default
redirect_uri	str	The full callback URL received from the authorization server (e.g. https://app.example.com/callback?code=abc&state=xyz).	required

Returns:

Type	Description
AuthorizeCallbackResponse	An AuthorizeCallbackResponse with is_successful=False when the
AuthorizeCallbackResponse	URL contains an error parameter, or True otherwise.

Raises:

Type	Description
AuthorizeCallbackException	If redirect_uri is None, not a string, empty/whitespace-only, uses a non-HTTP(S) scheme, or contains no callback parameters.

State Validation

AuthorizeCallbackValidationResult

Bases: Enum

Outcome of authorization callback state validation.

StateValidationResult(is_valid, result, error=None, error_description=None) dataclass

Result of validating the state parameter in an authorization callback.

validate_authorize_callback_state(response, expected_state)

Validate the state parameter from an authorization callback.

Checks are performed in priority order:

1. Error response — if the authorization server returned an error, validation fails with ERROR_RESPONSE.
2. Missing state — if the callback or the caller-supplied expected_state is None or an empty string, validation fails with MISSING_STATE. Non-string types are also treated as missing.
3. State mismatch — the received state is compared to expected_state using hmac.compare_digest (constant-time) to avoid timing side-channels.

Parameters:

Name	Type	Description	Default
response	AuthorizeCallbackResponse	A parsed AuthorizeCallbackResponse.	required
expected_state	str | None	The state value sent in the original authorization request. May be None when the caller's session has expired or no state was stored.	required

Returns:

Type	Description
StateValidationResult	A StateValidationResult indicating whether validation passed.