mantelo.connection ================== .. py:module:: mantelo.connection Classes ------- .. autoapisummary:: mantelo.connection.Connection mantelo.connection.Token mantelo.connection.OpenidConnection mantelo.connection.UsernamePasswordConnection mantelo.connection.ClientCredentialsConnection Module Contents --------------- .. py:class:: Connection Bases: :py:obj:`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. .. py:method:: token() -> str :abstractmethod: Return a token usable in a Bearer authentication header. See also :class:`~.BearerAuth`. :return: A valid token. :raises AuthenticationException: If Keycloak returns a 401 when getting a token. :raises requests.RequestException: If the request to Keycloak fails with other non-2XX status codes. .. py:class:: 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. .. py:attribute:: access_token :type: str The token to use for authentication. .. py:attribute:: expires_in :type: int The number of seconds (from `created_at`) the token is valid. .. py:attribute:: scope :type: str | None :value: None The scope of the token (e.g. "openid"). .. py:attribute:: token_type :type: str | None :value: None The type of the token (e.g. "Bearer"). .. py:attribute:: refresh_token :type: str | None :value: None The token to use to refresh the access token. .. py:attribute:: refresh_expires_in :type: int | None :value: None The number of seconds (from `created_at`) the refresh token is valid. .. py:attribute:: created_at :type: datetime.datetime The time at which the token was created. .. py:method:: __attrs_post_init__() -> None .. py:property:: expires_at :type: datetime.datetime :getter: The time at which the token expires. :type: datetime .. py:property:: refresh_expires_at :type: datetime.datetime | None :getter: The time at which the refresh token expires, or None if no refresh token is set. .. py:method:: has_refresh_token(_now: collections.abc.Callable[[], datetime.datetime] = _utcnow) -> bool Check if a refresh token exists and is still valid. :return: True if a refresh token exists and is still valid. .. py:method:: from_dict(data: dict, now: datetime.datetime | None = None) -> Token :classmethod: Instantiate a :class:`~.Token` from a dictionary, as returned by Keycloak. .. py:class:: OpenidConnection Bases: :py:obj:`Connection`, :py:obj:`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). :param server_url: The URL of the Keycloak server (e.g. "https://my-keycloak.com"). :type server_url: str :param realm_name: The name of the realm used for authentication. :type realm_name: str :param client_id: The client ID used for authentication (e.g. "admin-cli"). :type client_id: str :param session: An optional session to use for authentication requests. :type session: requests.Session, optional :param refresh_timeout: The amount of seconds a token is guaranteed to be valid. :type refresh_timeout: timedelta, optional .. py:attribute:: server_url :type: str The URL of the Keycloak server. .. py:attribute:: realm_name :type: str The name of the realm used for authentication. .. py:attribute:: client_id :type: str The client name used for authentication (e.g. "admin-cli"). .. py:attribute:: session :type: requests.Session The session to use for authentication requests. .. py:attribute:: refresh_timeout :type: 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). .. py:property:: auth_url :type: str :getter: The URL to use for authentication requests (e.g. ""https://my-keycloak.com/realms/my-realm/protocol/openid-connect/token"). .. py:method:: 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. :return: A valid access token. .. py:class:: UsernamePasswordConnection Bases: :py:obj:`OpenidConnection` An :class:`~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. :param server_url: The URL of the Keycloak server (e.g. "https://my-keycloak.com"). :type server_url: str :param realm_name: The name of the realm used for authentication. :type realm_name: str :param client_id: The client ID used for authentication (e.g. "admin-cli"). :type client_id: str :param username: The username to use for authentication. :type username: str :param password: The password to use for authentication. :type password: str :param session: An optional session to use for authentication requests. :type session: requests.Session, optional :param refresh_timeout: The amount of seconds a token is guaranteed to be valid. :type refresh_timeout: timedelta, optional .. py:attribute:: username :type: str The username to use for authentication. .. py:attribute:: password :type: str The password to use for authentication. .. py:class:: ClientCredentialsConnection Bases: :py:obj:`OpenidConnection` An :class:`~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. :param server_url: The URL of the Keycloak server (e.g. "https://my-keycloak.com"). :type server_url: str :param realm_name: The name of the realm used for authentication. :type realm_name: str :param client_id: The client ID used for authentication (e.g. "admin-cli"). :type client_id: str :param client_secret: The client secret to use for authentication. :type client_secret: str :param session: An optional session to use for authentication requests. :type session: requests.Session, optional :param refresh_timeout: The amount of seconds a token is guaranteed to be valid. :type refresh_timeout: timedelta, optional .. py:attribute:: client_secret :type: str The client secret to use for authentication.