OIDCService

class gafaelfawr.services.oidc.OIDCService(*, config, token_lifetime, authorization_store, client_store, token_service, user_info_service, slack_client=None, session, logger)

Bases: object

Minimalist OpenID Connect identity provider.

This provides just enough of the OpenID Connect protocol to satisfy Chronograf (and possibly some other applications). It is the underlying implementation of the /auth/openid routes.

Parameters:

• config (OIDCServerConfig) – OpenID Connect server configuration.

• token_lifetime (timedelta) – Token lifetime for ID tokens if the underlying Gafaelfawr token does not have an expiration.

• authorization_store (OIDCAuthorizationStore) – The underlying storage for OpenID Connect authorizations.

• token_service (TokenService) – Token manipulation service.

• user_info_service (UserInfoService) – User information service.

• slack_client (Optional[SlackWebhookClient], default: None) – If provided, a Slack webhook client to use to report corruption of the underlying Redis store.

• session (AsyncSession) – Database session.

• logger (BoundLogger) – Logger for diagnostics.

Notes

Expects the following flow:

1. User is sent to /auth/openid/login for initial authentication.

2. User is redirected back to the application with an authorization code.

3. Application submits code to /auth/openid/token.

4. Application receives an access token and an ID token (the same).

5. Application gets user information from /auth/openid/userinfo.

The handler code is responsible for parsing the requests from the user. This object creates the authorization code (with its associated Redis entry) for step 2, and then returns the token for that code in step 4.

Parameters:

client_store (OIDCClientStore)

Methods Summary

delete_all_codes()	Invalidate all issued OpenID Connect codes.
delete_client(auth_data, client_id)	Delete a registered OpenID Connect client.
get_client(auth_data, client_id)	Get the metadata for a registered OpenID Connect client.
get_jwks()	Return the key set for the OpenID Connect server.
get_openid_configuration()	Return the OpenID Connect configuration for the internal server.
issue_code(*, client_id, redirect_uri, ...)	Issue a new authorization code.
issue_id_token(authorization)	Issue an OpenID Connect token.
list_clients(auth_data)	List all registered OpenID Connect clients.
migrate_clients(clients)	Migrate clients from the old configuration into the database.
redeem_code(*, grant_type, client_id, ...)	Redeem an authorization code.
register_client(auth_data, request)	Register a new OpenID Connect client.
token_to_userinfo_claims(token_data)	Generate OpenID Connect userinfo claims from a Gafaelfawr token.
update_client(auth_data, client_id, update)	Get the metadata for a registered OpenID Connect client.
validate_client(client_id, redirect_uri)	Check that the provided client and redirect URI are valid.
verify_token(token)	Verify a token issued by the internal OpenID Connect server.

Methods Documentation

async delete_all_codes()

Invalidate all issued OpenID Connect codes.

Return type:

None

async delete_client(auth_data, client_id)

Delete a registered OpenID Connect client.

Parameters:

• auth_data (TokenData) – Token information for the person requesting this client.

• client_id (str) – Identifier of the client.

Raises:

NotFoundError – Raised if the client could not be found.

Return type:

None

async get_client(auth_data, client_id)

Get the metadata for a registered OpenID Connect client.

Parameters:

• auth_data (TokenData) – Token information for the person requesting this client.

• client_id (str) – Identifier of the client.

Returns:

The registered OpenID Connect client.

Return type:

OIDCClient

Raises:

NotFoundError – Raised if the client could not be found.

get_jwks()

Return the key set for the OpenID Connect server.

Return type:

JWKS

get_openid_configuration()

Return the OpenID Connect configuration for the internal server.

Return type:

OIDCConfig

async issue_code(*, client_id, redirect_uri, token, scopes, nonce=None)

Issue a new authorization code.

Parameters:

• client_id (str) – Client ID with access to this authorization.

• redirect_uri (str) – Intended return URI for this authorization.

• token (Token) – Underlying authentication token.

• scopes (Sequence[OIDCScope]) – Requested scopes.

