API Reference

federatedidentity

ANY_AUDIENCE module-attribute

ANY_AUDIENCE = cast(AnyAudienceType, object())

Special value which can be passed as the valid_audiences parameter to verify_id_token which matches any audience.

ClaimVerifier module-attribute

ClaimVerifier = Union[
    dict[str, Any], Callable[[dict[str, Any]], None]
]

Type representing a claim verifier. A claim verifier may be a dictionary of acceptable claim values or a callable which takes the claims dictionary. A claims verifier callable should raise InvalidClaimsError if the claims do not match the expected values.

Issuer dataclass

Represents an issuer of OIDC id tokens.

name instance-attribute

name: str

Name of the issuer as it appears in iss claims.

key_set instance-attribute

key_set: JWKSet

JWK key set associated with the issuer used to verify JWT signatures.

from_discovery classmethod

from_discovery(
    name: str, request: Optional[RequestBase] = None
) -> Issuer

Initialise an issuer fetching key sets as per OpenID Connect Discovery.

Parameters:

Name	Type	Description	Default
name	str	The name of the issuer as it would appear in the "iss" claim of a token	required
request	Optional[RequestBase]	An optional HTTP request callable. If omitted a default implementation based on the requests module is used.	None

Returns:

Type	Description
Issuer	a newly-created issuer

Raises:

Type	Description
FederatedIdentityError	The issuer's keys could not be discovered.

async_from_discovery async classmethod

async_from_discovery(
    name: str, request: Optional[AsyncRequestBase] = None
) -> Issuer

Initialise an issuer fetching key sets as per OpenID Connect Discovery.

Parameters:

Name	Type	Description	Default
name	str	The name of the issuer as it would appear in the "iss" claim of a token	required
request	Optional[AsyncRequestBase]	An optional asynchronous HTTP request callable. If omitted a default implementation based on the requests module is used.	None

Returns:

Type	Description
Issuer	a newly-created issuer

Raises:

Type	Description
FederatedIdentityError	The issuer's keys could not be discovered.

verify_id_token

verify_id_token(
    token: Union[str, bytes],
    valid_issuers: Iterable[Issuer],
    valid_audiences: Iterable[Union[str, AnyAudienceType]],
    *,
    required_claims: Optional[
        Iterable[ClaimVerifier]
    ] = None
) -> dict[str, Any]

Verify an OIDC identity token.

Returns:

Type	Description
dict[str, Any]	the token's claims dictionary.

Parameters:

Name	Type	Description	Default
token	Union[str, bytes]	OIDC token to verify. If a bytes object is passed it is decoded using the ASCII codec before verification.	required
valid_issuers	Iterable[Issuer]	Iterable of valid issuers. At least one Issuer must match the token issuer for verification to succeed.	required
valid_audiences	Iterable[Union[str, AnyAudienceType]]	Iterable of valid audiences. At least one audience must match the aud claim for verification to succeed. An audience is either a literal string or a callable which takes an audience and returns True if it is valid.	required
required_claims	Optional[Iterable[ClaimVerifier]]	Iterable of required claim verifiers. Claims are passed to verifiers after the token's signature has been verified. Claims required by OIDC are always validated. All claim verifiers must pass for verification to succeed.	None

Raises:

Type	Description
FederatedIdentityError	The token failed verification.
UnicodeDecodeError	The token could not be decoded into an ASCII string.