pypomes-iam 0.2.3__py3-none-any.whl → 0.7.0__py3-none-any.whl

pypomes_iam/iam_services.py

@@ -0,0 +1,394 @@
+import json
+from flask import Request, Response, request, jsonify
+from logging import Logger
+from typing import Any
+
+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.
+
+    :param logger: the logger to be registered
+    """
+    global __IAM_LOGGER
+    __IAM_LOGGER = logger
+
+
+# @flask_app.route(rule=<login_endpoint>,  # JUSBR_ENDPOINT_LOGIN
+#                  methods=["GET"])
+# @flask_app.route(rule=<login_endpoint>,  # KEYCLOAK_ENDPOINT_LOGIN
+#                  methods=["GET"])
+def service_login() -> Response:
+    """
+    Entry point for the IAM server's login service.
+
+    These are the expected request parameters:
+        - user-id: optional, identifies the reference user (alias: 'login')
+        - redirect-uri: a parameter to be added to the query part of the returned URL
+
+    If provided, the user identification will be validated against the authorization data
+    returned by *iam_server* upon login. On success, the following JSON, containing the appropriate
+    URL for invoking the IAM server's authentication page, is returned:
+        {
+            "login-url": <login-url>
+        }
+
+    :return: *Response* with the URL for invoking the IAM server's authentication page, or *BAD REQUEST* if error
+    """
+    # declare the return variable
+    result: Response | None = None
+
+    # log the request
+    if __IAM_LOGGER:
+        __IAM_LOGGER.debug(msg=_log_init(request=request))
+
+    errors: list[str] = []
+    with _iam_lock:
+        # retrieve the IAM server
+        iam_server: IamServer = _iam_server_from_endpoint(endpoint=request.endpoint,
+                                                          errors=errors,
+                                                          logger=__IAM_LOGGER)
+        if iam_server:
+            # obtain the login URL
+            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:
+        result = Response(response="; ".join(errors),
+                          status=400)
+
+    # log the response
+    if __IAM_LOGGER:
+        __IAM_LOGGER.debug(msg=f"Response {result}, {result.get_data(as_text=True)}")
+
+    return result
+
+
+# @flask_app.route(rule=<logout_endpoint>,  # JUSBR_ENDPOINT_LOGOUT
+#                  methods=["GET"])
+# @flask_app.route(rule=<login_endpoint>,   # KEYCLOAK_ENDPOINT_LOGOUT
+#                  methods=["GET"])
+def service_logout() -> Response:
+    """
+    Entry point for the IAM server's logout service.
+
+    The user is identified by the attribute *user-id* or "login", provided as a request parameter.
+    If successful, remove all data relating to the user from the *IAM* server's registry.
+    Otherwise, this operation fails silently, unless an error has ocurred.
+
+    :return: *Response NO CONTENT*, or *BAD REQUEST* if error
+    """
+    # declare the return variable
+    result: Response | None
+
+    # log the request
+    if __IAM_LOGGER:
+        __IAM_LOGGER.debug(msg=_log_init(request=request))
+
+    errors: list[str] = []
+    with _iam_lock:
+        # retrieve the IAM server
+        iam_server: IamServer = _iam_server_from_endpoint(endpoint=request.endpoint,
+                                                          errors=errors,
+                                                          logger=__IAM_LOGGER)
+        if iam_server:
+            # logout the user
+            action_logout(iam_server=iam_server,
+                          args=request.args,
+                          errors=errors,
+                          logger=__IAM_LOGGER)
+    if errors:
+        result = Response(response="; ".join(errors),
+                          status=400)
+    else:
+        result = Response(status=204)
+
+    # log the response
+    if __IAM_LOGGER:
+        __IAM_LOGGER.debug(msg=f"Response {result}")
+
+    return result
+
+
+# @flask_app.route(rule=<callback_endpoint>,  # JUSBR_ENDPOINT_CALLBACK
+#                  methods=["GET", "POST"])
+# @flask_app.route(rule=<callback_endpoint>,  # KEYCLOAK_ENDPOINT_CALLBACK
+#                  methods=["POST"])
+def service_callback() -> Response:
+    """
+    Entry point for the callback from the IAM server on authentication operation.
+
+    This callback is invoked from a front-end application after a successful login at the
+    *IAM* server's login page, forwarding the data received. In a typical OAuth2 flow faction,
+    this data is then used to effectively obtain the token from the *IAM* server.
+
+    The relevant expected request arguments are:
+        - *state*: used to enhance security during the authorization process, typically to provide *CSRF* protection
+        - *code*: the temporary authorization code provided by the IAM server, to be exchanged for the token
+
+    On success, the returned *Response* will contain the following JSON:
+        {
+            "user-id": <reference-user-identification>,
+            "access-token": <token>
+        }
+
+    :return: *Response* containing the reference user identification and the token, or *BAD REQUEST*
+    """
+    # log the request
+    if __IAM_LOGGER:
+        __IAM_LOGGER.debug(msg=_log_init(request=request))
+
+    errors: list[str] = []
+    token_data: tuple[str, str] | None = None
+    with _iam_lock:
+        # retrieve the IAM server
+        iam_server: IamServer = _iam_server_from_endpoint(endpoint=request.endpoint,
+                                                          errors=errors,
+                                                          logger=__IAM_LOGGER)
+        if iam_server:
+            # process the callback operation
+            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)})
+        result.status_code = 400
+    else:
+        result = jsonify({"user-id": token_data[0],
+                          "access-token": token_data[1]})
+    if __IAM_LOGGER:
+        # log the response (the returned data is not logged, as it contains the token)
+        __IAM_LOGGER.debug(msg=f"Response {result}")
+
+    return result
+
+
+# @flask_app.route(rule=<token_endpoint>,  # JUSBR_ENDPOINT_TOKEN
+#                  methods=["GET"])
+# @flask_app.route(rule=<token_endpoint>,  # KEYCLOAK_ENDPOINT_TOKEN
+#                  methods=["GET"])
+def service_token() -> Response:
+    """
+    Entry point for retrieving a token from the *IAM* server.
+
+    The user is identified by the attribute *user-id* or "login", provided as a request parameter.
+
+    On success, the returned *Response* will contain the following JSON:
+        {
+            "user-id": <reference-user-identification>,
+            "access-token": <token>
+        }
+
+    :return: *Response* containing the user reference identification and the token, or *BAD REQUEST*
+    """
+    # log the request
+    if __IAM_LOGGER:
+        __IAM_LOGGER.debug(msg=_log_init(request=request))
+
+    # obtain the user's identification
+    args: dict[str, Any] = request.args
+    user_id: str = args.get("user-id") or args.get("login")
+
+    errors: list[str] = []
+    token: str | None = None
+    if user_id:
+        with _iam_lock:
+            # retrieve the IAM server
+            iam_server: IamServer = _iam_server_from_endpoint(endpoint=request.endpoint,
+                                                              errors=errors,
+                                                              logger=__IAM_LOGGER)
+            if iam_server:
+                # retrieve the token
+                errors: list[str] = []
+                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)
+        if __IAM_LOGGER:
+            __IAM_LOGGER.error(msg=msg)
+
+    result: Response
+    if errors:
+        result = Response(response="; ".join(errors),
+                          status=400)
+    else:
+        result = jsonify({"user-id": user_id,
+                          "access-token": token})
+    if __IAM_LOGGER:
+        # log the response (the returned data is not logged, as it contains the token)
+        __IAM_LOGGER.debug(msg=f"Response {result}")
+
+    return result
+
+
+# @flask_app.route(rule=<callback_endpoint>,  # KEYCLOAK_ENDPOINT_EXCHANGE
+#                  methods=["POST"])
+def service_exchange() -> Response:
+    """
+    Entry point for requesting the *IAM* server to exchange the token.
+
+    This is currently limited to the *KEYCLOAK* server. The token itself is stored in *KEYCLOAK*'s registry.
+    The expected request parameters are:
+        - user-id: identification for the reference user (alias: 'login')
+        - access-token: the token to be exchanged
+
+    If the exchange is successful, the token data is stored in the *IAM* server's registry, and returned.
+    Otherwise, *errors* will contain the appropriate error message.
+
+    On success, the typical *Response* returned will contain the following attributes:
+        {
+            "token_type": "Bearer",
+            "access_token": <str>,
+            "expires_in": <number-of-seconds>,
+            "refresh_token": <str>,
+            "refesh_expires_in": <number-of-seconds>
+        }
+
+    :return: *Response* containing the token data, or *BAD REQUEST*
+    """
+    # log the request
+    if __IAM_LOGGER:
+        __IAM_LOGGER.debug(msg=_log_init(request=request))
+
+    errors: list[str] = []
+    with _iam_lock:
+        # retrieve the IAM server (currently, only 'IAM_KEYCLOAK' is supported)
+        iam_server: IamServer = _iam_server_from_endpoint(endpoint=request.endpoint,
+                                                          errors=errors,
+                                                          logger=__IAM_LOGGER)
+        # exchange the token
+        token_data: dict[str, Any] | None = None
+        if iam_server:
+            errors: list[str] = []
+            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),
+                          status=400)
+    else:
+        result = jsonify(token_data)
+
+    # log the response
+    if __IAM_LOGGER:
+        __IAM_LOGGER.debug(msg=f"Response {result}, {result.get_data(as_text=True)}")
+
+    return result
+
+
+def _log_init(request: Request) -> str:
+    """
+    Build the messages for logging the request entry.
+
+    :param request: the Request object
+    :return: the log message
+    """
+
+    params: str = json.dumps(obj=request.args,
+                             ensure_ascii=False)
+    return f"Request {request.method}:{request.path}, params {params}"

pypomes_iam/provider_pomes.py

@@ -1,10 +1,30 @@
+import json
 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 typing import Any
+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:
 # {
@@ -12,14 +32,20 @@ from typing import Any
 #      "url": <strl>,
 #      "user": <str>,
 #      "pwd": <str>,
-#      "basic-auth": <bool>,
+#      "custom-auth": <bool>,
 #      "headers-data": <dict[str, str]>,
 #      "body-data": <dict[str, str],
-#      "token": <str>,
-#      "expiration": <timestamp>
+#      "access-token": <str>,
+#      "access-expiration": <timestamp>,
+#      "refresh-token": <str>,
+#      "refresh-expiration": <timestamp>
 #    }
 # }
-_provider_registry: dict[str, dict[str, Any]] = {}
+_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[Lock] = Lock()
 
 
 def provider_register(provider_id: str,
@@ -48,18 +74,21 @@ def provider_register(provider_id: str,
     :param headers_data: optional key-value pairs to be added to the request headers
     :param body_data: optional key-value pairs to be added to the request body
     """
