Skip to content

OpenID Connect

reauth.factors.oauth2.oidc

CLIENT_ASSERTION_TYPE module-attribute 

CLIENT_ASSERTION_TYPE = (
    "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
)

Signer

Bases: Protocol

Produces JWS signatures.

An implementation either holds the private key in process, as JWKSSigner does, or delegates to a remote signer that never releases it, such as a cloud key management service. kid is advertised in the JOSE header so a verifier can select the matching public key from a multi-key JWKS.

kid instance-attribute 

kid: str

algorithm instance-attribute 

algorithm: str

sign 

sign(signing_input: bytes) -> bytes

JWKSSigner 

JWKSSigner(jwks: PyJWKSet, kid: str)

Signs in process with a private key selected from a JWK set by ID.

kid instance-attribute 

kid = kid

algorithm instance-attribute 

algorithm = key.algorithm_name

sign 

sign(signing_input: bytes) -> bytes

OIDCException 

OIDCException(message: str | None = None)

Bases: OAuth2Exception

Base exception for OpenID Connect errors.

DiscoveryDocumentException 

DiscoveryDocumentException(message: str | None = None)

Bases: OIDCException

Raised when there is an error fetching or parsing the OpenID Connect discovery document.

JWKSFetchException 

JWKSFetchException(message: str | None = None)

Bases: OIDCException

Raised when there is an error fetching the JWKS for ID Token validation.

InvalidIDTokenException 

InvalidIDTokenException(message: str | None = None)

Bases: OIDCException

Raised when an ID Token fails validation.

SigningKeyNotFoundException 

SigningKeyNotFoundException(kid: str)

Bases: OIDCException

Raised when the configured signing key ID is not present in the JWKS.

kid instance-attribute 

kid = kid

OIDCExtraParams

Bases: TypedDict

Extra parameters for OpenID Connect authorization URL.

References
  • OpenID Connect Core 1.0: https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest

scope instance-attribute 

scope: str

response_type instance-attribute 

response_type: Literal[
    "code",
    "id_token",
    "code id_token",
    "code token",
    "id_token token",
]

nonce instance-attribute 

nonce: str

display instance-attribute 

display: Literal['page', 'popup', 'touch', 'wap']

prompt instance-attribute 

prompt: Literal[
    "none", "login", "consent", "select_account"
]

max_age instance-attribute 

max_age: int

ui_locales instance-attribute 

ui_locales: str

id_token_hint instance-attribute 

id_token_hint: str

login_hint instance-attribute 

login_hint: str

acr_values instance-attribute 

acr_values: str

response_mode instance-attribute 

response_mode: Literal['query', 'fragment', 'form_post']

OIDCFactorBase 

OIDCFactorBase(
    *,
    identifier: str,
    client_id: str,
    discovery_endpoint: str,
    state_service: OAuth2StateService,
    step: int = 0,
    advance_by: int = 1,
)

Bases: OAuth2Factor[OIDCExtraParams], ABC

Base OpenID Connect factor implementation.

This class implements the core OIDC flow using the discovery document and JWKS for ID Token validation.

Subclasses must implement get_request_authentication() to authenticate the token request. For the common static client_secret case, use the OIDCFactor subclass, which handles client_secret_basic/client_secret_post.

References
  • OpenID Connect Core 1.0: https://openid.net/specs/openid-connect-core-1_0.html

discovery_endpoint instance-attribute 

discovery_endpoint = discovery_endpoint

get_authorization_url async 

get_authorization_url(
    *,
    redirect_uri: str,
    scope: list[str] | None = None,
    state: str,
    code_challenge: str | None = None,
    code_challenge_method: CodeChallengeMethod
    | None = None,
    nonce: str | None = None,
    extra: OIDCExtraParams | None = None,
) -> str

exchange_code async 

exchange_code(
    *,
    code: str,
    redirect_uri: str,
    code_verifier: str | None = None,
    nonce: str | None = None,
    state: OAuth2State,
) -> TokenResponse

get_id_token_claims async 

get_id_token_claims(id_token: str) -> dict[str, typing.Any]

Decode and return claims from an ID Token JWT.

This method validates and decodes the id_token JWT, returning the claims. It's intended for providers like Apple that don't support userinfo endpoint.

Parameters:

Name Type Description Default
id_token str

The OIDC ID Token JWT string.

 required

Returns:

Type Description
dict[str, Any]

dict[str, Any]: The decoded JWT claims/payload.

get_profile async 

get_profile(access_token: str) -> dict[str, typing.Any]

