simple_openid_connect.client#

A more contiguous client implementation of the Openid-Connect protocol that offers simpler APIs at the cost of losing some flexibility.

Classes

OpenidClient(provider_config, provider_keys, ...)

A more contiguous client implementation of the Openid-Connect protocol that offers simpler APIs at the cost of losing some flexibility.
class simple_openid_connect.client.OpenidClient(provider_config: ProviderMetadata, provider_keys: List[JWK], authentication_redirect_uri: str | None, client_id: str, client_secret: str | None = None, scope: str = 'openid')#

A more contiguous client implementation of the Openid-Connect protocol that offers simpler APIs at the cost of losing some flexibility.

__init__(provider_config: ProviderMetadata, provider_keys: List[JWK], authentication_redirect_uri: str | None, client_id: str, client_secret: str | None = None, scope: str = 'openid')#
authorization_code_flow: AuthorizationCodeFlowClient#

authorization code flow related functionality

client_credentials_grant: ClientCredentialsGrantClient#

Client Credentials Grant (or Service Account Authentication) functionality

property client_type: Literal['public', 'confidential']#

Which type of client behavior is used.

This is based on whether a client secret has been passed during client construction

decode_id_token(raw_token: str, nonce: str | None = None, extra_trusted_audiences: List[str] = [], min_iat: float = 0, validate_acr: Callable[[str], None] | None = None, min_auth_time: float = 0) → IdToken#

Decode and verify an encoded and signed id token.

Issuer and client id for validation are taken from the client configuration but extra optional validation information can be supplied as well.

Parameters:

  • raw_token – The encoded and signed id token. This could e.g. be retrieved as part of the authentication process and returned by the OP in TokenSuccessResponse.id_token.

  • nonce – The nonce that was used during authentication. It is carried over by the OP into ID-Tokens and must now match.

  • extra_trusted_audiences – Which token audiences (client ids) to consider trusted beside this client’s own client_id. This is usually an empty list but if the token is intended to be used by more than one client, all of these need to be listed in the tokens IdToken.aud field, and they all need to be known and trusted by this client.

  • min_iat – Minimum value that the tokens IdToken.iat claim must be. This value is a posix timestamp and defaults to 0 which allows arbitrarily old iat dates.

  • validate_acr – A callable that receives this tokens IdToken.acr value and must perform its own validation. This is necessary because the value of acr is outside OpenId-Connect specification and usage specific. If not given, acr is assumed to always be valid.

  • min_auth_time – The point in time which is considered the minimum at which a user should have authenticated. It basically means that if the user was authenticated very far in the past and reused their session, the time at which the original authentication took place must be greater than this value. This is only validated if the IdToken.auth_time is present in the token. This value is a posix timestamp and default to 0 which allows arbitrarily old auth_time dates.

Raises:

ValidationError – if the validation fails

direct_access_grant: DirectAccessGrantClient#

Direct Access Grant (or Resource Owner Password Credentials Grant) functionality

exchange_refresh_token(refresh_token: str) → TokenSuccessResponse | TokenErrorResponse#

Exchange a refresh token for new tokens

Parameters:

refresh_token – The refresh token to use

Raises:

UnsupportedByProviderError – If the provider only supports implicit flow and has no token endpoint.

fetch_userinfo(access_token: str) → UserinfoSuccessResponse | UserinfoErrorResponse#

Fetch user information from the OP by doing a userinfo request.

Which users information is fetched is determined by the OP directly from the used access token.

Parameters:

access_token – An access token which grants access to user information.

Raises:

UnsupportedByProviderError – If the provider does not support userinfo requests or the userinfo endpoint is not known.

Returns:

The OPs response

classmethod from_issuer_config(config: ProviderMetadata, authentication_redirect_uri: str | None, client_id: str, client_secret: str | None = None, scope: str = 'openid') → Self#

Create a new client instance with a resolved issuer configuration as base.

If you don’t have a configuration, use from_issuer_url() to automatically retrieve it.

Parameters:

  • config – The configuration of the used issuer.

  • authentication_redirect_uri – URI that is used during the authentication flow to redirect back to this application.

  • client_id – The already known client id of your application. It must be already registered with the issuer.

  • client_secret – Optionally a client secret which has been assigned to your client from the issuer. If not supplied, this client is assumed to be public which means it has not client secret because it cannot be kept safe (e.g. a web-app).

  • scope – Which scopes to request from the OP

classmethod from_issuer_url(url: str, authentication_redirect_uri: str | None, client_id: str, client_secret: str | None = None, scope: str = 'openid') → Self#

Create a new client instance with an issuer url as base, automatically discovering information about the issuer in the process.

Parameters:

  • url – The url to an Openid issuer

  • authentication_redirect_uri – URI that is used during the authentication flow to redirect back to this application.

  • client_id – The already known client id of your application. It must be already registered with the issuer.

  • client_secret – Optionally a client secret which has been assigned to your client from the issuer. If not supplied, this client is assumed to be public which means it has not client secret because it cannot be kept safe (e.g. a web-app).

  • scope – Which scopes to request from the OP

initiate_logout(request: RpInitiatedLogoutRequest | None = None) → str#

Initiate user logout as a Relying-Party

Parameters:

request – Additional data pertaining to the logout

Raises:

UnsupportedByProviderError – If the provider does not support Relying-Party-Initiated logout.

Returns:

A url to which the user should be redirected

introspect_token(token: str, token_type_hint: str | None = None) → TokenIntrospectionSuccessResponse | TokenIntrospectionErrorResponse#

Introspect the given token at the OP.

Parameters:

  • token – The token to introspect.

  • token_type_hint – Which type of token this is e.g. refresh_token or access_token.

Raises:

UnsupportedByProviderError – If the provider does not support token introspection.

Returns:

The OPs response