-    global _provider_registry  # noqa: PLW0602
-
-    _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,
-        "token": None,
-        "expiration": datetime.now(tz=TZ_LOCAL).timestamp()
-    }
+    global _provider_registry
+
+    with _provider_lock:
+        _provider_registry[provider_id] = {
+            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
+        }
 
 
 def provider_get_token(provider_id: str,
@@ -77,63 +106,137 @@ def provider_get_token(provider_id: str,
     # initialize the return variable
     result: str | None = None
 
-    err_msg: str | None = None
-    provider: dict[str, Any] = _provider_registry.get(provider_id)
-    if provider:
-        now: float = datetime.now(tz=TZ_LOCAL).timestamp()
-        if now > provider.get("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
+    with _provider_lock:
+        provider: dict[str, Any] = _provider_registry.get(provider_id)
+        if provider:
+            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:
-                enc_bytes: bytes = b64encode(f"{user}:{pwd}".encode())
-                headers_data["Authorization"] = f"Basic {enc_bytes.decode()}"
-            url: str = provider.get("url")
-            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 '{url}': failed, "
-                               f"status {response.status_code}, reason '{response.reason}'")
-                else:
-                    reply: dict[str, Any] = response.json()
-                    provider["token"] = reply.get("access_token")
-                    provider["expiration"] = now + int(reply.get("expires_in"))
-                    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 '{url}': 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("token")
+                # 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:
+                        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