pypomes-iam 0.5.2__py3-none-any.whl → 0.6.2__py3-none-any.whl

pypomes_iam/iam_services.py

@@ -3,17 +3,102 @@ from flask import Request, Response, request, jsonify
 from logging import Logger
 from typing import Any
 
-from .iam_common import IamServer, _iam_lock, _iam_server_from_endpoint
-from .iam_pomes import (
-    user_login, user_logout,
-    user_token, token_exchange, login_callback
+from .iam_common import (
+    IamServer, IamParam, _iam_lock,
+    _get_iam_registry, _get_public_key,
+    _iam_server_from_endpoint, _iam_server_from_issuer
 )
+from .iam_actions import (
+    action_login, action_logout,
+    action_token, action_exchange, action_callback
+)
+from .token_pomes import token_get_claims, token_validate
 
 # the logger for IAM service operations
 # (used exclusively at the HTTP endpoints - all other functions receive the logger as parameter)
 __IAM_LOGGER: Logger | None = None
 
 
+def jwt_required(func: callable) -> callable:
+    """
+    Create a decorator to authenticate service endpoints with JWT tokens.
+
+    :param func: the function being decorated
+    """
+    # ruff: noqa: ANN003 - Missing type annotation for *{name}
+    def wrapper(*args, **kwargs) -> Response:
+        response: Response = __request_validate(request=request)
+        return response if response else func(*args, **kwargs)
+
+    # prevent a rogue error ("View function mapping is overwriting an existing endpoint function")
+    wrapper.__name__ = func.__name__
+
+    return wrapper
+
+
+def __request_validate(request: Request) -> Response:
+    """
+    Verify whether the HTTP *request* has the proper authorization, as per the JWT standard.
+
+    This implementation assumes that HTTP requests are handled with the *Flask* framework.
+    Because this code has a high usage frequency, only authentication failures are logged.
+
+    :param request: the *request* to be verified
+    :return: *None* if the *request* is valid, otherwise a *Response* reporting the error
+    """
+    # initialize the return variable
+    result: Response | None = None
+
+    # retrieve the authorization from the request header
+    auth_header: str = request.headers.get("Authorization")
+
+    # validate the authorization token
+    bad_token: bool = True
+    if auth_header and auth_header.startswith("Bearer "):
+        # extract and validate the JWT access token
+        token: str = auth_header.split(" ")[1]
+        claims: dict[str, Any] = token_get_claims(token=token)
+        if claims:
+            issuer: str = claims["payload"].get("iss")
+            recipient_attr: str | None = None
+            recipient_id: str = request.values.get("user-id") or request.values.get("login")
+            with _iam_lock:
+                iam_server: IamServer = _iam_server_from_issuer(issuer=issuer,
+                                                                errors=None,
+                                                                logger=__IAM_LOGGER)
+                if iam_server:
+                    # validate the token's recipient only if a user identification is provided
+                    if recipient_id:
+                        registry: dict[str, Any] = _get_iam_registry(iam_server=iam_server,
+                                                                     errors=None,
+                                                                     logger=__IAM_LOGGER)
+                        if registry:
+                            recipient_attr = registry[IamParam.RECIPIENT_ATTR]
+                    public_key: str = _get_public_key(iam_server=iam_server,
+                                                      errors=None,
+                                                      logger=__IAM_LOGGER)
+            # validate the token (log errors, only)
+            errors: list[str] = []
+            if public_key and token_validate(token=token,
+                                             issuer=issuer,
+                                             recipient_id=recipient_id,
+                                             recipient_attr=recipient_attr,
+                                             public_key=public_key,
+                                             errors=errors):
+                # token is valid
+                bad_token = False
+            elif __IAM_LOGGER:
+                __IAM_LOGGER.error("; ".join(errors))
+        if bad_token and __IAM_LOGGER:
+            __IAM_LOGGER.error(f"Authorization refused for token {token}")
+
+    # deny the authorization
+    if bad_token:
+        result = Response(response="Authorization failed",
+                          status=401)
+    return result
+
+
 def logger_register(logger: Logger) -> None:
     """
     Register the logger for HTTP services.
@@ -60,10 +145,10 @@ def service_login() -> Response:
                                                           logger=__IAM_LOGGER)
         if iam_server:
             # obtain the login URL
-            login_url: str = user_login(iam_server=iam_server,
-                                        args=request.args,
-                                        errors=errors,
-                                        logger=__IAM_LOGGER)
+            login_url: str = action_login(iam_server=iam_server,
+                                          args=request.args,
+                                          errors=errors,
+                                          logger=__IAM_LOGGER)
             if login_url:
                 result = jsonify({"login-url": login_url})
     if errors:
@@ -106,10 +191,10 @@ def service_logout() -> Response:
                                                           logger=__IAM_LOGGER)
         if iam_server:
             # logout the user
-            user_logout(iam_server=iam_server,
-                        args=request.args,
-                        errors=errors,
-                        logger=__IAM_LOGGER)
+            action_logout(iam_server=iam_server,
+                          args=request.args,
+                          errors=errors,
+                          logger=__IAM_LOGGER)
     if errors:
         result = Response(response="; ".join(errors),
                           status=400)
@@ -160,10 +245,10 @@ def service_callback() -> Response:
                                                           logger=__IAM_LOGGER)
         if iam_server:
             # process the callback operation
-            token_data = login_callback(iam_server=iam_server,
-                                        args=request.args,
-                                        errors=errors,
-                                        logger=__IAM_LOGGER)
+            token_data = action_callback(iam_server=iam_server,
+                                         args=request.args,
+                                         errors=errors,
+                                         logger=__IAM_LOGGER)
     result: Response
     if errors:
         result = jsonify({"errors": "; ".join(errors)})
@@ -171,9 +256,9 @@ def service_callback() -> Response:
     else:
         result = jsonify({"user-id": token_data[0],
                           "access-token": token_data[1]})
-    # log the response
     if __IAM_LOGGER:
-        __IAM_LOGGER.debug(msg=f"Response {result}, {result.get_data(as_text=True)}")
+        # log the response (the returned data is not logged, as it contains the token)
+        __IAM_LOGGER.debug(msg=f"Response {result}")
 
     return result
 
@@ -215,10 +300,10 @@ def service_token() -> Response:
             if iam_server:
                 # retrieve the token
                 errors: list[str] = []
-                token: str = user_token(iam_server=iam_server,
-                                        args=args,
-                                        errors=errors,
-                                        logger=__IAM_LOGGER)
+                token: str = action_token(iam_server=iam_server,
+                                          args=args,
+                                          errors=errors,
+                                          logger=__IAM_LOGGER)
     else:
         msg: str = "User identification not provided"
         errors.append(msg)
@@ -232,9 +317,9 @@ def service_token() -> Response:
     else:
         result = jsonify({"user-id": user_id,
                           "access-token": token})
-    # log the response
     if __IAM_LOGGER:
-        __IAM_LOGGER.debug(msg=f"Response {result}, {result.get_data(as_text=True)}")
+        # log the response (the returned data is not logged, as it contains the token)
+        __IAM_LOGGER.debug(msg=f"Response {result}")
 
     return result
 
@@ -278,10 +363,10 @@ def service_exchange() -> Response:
         token_data: dict[str, Any] | None = None
         if iam_server:
             errors: list[str] = []
-            token_data = token_exchange(iam_server=iam_server,
-                                        args=request.args,
-                                        errors=errors,
-                                        logger=__IAM_LOGGER)
+            token_data = action_exchange(iam_server=iam_server,
+                                         args=request.args,
+                                         errors=errors,
+                                         logger=__IAM_LOGGER)
     result: Response
     if errors:
         result = Response(response="; ".join(errors),

pypomes_iam/provider_pomes.py

@@ -3,29 +3,49 @@ import requests
 import sys
 from base64 import b64encode
 from datetime import datetime
+from enum import StrEnum
 from logging import Logger
 from pypomes_core import TZ_LOCAL, exc_format
-from threading import RLock
+from threading import Lock
 from typing import Any, Final
 
+
+class ProviderParam(StrEnum):
+    """
+    Parameters for configuring a *JWT* token provider.
+    """
+    URL = "url"
+    USER = "user"
+    PWD = "pwd"
+    CUSTOM_AUTH = "custom-auth"
+    HEADER_DATA = "headers-data"
+    BODY_DATA = "body-data"
+    ACCESS_TOKEN = "access-token"
+    ACCESS_EXPIRATION = "access-expiration"
+    REFRESH_TOKEN = "refresh-token"
+    REFRESH_EXPIRATION = "refresh-expiration"
+
+
 # structure:
 # {
 #    <provider-id>: {
 #      "url": <strl>,
 #      "user": <str>,
 #      "pwd": <str>,
-#      "basic-auth": <bool>,
+#      "custom-auth": <bool>,
 #      "headers-data": <dict[str, str]>,
 #      "body-data": <dict[str, str],
 #      "access-token": <str>,
-#      "access-expiration": <timestamp>
+#      "access-expiration": <timestamp>,
+#      "refresh-token": <str>,
+#      "refresh-expiration": <timestamp>
 #    }
 # }
 _provider_registry: Final[dict[str, dict[str, Any]]] = {}
 
 # the lock protecting the data in '_provider_registry'
 # (because it is 'Final' and set at declaration time, it can be accessed through simple imports)
-_provider_lock: Final[RLock] = RLock()
+_provider_lock: Final[Lock] = Lock()
 
 
 def provider_register(provider_id: str,
@@ -58,16 +78,16 @@ def provider_register(provider_id: str,
 
     with _provider_lock:
         _provider_registry[provider_id] = {
-            "url": auth_url,
-            "user": auth_user,
-            "pwd": auth_pwd,
-            "custom-auth": custom_auth,
-            "headers-data": headers_data,
-            "body-data": body_data,
-            "access-token": None,
-            "access-expiration": 0,
-            "refresh-token": None,
-            "refresh-expiration": 0
+            ProviderParam.URL: auth_url,
+            ProviderParam.USER: auth_user,
+            ProviderParam.PWD: auth_pwd,
+            ProviderParam.CUSTOM_AUTH: custom_auth,
+            ProviderParam.HEADER_DATA: headers_data,
+            ProviderParam.BODY_DATA: body_data,
+            ProviderParam.ACCESS_TOKEN: None,
+            ProviderParam.ACCESS_EXPIRATION: 0,
+            ProviderParam.REFRESH_TOKEN: None,
+            ProviderParam.REFRESH_EXPIRATION: 0
         }
 
 
@@ -86,76 +106,137 @@ def provider_get_token(provider_id: str,
     # initialize the return variable
     result: str | None = None
 
-    err_msg: str | None = None
     with _provider_lock:
         provider: dict[str, Any] = _provider_registry.get(provider_id)
         if provider:
-            now: float = datetime.now(tz=TZ_LOCAL).timestamp()
-            if now > provider.get("access-expiration"):
-                user: str = provider.get("user")
-                pwd: str = provider.get("pwd")
-                headers_data: dict[str, str] = provider.get("headers-data") or {}
-                body_data: dict[str, str] = provider.get("body-data") or {}
-                custom_auth: tuple[str, str] = provider.get("custom-auth")
-                if custom_auth:
-                    body_data[custom_auth[0]] = user
-                    body_data[custom_auth[1]] = pwd
-                else:
-                    enc_bytes: bytes = b64encode(f"{user}:{pwd}".encode())
-                    headers_data["Authorization"] = f"Basic {enc_bytes.decode()}"
-                url: str = provider.get("url")
-            if logger:
-                logger.debug(msg=f"POST {url}, {json.dumps(obj=body_data,
-                                                           ensure_ascii=False)}")
-                try:
-                    # typical return on a token request:
-                    # {
-                    #   "token_type": "Bearer",
-                    #   "access_token": <str>,
-                    #   "expires_in": <number-of-seconds>,
-                    #   optional data:
-                    #   "refresh_token": <str>,
-                    #   "refresh_expires_in": <number-of-seconds>
-                    # }
-                    response: requests.Response = requests.post(url=url,
-                                                                data=body_data,
-                                                                headers=headers_data,
-                                                                timeout=None)
-                    if response.status_code < 200 or response.status_code >= 300:
-                        # request resulted in error, report the problem
-                        err_msg = (f"POST failure, "
-                                   f"status {response.status_code}, reason {response.reason}")
+            now: int = int(datetime.now(tz=TZ_LOCAL).timestamp())
+            if now < provider.get(ProviderParam.ACCESS_EXPIRATION):
+                # retrieve the stored access token
+                result = provider.get(ProviderParam.ACCESS_TOKEN)
+            else:
+                # access token has expired
+                header_data: dict[str, str] | None = None
+                body_data: dict[str, str] | None = None
+                url: str = provider.get(ProviderParam.URL)
+                refresh_token: str = provider.get(ProviderParam.REFRESH_TOKEN)
+                if refresh_token:
+                    # refresh token exists
+                    refresh_expiration: int = provider.get(ProviderParam.REFRESH_EXPIRATION)
+                    if now < refresh_expiration:
+                        # refresh token has not expired
+                        header_data: dict[str, str] = {
+                            "Content-Type": "application/json"
+                        }
+                        body_data: dict[str, str] = {
+                            "grant_type": "refresh_token",
+                            "refresh_token": refresh_token
+                        }
+                if not body_data:
+                    # refresh token does not exist or has expired
+                    user: str = provider.get(ProviderParam.USER)
+                    pwd: str = provider.get(ProviderParam.PWD)
+                    headers_data: dict[str, str] = provider.get(ProviderParam.HEADER_DATA) or {}
+                    body_data: dict[str, str] = provider.get(ProviderParam.BODY_DATA) or {}
+                    custom_auth: tuple[str, str] = provider.get(ProviderParam.CUSTOM_AUTH)
+                    if custom_auth:
+                        body_data[custom_auth[0]] = user
+                        body_data[custom_auth[1]] = pwd
                     else:
-                        # request succeeded
-                        if logger:
-                            logger.debug(msg=f"POST success, status {response.status_code}")
-                        reply: dict[str, Any] = response.json()
-                        provider["access-token"] = reply.get("access_token")
-                        provider["access-expiration"] = now + int(reply.get("expires_in"))
-                        if reply.get("refresh_token"):
-                            provider["refresh-token"] = reply["refesh_token"]
-                            if reply.get("refresh_expires_in"):
-                                provider["refresh-expiration"] = now + int(reply.get("refresh_expires_in"))
-                            else:
-                                provider["refresh-expiration"] = sys.maxsize
-                        if logger:
-                            logger.debug(msg=f"POST {url}: status {response.status_code}")
-                except Exception as e:
-                    # the operation raised an exception
-                    err_msg = exc_format(exc=e,
-                                         exc_info=sys.exc_info())
-                    err_msg = f"POST error, '{err_msg}'"
-        else:
-            err_msg: str = f"Provider '{provider_id}' not registered"
-
-    if err_msg:
-        if isinstance(errors, list):
-            errors.append(err_msg)
-        if logger:
-            logger.error(msg=err_msg)
-    else:
-        result = provider.get("access-token")
+                        enc_bytes: bytes = b64encode(f"{user}:{pwd}".encode())
+                        headers_data["Authorization"] = f"Basic {enc_bytes.decode()}"
+
+                # obtain the token
+                token_data: dict[str, Any] = __post_for_token(url=url,
+                                                              header_data=header_data,
+                                                              body_data=body_data,
+                                                              errors=errors,
+                                                              logger=logger)
+                if token_data:
+                    result = token_data.get("access_token")
+                    provider[ProviderParam.ACCESS_TOKEN] = result
+                    provider[ProviderParam.ACCESS_EXPIRATION] = now + token_data.get("expires_in")
+                    refresh_token = token_data.get("refresh_token")
+                    if refresh_token:
+                        provider[ProviderParam.REFRESH_TOKEN] = refresh_token
+                        refresh_exp: int = token_data.get("refresh_expires_in")
+                        provider[ProviderParam.REFRESH_EXPIRATION] = (now + refresh_exp) \
+                            if refresh_exp else sys.maxsize
+
+        elif logger or isinstance(errors, list):
+            msg: str = f"Unknown provider '{provider_id}'"
+            if logger:
+                logger.error(msg=msg)
+            if isinstance(errors, list):
+                errors.append(msg)
 
     return result
 
 
+def __post_for_token(url: str,
+                     header_data: dict[str, str],
+                     body_data: dict[str, Any],
+                     errors: list[str] | None,
+                     logger: Logger | None) -> dict[str, Any] | None:
+    """
+    Send a *POST* request to *url* and return the token data obtained.
+
+    Token acquisition and token refresh are the two types of requests contemplated herein.
+    For the former, *header_data* and *body_data* will have contents customized to the specific provider,
+    whereas the latter's *body_data* will contain these two attributes:
+        - "grant_type": "refresh_token"
+        - "refresh_token": <current-refresh-token>
+
+    The typical data set returned contains the following attributes:
+        {
+            "token_type": "Bearer",
+            "access_token": <str>,
+            "expires_in": <number-of-seconds>,
+            "refresh_token": <str>,
+            "refesh_expires_in": <number-of-seconds>
+        }
+
+    :param url: the target URL
+    :param header_data: the data to send in the header of the request
+    :param body_data: the data to send in the body of the request
+    :param errors: incidental errors
+    :param logger: optional logger
+    :return: the token data, or *None* if error
+    """
+    # initialize the return variable
+    result: dict[str, Any] | None = None
+
+    # log the POST
+    if logger:
+        logger.debug(msg=f"POST {url}, {json.dumps(obj=body_data,
+                                                   ensure_ascii=False)}")
+    try:
+        response: requests.Response = requests.post(url=url,
+                                                    data=body_data,
+                                                    headers=header_data,
+                                                    timeout=None)
+        if response.status_code == 200:
+            # request succeeded
+            result = response.json()
+            if logger:
+                logger.debug(msg=f"POST success, status {response.status_code}")
+        else:
+            # request failed, report the problem
+            msg: str = (f"POST failure, "
+                        f"status {response.status_code}, reason {response.reason}")
+            if hasattr(response, "content") and response.content:
+                msg += f", content '{response.content}'"
+            if logger:
+                logger.error(msg=msg)
+            if isinstance(errors, list):
+                errors.append(msg)
+    except Exception as e:
+        # the operation raised an exception
+        err_msg = exc_format(exc=e,
+                             exc_info=sys.exc_info())
+        msg: str = f"POST error, {err_msg}"
+        if logger:
+            logger.debug(msg=msg)
+        if isinstance(errors, list):
+            errors.append(msg)
+
+    return result

pypomes_iam/token_pomes.py

@@ -117,8 +117,6 @@ def token_validate(token: str,
             "verify_nbf": False,
             "verify_signature": token_alg in ["RS256", "RS512"] and public_key is not None
         }
-        if issuer:
-            options["require"].append("iss")
         try:
             # raises:
             #   InvalidTokenError: token is invalid

{pypomes_iam-0.5.2.dist-info → pypomes_iam-0.6.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pypomes_iam
-Version: 0.5.2
+Version: 0.6.2
 Summary: A collection of Python pomes, penyeach (IAM modules)
 Project-URL: Homepage, https://github.com/TheWiseCoder/PyPomes-IAM
 Project-URL: Bug Tracker, https://github.com/TheWiseCoder/PyPomes-IAM/issues
@@ -10,7 +10,6 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.12
-Requires-Dist: cachetools>=6.2.1
 Requires-Dist: flask>=3.1.2
 Requires-Dist: pyjwt>=2.10.1
 Requires-Dist: pypomes-core>=2.8.1

pypomes_iam-0.6.2.dist-info/RECORD

@@ -0,0 +1,11 @@
+pypomes_iam/__init__.py,sha256=_6tSFfjuU-5p6TAMqNLHSL6IQmaJMSYuEW-TG3ybhTI,1044
+pypomes_iam/iam_actions.py,sha256=DhDZcY6j3uSWnm5Q5SrA5jriTUCatLqJKd9K7IjA2i8,39283
+pypomes_iam/iam_common.py,sha256=ki_-m6fqJqUbGjgTD41r9zaE-FOXgA_c_tLisIYYTfU,15457
+pypomes_iam/iam_pomes.py,sha256=XkxpwwGivUR3Y1TKR6McrqLUnpFJhRvIrsEn9T_Ut9A,7351
+pypomes_iam/iam_services.py,sha256=IkCjrKDX1Ix7BiHh-BL3VKz5xogcNC8prXkHyJzQoZ8,15862
+pypomes_iam/provider_pomes.py,sha256=3mMj5LQs53YEINUEOfFBAxOwOP3aOR_szlE4daEBLK0,10523
+pypomes_iam/token_pomes.py,sha256=K4nSAotKUoHIE2s3ltc_nVimlNeKS9tnD-IlslkAvkk,6626
+pypomes_iam-0.6.2.dist-info/METADATA,sha256=XeUm7yxjoWFURVvoHDSoYkF5iROCC696PPuHydJ1UIs,661
+pypomes_iam-0.6.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pypomes_iam-0.6.2.dist-info/licenses/LICENSE,sha256=YvUELgV8qvXlaYsy9hXG5EW3Bmsrkw-OJmmILZnonAc,1086
+pypomes_iam-0.6.2.dist-info/RECORD,,

pypomes_iam/jusbr_pomes.py

@@ -1,125 +0,0 @@
-from cachetools import Cache, FIFOCache
-from flask import Flask
-from logging import Logger
-from pypomes_core import (
-    APP_PREFIX, env_get_int, env_get_str
-)
-from typing import Any, Final
-
-from .iam_common import _IAM_SERVERS, IamServer, _iam_lock
-from .iam_pomes import user_token
-
-JUSBR_CLIENT_ID: Final[str] = env_get_str(key=f"{APP_PREFIX}_JUSBR_CLIENT_ID")
-JUSBR_CLIENT_SECRET: Final[str] = env_get_str(key=f"{APP_PREFIX}_JUSBR_CLIENT_SECRET")
-JUSBR_CLIENT_TIMEOUT: Final[int] = env_get_int(key=f"{APP_PREFIX}_JUSBR_CLIENT_TIMEOUT")
-
-JUSBR_ENDPOINT_CALLBACK: Final[str] = env_get_str(key=f"{APP_PREFIX}_JUSBR_ENDPOINT_CALLBACK",
-                                                  def_value="/iam/jusbr:callback")
-JUSBR_ENDPOINT_LOGIN: Final[str] = env_get_str(key=f"{APP_PREFIX}_JUSBR_ENDPOINT_LOGIN",
-                                               def_value="/iam/jusbr:login")
-JUSBR_ENDPOINT_LOGOUT: Final[str] = env_get_str(key=f"{APP_PREFIX}_JUSBR_ENDPOINT_LOGOUT",
-                                                def_value="/iam/jusbr:logout")
-JUSBR_ENDPOINT_TOKEN: Final[str] = env_get_str(key=f"{APP_PREFIX}_JUSBR_ENDPOINT_TOKEN",
-                                               def_value="/iam/jusbr:get-token")
-
-JUSBR_PUBLIC_KEY_LIFETIME: Final[int] = env_get_int(key=f"{APP_PREFIX}_JUSBR_PUBLIC_KEY_LIFETIME",
-                                                    def_value=86400)  # 24 hours
-JUSBR_REALM: Final[str] = env_get_str(key=f"{APP_PREFIX}_JUSBR_REALM")
-JUSBR_RECIPIENT_ATTR: Final[str] = env_get_str(key=f"{APP_PREFIX}_JUSBR_RECIPIENT_ATTR",
-                                               def_value="preferred_username")
-JUSBR_URL_AUTH_BASE: Final[str] = env_get_str(key=f"{APP_PREFIX}_JUSBR_URL_AUTH_BASE")
-
-
-def jusbr_setup(flask_app: Flask,
-                base_url: str = JUSBR_URL_AUTH_BASE,
-                realm: str = JUSBR_REALM,
-                client_id: str = JUSBR_CLIENT_ID,
-                client_secret: str = JUSBR_CLIENT_SECRET,
-                client_timeout: int = JUSBR_CLIENT_TIMEOUT,
-                public_key_lifetime: int | None = JUSBR_PUBLIC_KEY_LIFETIME,
-                recipient_attribute: str | None = JUSBR_RECIPIENT_ATTR,
-                callback_endpoint: str | None = JUSBR_ENDPOINT_CALLBACK,
-                login_endpoint: str | None = JUSBR_ENDPOINT_LOGIN,
-                logout_endpoint: str | None = JUSBR_ENDPOINT_LOGOUT,
-                token_endpoint: str | None = JUSBR_ENDPOINT_TOKEN) -> None:
-    """
-    Configure the JusBR IAM.
-
-    This should be invoked only once, before the first access to a JusBR service.
-
-    :param flask_app: the Flask application
-    :param base_url: base URL to request JusBR services
-    :param realm: the JusBR realm
-    :param client_id: the client's identification with JusBR
-    :param client_secret: the client's password with JusBR
-    :param client_timeout: timeout for login authentication (in seconds,defaults to no timeout)
-    :param public_key_lifetime: how long to use JusBR's public key, before refreshing it (in seconds)
-    :param recipient_attribute: attribute in the token's payload holding the token's subject
-    :param callback_endpoint: endpoint for the callback from JusBR
-    :param login_endpoint: endpoint for redirecting user to JusBR's login page
-    :param logout_endpoint: endpoint for terminating user access to JusBR
-    :param token_endpoint: endpoint for retrieving JusBR's authentication token
-    """
-    from .iam_services import service_login, service_logout, service_callback, service_token
-
-    # configure the JusBR registry
-    cache: Cache = FIFOCache(maxsize=1048576)
-    cache["users"] = {}
-    with _iam_lock:
-        _IAM_SERVERS[IamServer.IAM_JUSRBR] = {
-            "base-url": f"{base_url}/realms/{realm}",
-            "client-id": client_id,
-            "client-secret": client_secret,
-            "client-timeout": client_timeout,
-            "public-key": None,
-            "pk-lifetime": public_key_lifetime,
-            "pk-expiration": 0,
-            "recipient-attr": recipient_attribute,
-            "cache": cache
-        }
-
-    # establish the endpoints
-    if callback_endpoint:
-        flask_app.add_url_rule(rule=callback_endpoint,
-                               endpoint="jusbr-callback",
-                               view_func=service_callback,
-                               methods=["GET"])
-    if login_endpoint:
-        flask_app.add_url_rule(rule=login_endpoint,
-                               endpoint="jusbr-login",
-                               view_func=service_login,
-                               methods=["GET"])
-    if logout_endpoint:
-        flask_app.add_url_rule(rule=logout_endpoint,
-                               endpoint="jusbr-logout",
-                               view_func=service_logout,
-                               methods=["GET"])
-    if token_endpoint:
-        flask_app.add_url_rule(rule=token_endpoint,
-                               endpoint="jusbr-token",
-                               view_func=service_token,
-                               methods=["GET"])
-
-
-def jusbr_get_token(user_id: str,
-                    errors: list[str] = None,
-                    logger: Logger = None) -> str:
-    """
-    Retrieve a JusBR authentication token for *user_id*.
-
-    :param user_id: the user's identification
-    :param errors: incidental errors
-    :param logger: optional logger
-    :return: the uthentication tokem
-    """
-    # declare the return variable
-    result: str
-
-    # retrieve the token
-    args: dict[str, Any] = {"user-id": user_id}
-    with _iam_lock:
-        result = user_token(iam_server=IamServer.IAM_JUSRBR,
-                            args=args,
-                            errors=errors,
-                            logger=logger)
-    return result