Get identity claims from provider via userinfo endpoint.

For OIDC providers that support the userinfo endpoint.

Parameters:

Name Type Description Default
access_token str

The OAuth2 access token for making authenticated requests.

 required

Returns:

Type Description
dict[str, Any]

dict[str, Any]: Provider-specific profile claims.

Raises:

Type Description
NotImplementedError

If provider has no userinfo endpoint.
OAuth2GetProfileException

If fetching the profile fails.

OIDCFactor 

OIDCFactor(
    *,
    identifier: str,
    client_id: str,
    client_secret: str,
    discovery_endpoint: str,
    state_service: OAuth2StateService,
    step: int = 0,
    advance_by: int = 1,
)

Bases: OIDCFactorBase

OpenID Connect factor implementation with a static client secret.

Authenticates with a fixed client secret provided at instantiation, using client_secret_post or client_secret_basic depending on what the provider advertises in its discovery document. Use this for most OAuth providers.

For providers requiring dynamic credentials (e.g., Apple Sign In), subclass OIDCFactorBase directly and override get_request_authentication().

get_request_authentication async 

get_request_authentication(
    *, token_endpoint: str
) -> tuple[dict[str, str], dict[str, str]]

PrivateKeyJWTOIDCFactor 

PrivateKeyJWTOIDCFactor(
    *,
    identifier: str,
    client_id: str,
    signer: Signer,
    discovery_endpoint: str,
    state_service: OAuth2StateService,
    assertion_lifetime: int = 60,
    step: int = 0,
    advance_by: int = 1,
)

Bases: OIDCFactorBase

OpenID Connect factor authenticating with private_key_jwt (RFC 7523).

Signs a short-lived client assertion JWT for each token exchange with signer, instead of sending a shared client secret. The matching public key must be registered with the provider (usually via a JWKS URL). Rotating keys is a matter of publishing the new public key and pointing the signer at its private counterpart (OIDC Core §10.1.1).

The provider must advertise private_key_jwt in its token_endpoint_auth_methods_supported.

get_request_authentication async 

get_request_authentication(
    *, token_endpoint: str
) -> tuple[dict[str, str], dict[str, str]]

build_client_assertion 

build_client_assertion(
    *,
    client_id: str,
    token_endpoint: str,
    signer: Signer,
    lifetime: int = 60,
) -> str

Build a signed client assertion JWT for private_key_jwt authentication.

Implements the JWT profile for OAuth2 client authentication (RFC 7523): the client proves its identity to the token endpoint with a short-lived JWT signed by its private key, instead of sending a shared secret.

The signer advertises its key ID in the JOSE header, as required for verification against a multi-key JWKS (OIDC Core §10.1), and names the signing algorithm. The JWS is assembled here rather than by PyJWT, so a signer that never releases the private key can serve this path.

Parameters:

Name Type Description Default
client_id str

The OAuth2 client identifier, used as both iss and sub.

 required
token_endpoint str

The token endpoint URL, used as the aud.

 required
signer Signer

Signs the assertion. Its public counterpart must be published at the client's jwks_uri.

 required
lifetime int

The assertion validity in seconds.

 60

Returns:

Type Description
str

The signed client assertion JWT.

validate_id_token 

validate_id_token(
    id_token: str,
    jwks: PyJWKSet,
    *,
    issuer: str,
    client_id: str,
    id_token_signing_alg_values_supported: list[str],
    nonce: str | None = None,
    access_token: str | None = None,
) -> dict[str, typing.Any]

Validate an OpenID Connect ID Token.

This is a synchronous function that validates all aspects of an ID Token. All required data (discovery document info, JWKS) must be passed as arguments.

Validates: - JWT structure (3 parts) - Required claims: iss, sub, aud, exp, iat - Signature (using the JWK from JWKS matching the kid in the header) - Nonce (if provided) - at_hash (if access_token provided) - Audience matches expected audience - Issuer matches expected issuer - Token not expired

Parameters:

Name Type Description Default
id_token str

The ID Token JWT string.

 required
jwks PyJWKSet

The JWKS containing the signing keys.

 required
issuer str

The expected issuer from the discovery document.

 required
client_id str

The expected audience (client_id).

 required
id_token_signing_alg_values_supported list[str]

List of supported signing algorithms.

 required
nonce str | None

Expected nonce value for replay attack protection (optional).

 None
access_token str | None

Access token for at_hash validation (optional).

 None

Returns:

Type Description
dict[str, Any]

The decoded payload as a dictionary.

Raises:

Type Description
InvalidIDTokenException

If the token is invalid.