mantelo.connection

Classes

Connection	A base class for all connections.
Token	A wrapper around a Keycloak token response.
OpenidConnection	A base class for OpenID connections.
UsernamePasswordConnection	An OpenidConnection using username and password for authentication.
ClientCredentialsConnection	An OpenidConnection using client credentials for authentication.

Module Contents

class mantelo.connection.Connection

Bases: abc.ABC

A base class for all connections.

A connection only requires a method to generate a token. This is the base class used for all connections.

abstractmethod token() → str

Return a token usable in a Bearer authentication header. See also BearerAuth.

Returns:

A valid token.

Raises:

• AuthenticationException – If Keycloak returns a 401 when getting a token.

• requests.RequestException – If the request to Keycloak fails with other non-2XX status codes.

class mantelo.connection.Token

A wrapper around a Keycloak token response.

This class holds a token and its metadata, as returned by Keycloak. A token should at least have an access_token and an expires_in field. Optionally, a refresh_token and refresh_expires_in can be provided.

access_token: str

The token to use for authentication.

expires_in: int

The number of seconds (from created_at) the token is valid.

scope: str | None = None

The scope of the token (e.g. “openid”).

token_type: str | None = None

The type of the token (e.g. “Bearer”).

refresh_token: str | None = None

The token to use to refresh the access token.

refresh_expires_in: int | None = None

The number of seconds (from created_at) the refresh token is valid.

created_at: datetime.datetime

The time at which the token was created.

__attrs_post_init__() → None

property expires_at: datetime.datetime

Getter:

The time at which the token expires.

Type:

datetime

property refresh_expires_at: datetime.datetime | None

Getter:

The time at which the refresh token expires, or None if no refresh token is set.

has_refresh_token(_now: collections.abc.Callable[[], datetime.datetime] = _utcnow) → bool

Check if a refresh token exists and is still valid.

Returns:

True if a refresh token exists and is still valid.

classmethod from_dict(data: dict, now: datetime.datetime | None = None) → Token

Instantiate a Token from a dictionary, as returned by Keycloak.

class mantelo.connection.OpenidConnection

Bases: Connection, abc.ABC

A base class for OpenID connections.

This class handles the fetching and refreshing of a token using the well-known OpenId token endpoint. The payload data to send when fetching a token must be defined in the subclasses (_token_exchange_data method).

Parameters:

• server_url (str) – The URL of the Keycloak server (e.g. “https://my-keycloak.com”).

• realm_name (str) – The name of the realm used for authentication.

• client_id (str) – The client ID used for authentication (e.g. “admin-cli”).

• session (requests.Session, optional) – An optional session to use for authentication requests.

• refresh_timeout (timedelta, optional) – The amount of seconds a token is guaranteed to be valid.

server_url: str

The URL of the Keycloak server.

realm_name: str

The name of the realm used for authentication.

client_id: str

The client name used for authentication (e.g. “admin-cli”).

session: requests.Session

The session to use for authentication requests.

refresh_timeout: datetime.timedelta

The amount of seconds a token is guaranteed to be valid. If the existing token expires in less than this amount of time, it will be refreshed (or a new token will be fetched).

property auth_url: str

Getter:

The URL to use for authentication requests (e.g. “”https://my-keycloak.com/realms/my-realm/protocol/openid-connect/token”).

token(_now: collections.abc.Callable[[], datetime.datetime] = _utcnow) → str

Get a valid token guaranteed to be valid for at least refresh_timeout seconds. If no valid token exists, it first tries to use the refresh token, and falls back to fetching a new token.

Returns:

A valid access token.

class mantelo.connection.UsernamePasswordConnection

Bases: OpenidConnection

An OpenidConnection using username and password for authentication. It requests a token using the “password” grant type. The user should have the permissions necessary to access the Admin REST API endpoints.

Parameters:

• server_url (str) – The URL of the Keycloak server (e.g. “https://my-keycloak.com”).

• realm_name (str) – The name of the realm used for authentication.

• client_id (str) – The client ID used for authentication (e.g. “admin-cli”).

• username (str) – The username to use for authentication.

• password (str) – The password to use for authentication.

• session (requests.Session, optional) – An optional session to use for authentication requests.

• refresh_timeout (timedelta, optional) – The amount of seconds a token is guaranteed to be valid.

username: str

The username to use for authentication.

password: str

The password to use for authentication.

class mantelo.connection.ClientCredentialsConnection

Bases: OpenidConnection

An OpenidConnection using client credentials for authentication. It requests a token using the “client_credentials” grant type.

To access the Admin REST API, the client should: - have “Client authentication” enabled, - support the Service accounts roles authentication flow, - have one or more service account roles granting access to Admin endpoints.

Parameters:

• server_url (str) – The URL of the Keycloak server (e.g. “https://my-keycloak.com”).

• realm_name (str) – The name of the realm used for authentication.

• client_id (str) – The client ID used for authentication (e.g. “admin-cli”).

• client_secret (str) – The client secret to use for authentication.

• session (requests.Session, optional) – An optional session to use for authentication requests.

• refresh_timeout (timedelta, optional) – The amount of seconds a token is guaranteed to be valid.

client_secret: str

The client secret to use for authentication.