API

Flask-pyoidc extension

class flask_pyoidc.OIDCAuthentication(provider_configurations, app=None, redirect_uri_config=None)

OIDCAuthentication object for Flask extension.

Parameters:
  • provider_configurations (Mapping[str, ProviderConfiguration]) – provider configurations by name
  • app (flask.app.Flask) – optional Flask app
  • redirect_uri_config (RedirectUriConfig) – optional redirect URI config to use instead of ‘OIDC_REDIRECT_URI’ config parameter.
valid_access_token(force_refresh=False)

Returns a valid access token.

  1. If the current access token in the user session is valid, return that.
  2. If the current access token has expired and there is a refresh token in the user session, make a refresh token request and return the new access token.
  3. If the token refresh fails, either due to missing refresh token or token error response, return None.
Parameters:force_refresh (bool) – whether to perform the refresh token request even if the current access token is valid
Returns:valid access token
Return type:Option[str]

Configuration

class flask_pyoidc.provider_configuration.ClientMetadata(client_id=None, client_secret=None, **kwargs)
class flask_pyoidc.provider_configuration.ClientRegistrationInfo(*args, **kwargs)
Parameters:
  • args (List[Tuple[String, String]]) – key-value pairs to store
  • kwargs (Dict[string, string]) – key-value pairs to store
class flask_pyoidc.provider_configuration.OIDCData(*args, **kwargs)

Basic OIDC data representation providing validation of required fields.

Parameters:
  • args (List[Tuple[String, String]]) – key-value pairs to store
  • kwargs (Dict[string, string]) – key-value pairs to store
class flask_pyoidc.provider_configuration.ProviderConfiguration(issuer=None, provider_metadata=None, userinfo_http_method='GET', client_registration_info=None, client_metadata=None, auth_request_params=None, session_refresh_interval_seconds=None, requests_session=None)

Metadata for communicating with an OpenID Connect Provider (OP).

auth_request_params

Extra parameters, as key-value pairs, to include in the query parameters of the authentication request

Type:dict
registered_client_metadata

The client metadata registered with the provider.

Type:ClientMetadata
requests_session

Requests object to use when communicating with the provider.

Type:requests.Session
session_refresh_interval_seconds

Number of seconds between updates of user data (tokens, user data, etc.) fetched from the provider. If None is specified, no silent updates should be made user data will be made.

Type:int
userinfo_endpoint_method

HTTP method (“GET” or “POST”) to use when making the UserInfo Request. If None is specifed, no UserInfo Request will be made.

Type:str
Parameters:
  • issuer (str) – OP Issuer Identifier. If this is specified discovery will be used to fetch the provider metadata, otherwise provider_metadata must be specified.
  • provider_metadata (ProviderMetadata) – OP metadata,
  • userinfo_http_method (Optional[str]) – HTTP method (GET or POST) to use when sending the UserInfo Request. If none is specified, no userinfo request will be sent.
  • client_registration_info (ClientRegistrationInfo) – Client metadata to register your app dynamically with the provider. Either this or registered_client_metadata must be specified.
  • client_metadata (ClientMetadata) – Client metadata if your app is statically registered with the provider. Either this or client_registration_info must be specified.
  • auth_request_params (dict) – Extra parameters that should be included in the authentication request.
  • session_refresh_interval_seconds (int) – Length of interval (in seconds) between attempted user data refreshes.
  • requests_session (requests.Session) – custom requests object to allow for example retry handling, etc.
class flask_pyoidc.provider_configuration.ProviderMetadata(issuer=None, authorization_endpoint=None, jwks_uri=None, **kwargs)

User session handling

exception flask_pyoidc.user_session.UninitialisedSession
class flask_pyoidc.user_session.UserSession(session_storage, provider_name=None)

Session object for user login state.

Wraps comparison of times necessary for session handling.

is_authenticated()

flask_session is empty when the session hasn’t been initialised or has expired. Thus checking for existence of any item is enough to determine if we’re authenticated.

update(*, access_token=None, expires_in=None, id_token=None, id_token_jwt=None, userinfo=None, refresh_token=None)
Parameters:
  • access_token (str) –
  • expires_in (int) –
  • id_token (Mapping[str, str]) –
  • id_token_jwt (str) –
  • userinfo (Mapping[str, str]) –

Internals

exception flask_pyoidc.auth_response_handler.AuthResponseErrorResponseError(error_response)
Parameters:error_response (Mapping[str, str]) – OAuth error response containing ‘error’ and ‘error_description’
exception flask_pyoidc.auth_response_handler.AuthResponseMismatchingSubjectError
exception flask_pyoidc.auth_response_handler.AuthResponseProcessError
exception flask_pyoidc.auth_response_handler.AuthResponseUnexpectedStateError
class flask_pyoidc.auth_response_handler.AuthenticationResult(access_token, expires_in, id_token_claims, id_token_jwt, userinfo_claims, refresh_token)

Create new instance of AuthenticationResult(access_token, expires_in, id_token_claims, id_token_jwt, userinfo_claims, refresh_token)

access_token

Alias for field number 0

expires_in

Alias for field number 1

id_token_claims

Alias for field number 2

id_token_jwt

Alias for field number 3

refresh_token

Alias for field number 5

userinfo_claims

Alias for field number 4

exception flask_pyoidc.auth_response_handler.InvalidIdTokenError
class flask_pyoidc.pyoidc_facade.PyoidcFacade(provider_configuration, redirect_uri)

Wrapper around pyoidc library, coupled with config for a simplified API for flask-pyoidc.

Parameters:provider_configuration (flask_pyoidc.provider_configuration.ProviderConfiguration) –
authentication_request(state, nonce, extra_auth_params)
Parameters:
  • state (str) – authentication request parameter ‘state’
  • nonce (str) – authentication request parameter ‘nonce’
  • extra_auth_params (Mapping[str, str]) – extra authentication request parameters
Returns:

the authentication request

Return type:

AuthorizationRequest

exchange_authorization_code(authorization_code)

Requests tokens from an authorization code.

Parameters:authorization_code (str) – authorization code issued to client after user authorization
Returns:The parsed token response, or None if no token request was performed.
Return type:Union[AccessTokenResponse, TokenErrorResponse, None]
login_url(auth_request)
Parameters:auth_request (AuthorizationRequest) – authenticatio request
Returns:Authentication request as a URL to redirect the user to the provider.
Return type:str
parse_authentication_response(response_params)
Parameters:response_params (Mapping[str, str]) – authentication response parameters
Returns:The parsed authorization response
Return type:Union[AuthorizationResponse, AuthorizationErrorResponse]
refresh_token(refresh_token)

Requests new tokens using a refresh token.

Parameters:refresh_token (str) – refresh token issued to client after user authorization
Returns:The parsed token response, or None if no token request was performed.
Return type:Union[AccessTokenResponse, TokenErrorResponse, None]
userinfo_request(access_token)
Parameters:access_token (str) – Bearer access token to use when fetching userinfo
Returns:UserInfo Response
Return type:oic.oic.message.OpenIDSchema
verify_id_token(id_token, auth_request)

Verifies the ID Token.

Parameters:
  • id_token (Mapping[str, str]) – ID token claims
  • auth_request (Mapping[str, str]) – original authentication request parameters to validate against (nonce, acr_values, max_age, etc.)
Raises:

PyoidcError – If the ID token is invalid.