pypomes-iam 0.1.0__tar.gz → 0.1.2__tar.gz

{pypomes_iam-0.1.0 → pypomes_iam-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pypomes_iam
-Version: 0.1.0
+Version: 0.1.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
@@ -12,5 +12,7 @@ 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.0
+Requires-Dist: pypomes-crypto>=0.4.8
 Requires-Dist: requests>=2.32.5

{pypomes_iam-0.1.0 → pypomes_iam-0.1.2}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pypomes_iam"
-version = "0.1.0"
+version = "0.1.2"
 authors = [
   { name="GT Nunes", email="wisecoder01@gmail.com" }
 ]
@@ -21,7 +21,9 @@ classifiers = [
 dependencies = [
     "cachetools>=6.2.1",
     "Flask>=3.1.2",
+    "PyJWT>=2.10.1",
     "pypomes-core>=2.8.0",
+    "pypomes-crypto>=0.4.8",
     "requests>=2.32.5"
 ]
 

{pypomes_iam-0.1.0 → pypomes_iam-0.1.2}/src/pypomes_iam/__init__.py

@@ -4,12 +4,17 @@ from .jusbr_pomes import (
 from .provider_pomes import (
     provider_register, provider_get_token
 )
+from .token_pomes import (
+    token_validate
+)
 
 __all__ = [
     # jusbr_pomes
     "jusbr_setup", "jusbr_get_token", "jusbr_set_scope",
     # provider_pomes
-    "provider_register", "provider_get_token"
+    "provider_register", "provider_get_token",
+    # token_pomes
+    "token_validate"
 ]
 
 from importlib.metadata import version

{pypomes_iam-0.1.0 → pypomes_iam-0.1.2}/src/pypomes_iam/jusbr_pomes.py

@@ -24,38 +24,33 @@ JUSBR_ENDPOINT_LOGOUT: Final[str] = env_get_str(key=f"{APP_PREFIX}_JUSBR_ENDPOIN
 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_URL_AUTH_BASE: Final[str] = env_get_str(key=f"{APP_PREFIX}_JUSBR_URL_AUTH_BASE")
 JUSBR_URL_AUTH_CALLBACK: Final[str] = env_get_str(key=f"{APP_PREFIX}_JUSBR_URL_AUTH_CALLBACK")
-JUSBR_URL_AUTH_LOGIN: Final[str] = env_get_str(key=f"{APP_PREFIX}JUSBR_URL_AUTH_LOGIN")
-JUSBR_URL_AUTH_TOKEN: Final[str] = env_get_str(key=f"{APP_PREFIX}JUSBR_URL_AUTH_TOKEN")
 
-# safe memory cache - structure:
+# registry structure:
 # {
 #    "client-id": <str>,
 #    "client-secret": <str>,
-#    "auth-url": <str>,
-#    "token-url": <str>,
 #    "client-timeout": <int>,
+#    "public_key": <str>,
+#    "key-expiration": <int>,
+#    "auth-url": <str>,
+#    "callback-url": <str>,
 #    "users": {
 #       "<user-id>": {
 #         "cache-obj": <Cache>,
 #         "oauth-scope": <str>,
 #         "access-expiration": <timestamp>,
-#         data in <TTLCache>:
+#         data in <Cache>:
 #           "oauth-state": <str>
 #           "access-token": <str>
 #           "refresh-token": <str>
 #       }
 #    }
 # }
-_jusbr_registry: dict[str, Any] = {
-    "client-id": None,
-    "client-secret": None,
-    "client-timeout": None,
-    "auth-url": None,
-    "callback-url": None,
-    "token-url": None,
-    "users": {}
-}
+_jusbr_registry: dict[str, Any] | None = None
 
 # dafault logger
 _logger: Logger | None = None
@@ -65,13 +60,13 @@ def jusbr_setup(flask_app: Flask,
                 client_id: str = JUSBR_CLIENT_ID,
                 client_secret: str = JUSBR_CLIENT_SECRET,
                 client_timeout: int = JUSBR_CLIENT_TIMEOUT,
+                public_key_lifetime: int = JUSBR_PUBLIC_KEY_LIFETIME,
                 callback_endpoint: str = JUSBR_ENDPOINT_CALLBACK,
                 token_endpoint: str = JUSBR_ENDPOINT_TOKEN,
                 login_endpoint: str = JUSBR_ENDPOINT_LOGIN,
                 logout_endpoint: str = JUSBR_ENDPOINT_LOGOUT,
-                auth_url: str = JUSBR_URL_AUTH_LOGIN,
+                auth_url: str = JUSBR_URL_AUTH_BASE,
                 callback_url: str = JUSBR_URL_AUTH_CALLBACK,
-                token_url: str = JUSBR_URL_AUTH_TOKEN,
                 logger: Logger = None) -> None:
     """
     Configure the JusBR IAM.
@@ -82,13 +77,13 @@ def jusbr_setup(flask_app: Flask,
     :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 callback_endpoint: endpoint for the callback from JusBR
     :param token_endpoint: endpoint for retrieving the JusBR authentication token
     :param login_endpoint: endpoint for redirecting user to JusBR login page
     :param logout_endpoint: endpoint for terminating user access to JusBR
-    :param auth_url: URL to access the JusBR login page
+    :param auth_url: base URL to request the JusBR services
     :param callback_url: URL for JusBR to callback on login
-    :param token_url: URL for obtaing or refreshing the token
     :param logger: optional logger
     """
     # establish the logger
@@ -97,14 +92,15 @@ def jusbr_setup(flask_app: Flask,
 
     # configure the JusBR registry
     global _jusbr_registry  # noqa: PLW0602
-    _jusbr_registry.update({
+    _jusbr_registry = {
         "client-id": client_id,
         "client-secret": client_secret,
         "client-timeout": client_timeout,
         "auth-url": auth_url,
         "callback-url": callback_url,
-        "token-url": token_url
-    })
+        "key-expiration": int(datetime.now(tz=TZ_LOCAL).timestamp()),
+        "key-lifetime": public_key_lifetime
+    }
 
     # establish the endpoints
     if token_endpoint:
@@ -135,21 +131,20 @@ def service_login() -> Response:
     """
     Entry point for the JusBR login service.
 
-    Redirect the request to the JusBR authentication page, with the apprpriate parameters.
+    Redirect the request to the JusBR authentication page, with the appropriate parameters.
 
     :return: the response from the redirect operation
     """
     global _jusbr_registry
 
-    # retrieve user id
+    # retrieve user data (if not provided, 'user_id' is temporarily set to 'oauth_state'
     input_params: dict[str, Any] = request.values
-    user_id: str = input_params.get("user-id") or input_params.get("login")
-
-    # retrieve user data
-    user_data: dict[str, Any] = __get_user_data(user_id=user_id,
+    oauth_state: str = "".join(secrets.choice(string.ascii_letters + string.digits) for _ in range(16))
+    user_id: str = input_params.get("user-id") or input_params.get("login") or oauth_state
+    # obtain user data
+    user_data: dict[str, Any] = __get_user_data(user_id=user_id or oauth_state,
                                                 logger=_logger)
     # build redirect url
-    oauth_state: str = "".join(secrets.choice(string.ascii_letters + string.digits) for _ in range(16))
     timeout: int = __get_login_timeout()
     safe_cache: Cache
     if timeout:
@@ -159,7 +154,7 @@ def service_login() -> Response:
         safe_cache = FIFOCache(maxsize=16)
     safe_cache["oauth-state"] = oauth_state
     user_data["cache-obj"] = safe_cache
-    auth_url: str = (f"{_jusbr_registry["auth-url"]}?response_type=code"
+    auth_url: str = (f"{_jusbr_registry["auth-url"]}/protocol/openid-connect/auth?response_type=code"
                      f"&client_id={_jusbr_registry["client-id"]}"
                      f"&redirect_url={_jusbr_registry["callback-url"]}"
                      f"&state={oauth_state}")
@@ -178,7 +173,7 @@ def service_logout() -> Response:
 
     Remove all data associating the user with JusBR from the registry.
 
-    :return: the response from the redirect operation
+    :return: response *OK*
     """
     global _jusbr_registry
 
@@ -187,7 +182,7 @@ def service_logout() -> Response:
     user_id: str = input_params.get("user-id") or input_params.get("login")
 
     # remove user data
-    if user_id in _jusbr_registry.get("users"):
+    if user_id and user_id in _jusbr_registry.get("users"):
         _jusbr_registry["users"].pop(user_id)
         if _logger:
             _logger.debug(f"User '{user_id}' removed from the registry")
@@ -204,14 +199,18 @@ def service_callback() -> Response:
     :return: the response containing the token, or *NOT AUTHORIZED*
     """
     global _jusbr_registry
+    from .token_pomes import token_validate
 
     # validate the OAuth2 state
     oauth_state: str = request.args.get("state")
+    user_id: str | None = None
     user_data: dict[str, Any] | None = None
     if oauth_state:
-        for data in _jusbr_registry.get("users"):
-            safe_cache: Cache = user_data.get("cache-obj")
-            if safe_cache and oauth_state == safe_cache.get("oauth-state"):
+        for user, data in _jusbr_registry.get("users").items():
+            safe_cache: Cache = data.get("cache-obj")
+            if user == oauth_state or \
+                    (safe_cache and oauth_state == safe_cache.get("oauth-state")):
+                user_id = user
                 user_data = data
                 # 'oauth-state' is to be used only once
                 safe_cache["oauth-state"] = None
@@ -231,6 +230,20 @@ def service_callback() -> Response:
                              body_data=body_data,
                              errors=errors,
                              logger=_logger)
+        # retrieve the token's claims
+        if not errors:
+            token_claims: dict[str, dict[str, Any]] = token_validate(token=token,
+                                                                     issuer=_jusbr_registry.get("auth-url"),
+                                                                     public_key=_jusbr_registry.get("public_key"),
+                                                                     errors=errors,
+                                                                     logger=_logger)
+            if not errors:
+                token_user: str = token_claims["payload"].get("preferred_username")
+                if user_id == oauth_state:
+                    user_id = token_user
+                    _jusbr_registry["users"][user_id] = _jusbr_registry["users"].pop(oauth_state)
+                elif token_user != user_id:
+                    errors.append(f"Token was issued to user '{token_user}'")
     else:
         msg: str = "Unknown OAuth2 code received"
         if __get_login_timeout():
@@ -242,7 +255,9 @@ def service_callback() -> Response:
         result = jsonify({"errors": "; ".join(errors)})
         result.status_code = 400
     else:
-        result = jsonify({"access_token": token})
+        result = jsonify({
+            "user_id": user_id,
+            "access_token": token})
 
     return result
 
@@ -253,20 +268,22 @@ def service_token() -> Response:
     """
     Entry point for retrieving the JusBR token.
 
-    :return: the response containing the token, or *NOT AUTHORIZED*
+    :return: the response containing the token, or *UNAUTHORIZED*
     """
     # retrieve user id
     input_params: dict[str, Any] = request.args
     user_id: str = input_params.get("user-id") or input_params.get("login")
 
     # retrieve the token
+    errors: list[str] = []
     token: str = jusbr_get_token(user_id=user_id,
                                  logger=_logger)
     result: Response
     if token:
         result = jsonify({"token": token})
     else:
-        result = Response(status=401)
+        result = Response("; ".join(errors))
+        result.status_code = 401
 
     return result
 
@@ -340,6 +357,42 @@ def jusbr_set_scope(user_id: str,
         logger.debug(f"Scope for user '{user_id}' set to '{scope}'")
 
 
+def __get_public_key(url: str,
+                     logger: Logger | None) -> str:
+    """
+    Obtain the public key used by JusBR to sign the authentication tokens.
+
+    :param url: the base URL to request the public key
+    :return: the public key, in *PEM* format
+    """
+    from pypomes_crypto import crypto_jwk_convert
+    global _jusbr_registry
+
+    # initialize the return variable
+    result: str | None = None
+
+    now: int = int(datetime.now(tz=TZ_LOCAL).timestamp())
+    if now > _jusbr_registry.get("key-expiration"):
+        # obtain a new public key
+        url: str = f"{url}/protocol/openid-connect/certs"
+        response: requests.Response = requests.get(url=url)
+        if response.status_code == 200:
+            # request succeeded
+            reply: dict[str, Any] = response.json()
+            result = crypto_jwk_convert(jwk=reply["keys"][0],
+                                        fmt="PEM")
+            _jusbr_registry["public-key"] = result
+            duration: int = _jusbr_registry.get("key-lifetime") or 0
+            _jusbr_registry["key-expiration"] = now + duration
+        elif logger:
+            logger.error(msg=f"GET '{url}': failed, "
+                             f"status {response.status_code}, reason '{response.reason}'")
+    else:
+        result = _jusbr_registry.get("public-key")
+
+    return result
+
+
 def __get_login_timeout() -> int | None:
     """
     Retrieve the timeout currently applicable for the login operation.
@@ -410,9 +463,10 @@ def __post_jusbr(user_data: dict[str, Any],
     if client_secret:
         body_data["client_secret"] = client_secret
 
+    # obtain the token
     err_msg: str | None = None
     safe_cache: Cache = user_data.get("cache-obj")
-    url: str = _jusbr_registry.get("auth-url")
+    url: str = _jusbr_registry.get("auth-url") + "/protocol/openid-connect/token"
     now: int = int(datetime.now(tz=TZ_LOCAL).timestamp())
     try:
         # JusBR return on a token request:

pypomes_iam-0.1.2/src/pypomes_iam/keycloak_pomes.py

@@ -0,0 +1,212 @@
+# import requests
+# import secrets
+# import string
+# import sys
+# from cachetools import Cache, FIFOCache, TTLCache
+# from datetime import datetime
+from flask import Flask, Response, redirect, request, jsonify
+from logging import Logger
+from pypomes_core import (
+    APP_PREFIX, TZ_LOCAL, env_get_int, env_get_str, exc_format
+)
+from typing import Any, Final
+
+KEYCLOAK_CLIENT_ID: Final[str] = env_get_str(key=f"{APP_PREFIX}_KEYCLOAK_CLIENT_ID")
+KEYCLOAK_CLIENT_SECRET: Final[str] = env_get_str(key=f"{APP_PREFIX}_KEYCLOAK_CLIENT_SECRET")
+KEYCLOAK_CLIENT_TIMEOUT: Final[int] = env_get_int(key=f"{APP_PREFIX}_KEYCLOAK_CLIENT_TIMEOUT")
+
+KEYCLOAK_ENDPOINT_CALLBACK: Final[str] = env_get_str(key=f"{APP_PREFIX}_KEYCLOAK_ENDPOINT_CALLBACK",
+                                                     def_value="/iam/keycloak:callback")
+KEYCLOAK_ENDPOINT_LOGIN: Final[str] = env_get_str(key=f"{APP_PREFIX}_KEYCLOAK_ENDPOINT_LOGIN",
+                                                  def_value="/iam/keycloak:login")
+KEYCLOAK_ENDPOINT_LOGOUT: Final[str] = env_get_str(key=f"{APP_PREFIX}_KEYCLOAK_ENDPOINT_LOGOUT",
+                                                   def_value="/iam/keycloak:logout")
+KEYCLOAK_ENDPOINT_TOKEN: Final[str] = env_get_str(key=f"{APP_PREFIX}_KEYCLOAK_ENDPOINT_TOKEN",
+                                                  def_value="/iam/keycloak:get-token")
+
+KEYCLOAK_REALM: Final[str] = env_get_str(key=f"{APP_PREFIX}_KEYCLOAK_REALM")
+KEYCLOAK_URL_AUTH_BASE: Final[str] = env_get_str(key=f"{APP_PREFIX}_KEYCLOAK_URL_AUTH_BASE")
+KEYCLOAK_URL_AUTH_CALLBACK: Final[str] = env_get_str(key=f"{APP_PREFIX}_KEYCLOAK_URL_AUTH_CALLBACK")
+
+# registry structure:
+# {
+#    "client-id": <str>,
+#    "client-secret": <str>,
+#    "client-timeout": <int>,
+#    "realm": <str>,
+#    "auth-url": <str>,
+#    "callback-url": <str>,
+#    "users": {
+#       "<user-id>": {
+#         "cache-obj": <Cache>,
+#         "oauth-scope": <str>,
+#         "access-expiration": <timestamp>,
+#         data in <Cache>:
+#           "oauth-state": <str>
+#           "access-token": <str>
+#           "refresh-token": <str>
+#       }
+#    }
+# }
+_keycloak_registry: dict[str, Any] = {
+    "client-id": None,
+    "client-secret": None,
+    "client-timeout": None,
+    "realm": None,
+    "auth-url": None,
+    "callback-url": None,
+    "users": {}
+}
+
+# dafault logger
+_logger: Logger | None = None
+
+
+def keycloak_setup(flask_app: Flask,
+                   client_id: str = KEYCLOAK_CLIENT_ID,
+                   client_secret: str = KEYCLOAK_CLIENT_SECRET,
+                   client_timeout: int = KEYCLOAK_CLIENT_TIMEOUT,
+                   realm: str = KEYCLOAK_REALM,
+                   callback_endpoint: str = KEYCLOAK_ENDPOINT_CALLBACK,
+                   token_endpoint: str = KEYCLOAK_ENDPOINT_TOKEN,
+                   login_endpoint: str = KEYCLOAK_ENDPOINT_LOGIN,
+                   logout_endpoint: str = KEYCLOAK_ENDPOINT_LOGOUT,
+                   auth_url: str = KEYCLOAK_URL_AUTH_BASE,
+                   callback_url: str = KEYCLOAK_URL_AUTH_CALLBACK,
+                   logger: Logger = None) -> None:
+    """
+    Configure the Keycloak IAM.
+
+    This should be invoked only once, before the first access to a Keycloak service.
+
+    :param flask_app: the Flask application
+    :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 realm: the Keycloak reals
+    :param callback_endpoint: endpoint for the callback from JusBR
+    :param token_endpoint: endpoint for retrieving the JusBR authentication token
+    :param login_endpoint: endpoint for redirecting user to JusBR login page
+    :param logout_endpoint: endpoint for terminating user access to JusBR
+    :param auth_url: base URL to request the JusBR services
+    :param callback_url: URL for Keycloak to callback on login
+    :param logger: optional logger
+    """
+    global _keycloak_registry  # noqa: PLW0602
+
+    # establish the logger
+    global _logger
+    _logger = logger
+
+    # configure the JusBR registry
+    _keycloak_registry.update({
+        "client-id": client_id,
+        "client-secret": client_secret,
+        "client-timeout": client_timeout,
+        "realm": realm,
+        "auth-url": auth_url,
+        "callback-url": callback_url
+    })
+
+    # establish the endpoints
+    if token_endpoint:
+        flask_app.add_url_rule(rule=token_endpoint,
+                               endpoint="keycloak-token",
+                               view_func=service_token,
+                               methods=["GET"])
+    if login_endpoint:
+        flask_app.add_url_rule(rule=login_endpoint,
+                               endpoint="keycloak-login",
+                               view_func=service_login,
+                               methods=["GET"])
+    if logout_endpoint:
+        flask_app.add_url_rule(rule=logout_endpoint,
+                               endpoint="keycloak-logout",
+                               view_func=service_logout,
+                               methods=["GET"])
+    if callback_endpoint:
+        flask_app.add_url_rule(rule=callback_endpoint,
+                               endpoint="keycloak-callback",
+                               view_func=service_callback,
+                               methods=["POST"])
+
+
+# @flask_app.route(rule=<login_endpoint>,  # KEYCLOAK_LOGIN_ENDPOINT: /iam/keycloak:login
+#                  methods=["GET"])
+def service_login() -> Response:
+    """
+    Entry point for the Keycloak login service.
+
+    Redirect the request to the Keycloak authentication page, with the appropriate parameters.
+
+    :return: the response from the redirect operation
+    """
+    global _keycloak_registry
+
+    # retrieve user id
+    input_params: dict[str, Any] = request.args
+    _user_id: str = input_params.get("user-id") or input_params.get("login")
+    return Response()
+
+
+# @flask_app.route(rule=<login_endpoint>,  # KEYCLOAK_LOGIN_ENDPOINT: /iam/keycloak:logout
+#                  methods=["GET"])
+def service_logout() -> Response:
+    """
+    Entry point for the JusBR logout service.
+
+    Remove all data associating the user with JusBR from the registry.
+
+    :return: response *OK*
+    """
+    global _keycloak_registry
+
+    # retrieve user id
+    input_params: dict[str, Any] = request.args
+    _user_id: str = input_params.get("user-id") or input_params.get("login")
+    return Response()
+
+
+# @flask_app.route(rule=<callback_endpoint>,  # KEYCLOAK_CALLBACK_ENDPOINT: /iam/keycloak:callback
+#                  methods=["POST"])
+def service_callback() -> Response:
+    """
+    Entry point for the callback from Keycloak on authentication operation.
+
+    :return: the response containing the token, or *NOT AUTHORIZED*
+    """
+    global _keycloak_registry
+    return Response()
+
+
+# @flask_app.route(rule=<token_endpoint>,  # JUSBR_TOKEN_ENDPOINT: /iam/jusbr:get-token
+#                  methods=["GET"])
+def service_token() -> Response:
+    """
+    Entry point for retrieving the Keycloak token.
+
+    :return: the response containing the token, or *UNAUTHORIZED*
+    """
+    # retrieve user id
+    input_params: dict[str, Any] = request.args
+    _user_id: str = input_params.get("user-id") or input_params.get("login")
+    return Response()
+
+
+def keycloak_get_token(user_id: str,
+                       errors: list[str] = None,
+                       logger: Logger = None) -> str:
+    """
+    Retrieve the authentication token for user *user_id*.
+
+    :param user_id: the user's identification
+    :param errors: incidental error messages
+    :param logger: optional logger
+    :return: the token for *user_id*, or *None* if error
+    """
+    global _keycloak_registry
+
+    # initialize the return variable
+    result: str | None = None
+    return result
+

pypomes_iam-0.1.2/src/pypomes_iam/token_pomes.py

@@ -0,0 +1,101 @@
+import jwt
+import sys
+from jwt import PyJWK
+from jwt.algorithms import RSAPublicKey
+from logging import Logger
+from pypomes_core import exc_format
+from typing import Any
+
+
+def token_validate(token: str,
+                   issuer: str = None,
+                   public_key: str | bytes | PyJWK | RSAPublicKey = None,
+                   errors: list[str] = None,
+                   logger: Logger = None) -> dict[str, dict[str, Any]] | None:
+    """
+    Verify whether *token* is a valid JWT token, and return its claims (sections *header* and *payload*).
+
+    The supported public key types are:
+        - *DER*: Distinguished Encoding Rules (bytes)
+        - *PEM*: Privacy-Enhanced Mail (str)
+        - *PyJWK*: a formar from the *PyJWT* package
+        - *RSAPublicKey*: a format from the *PyJWT* package
+
+    If an asymmetric algorithm was used to sign the token and *public_key* is provided, then
+    the token is validated, by using the data in its *signature* section.
+
+    On failure, *errors* will contain the reason(s) for rejecting *token*.
+    On success, return the token's claims (*header* and *payload*).
+
+    :param token: the token to be validated
+    :param public_key: optional public key used to sign the token, in *PEM* format
+    :param issuer: optional value to compare with the token's *iss* (issuer) attribute in its *payload*
+    :param errors: incidental error messages
+    :param logger: optional logger
+    :return: The token's claims (*header* and *payload*) if it is valid, *None* otherwise
+    """
+    # initialize the return variable
+    result: dict[str, dict[str, Any]] | None = None
+
+    if logger:
+        logger.debug(msg="Validate JWT token")
+
+    # make sure to have an errors list
+    if not isinstance(errors, list):
+        errors = []
+
+    # extract needed data from token header
+    token_header: dict[str, Any] | None = None
+    try:
+        token_header: dict[str, Any] = jwt.get_unverified_header(jwt=token)
+    except Exception as e:
+        exc_err: str = exc_format(exc=e,
+                                  exc_info=sys.exc_info())
+        if logger:
+            logger.error(msg=f"Error retrieving the token's header: {exc_err}")
+        errors.append(exc_err)
+
+    # validate the token
+    if not errors:
+        token_alg: str = token_header.get("alg")
+        options: dict[str, Any] = {
+            "require": ["exp", "iat"],
+            "verify_aud": False,
+            "verify_exp": True,
+            "verify_iat": True,
+            "verify_iss": issuer is not None,
+            "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
+            #   InvalidKeyError: authentication key is not in the proper format
+            #   ExpiredSignatureError: token and refresh period have expired
+            #   InvalidSignatureError: signature does not match the one provided as part of the token
+            #   ImmatureSignatureError: 'nbf' or 'iat' claim represents a timestamp in the future
+            #   InvalidAlgorithmError: the specified algorithm is not recognized
+            #   InvalidIssuedAtError: 'iat' claim is non-numeric
+            #   MissingRequiredClaimError: a required claim is not contained in the claimset
+            payload: dict[str, Any] = jwt.decode(jwt=token,
+                                                 key=public_key,
+                                                 algorithms=[token_alg],
+                                                 options=options,
+                                                 issuer=issuer)
+            result = {
+                "header": token_header,
+                "payload": payload
+            }
+        except Exception as e:
+            exc_err: str = exc_format(exc=e,
+                                      exc_info=sys.exc_info())
+            if logger:
+                logger.error(msg=f"Error decoding the token: {exc_err}")
+            errors.append(exc_err)
+
+    if not errors and logger:
+        logger.debug(msg="Token is valid")
+
+    return result