• nonce (Optional[str], default: None) – Client-provided nonce.

Returns:

The code for a newly-created and stored authorization.

Return type:

OIDCAuthorizationCode

Raises:

• InvalidClientIdError – Raised if the provided client ID is not registered as an OpenID Connect client.

• ReturnUriMismatchError – Raised if the provided redirect URI does not match the one registered for this client.

async issue_id_token(authorization)

Issue an OpenID Connect token.

This creates a new OpenID Connect token with data taken from the internal Gafaelfawr token.

Parameters:

authorization (OIDCAuthorization) – Authorization code used to request a token.

Returns:

The new token.

Return type:

OIDCVerifiedToken

Raises:

InvalidGrantError – Raised if the underlying authorization or session does not exist.

async list_clients(auth_data)

List all registered OpenID Connect clients.

Parameters:

auth_data (TokenData) – Token information for the person requesting the client list.

Returns:

List of registered OpenID Connect clients.

Return type:

list of OIDCClient

async migrate_clients(clients)

Migrate clients from the old configuration into the database.

Parameters:

clients (list[OIDCClientConfig]) – Clients to migrate.

Return type:

None

async redeem_code(*, grant_type, client_id, client_secret, redirect_uri, code, ip_address)

Redeem an authorization code.

None of the parameters may be None in practice, but None is accepted and rejected wih an exception so that error handling can be unified.

Parameters:

• grant_type (Optional[str]) – Type of token grant requested.

• client_id (Optional[str]) – Client ID of the OpenID Connect client.

• client_secret (Optional[str]) – Secret for that client. A secret of None will never be valid, but is accepted so that error handling can be unified.

• redirect_uri (Optional[str]) – The return URI of the OpenID Connect client.

• code (Optional[str]) – The OpenID Connect authorization code.

• ip_address (str)

Returns:

The token reply to send to the user.

Return type:

OIDCTokenReply

Raises:

• InvalidClientError – Raised if the client ID is not known or the client secret does not match the client ID.

• InvalidGrantError – Raised if the code is not valid, the client is not allowed to use it, or the underlying authorization or session does not exist.

• InvalidRequestError – Raised if the token redemption request is syntactically invalid.

• UnsupportedGrantTypeError – Raised if the requested grant type isn’t supported.

async register_client(auth_data, request)

Register a new OpenID Connect client.

Parameters:

• auth_data (TokenData) – Token information for the person adding this client.

• request (OIDCClientUpdate) – OpenID Connect client information.

Return type:

OIDCClientWithSecret

async token_to_userinfo_claims(token_data)

Generate OpenID Connect userinfo claims from a Gafaelfawr token.

Parameters:

token_data (TokenData) – User and token metadata.

Return type:

dict[str, Any]

async update_client(auth_data, client_id, update)

Get the metadata for a registered OpenID Connect client.

Parameters:

• auth_data (TokenData) – Token information for the person requesting this client.

• client_id (str) – Identifier of the client.

• update (OIDCClientUpdate) – Updated information to replace in the client metadata.

Returns:

The updated OpenID Connect client.

Return type:

OIDCClient

Raises:

NotFoundError – Raised if the client could not be found.

async validate_client(client_id, redirect_uri)

Check that the provided client and redirect URI are valid.

Raises exceptions on any errors.

Parameters:

• client_id (str) – ID of client.

• redirect_uri (str) – URL to redirect to after authentication.

Raises:

• InvalidClientIdError – Raised if the provided client ID is unknown.

• ReturnUriMismatchError – Raised if the provided return URI doesn’t match the one registered with the client.

Return type:

None

async verify_token(token)

Verify a token issued by the internal OpenID Connect server.

Any currently-registered client audience is accepted as a valid audience.

Parameters:

token (OIDCToken) – An encoded token.

Returns:

The verified token.

Return type:

OIDCVerifiedToken

Raises:

InvalidTokenError – The issuer of this token is unknown and therefore the token cannot be verified.