pypomes-iam 0.5.0__tar.gz → 0.5.2__tar.gz

{pypomes_iam-0.5.0 → pypomes_iam-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pypomes_iam
-Version: 0.5.0
+Version: 0.5.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

{pypomes_iam-0.5.0 → pypomes_iam-0.5.2}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pypomes_iam"
-version = "0.5.0"
+version = "0.5.2"
 authors = [
   { name="GT Nunes", email="wisecoder01@gmail.com" }
 ]

{pypomes_iam-0.5.0 → pypomes_iam-0.5.2}/src/pypomes_iam/iam_common.py

@@ -55,6 +55,64 @@ _IAM_SERVERS: Final[dict[IamServer, dict[str, Any]]] = {}
 _iam_lock: Final[RLock] = RLock()
 
 
+def _iam_server_from_endpoint(endpoint: str,
+                              errors: list[str] | None,
+                              logger: Logger | None) -> IamServer | None:
+    """
+    Retrieve the registered *IAM* server associated with the service's invocation *endpoint*.
+
+    :param endpoint: the service's invocation endpoint
+    :param errors: incidental error messages
+    :param logger: optional logger
+    :return: the corresponding *IAM* server, or *None* if one could not be obtained
+    """
+    # declare the return variable
+    result: IamServer | None
+
+    if endpoint.startswith("jusbr"):
+        result = IamServer.IAM_JUSRBR
+    elif endpoint.startswith("keycloak"):
+        result = IamServer.IAM_KEYCLOAK
+    else:
+        result = None
+        msg: str = f"Unable to find a IAM server to service endpoint '{endpoint}'"
+        if logger:
+            logger.error(msg=msg)
+        if isinstance(errors, list):
+            errors.append(msg)
+
+    return result
+
+
+def _iam_server_from_issuer(issuer: str,
+                            errors: list[str] | None,
+                            logger: Logger | None) -> IamServer | None:
+    """
+    Retrieve the registered *IAM* server associated with the token's *issuer*.
+
+    :param issuer: the token's issuer
+    :param errors: incidental error messages
+    :param logger: optional logger
+    :return: the corresponding *IAM* server, or *None* if one could not be obtained
+    """
+    # initialize the return variable
+    result: IamServer | None = None
+
+    for iam_server, server_data in _IAM_SERVERS.items():
+        if server_data["base-url"] == issuer:
+            result = IamServer(iam_server)
+            break
+
+    if not result:
+        msg: str = f"Unable to find a IAM server associated with token issuer '{issuer}'"
+        if logger:
+            logger.error(msg=msg)
+        if isinstance(errors, list):
+            errors.append(msg)
+
+    return result
+
+
 def _get_public_key(iam_server: IamServer,
                     errors: list[str] | None,
                     logger: Logger | None) -> str:
@@ -178,35 +236,6 @@ def _get_user_data(iam_server: IamServer,
     return result
 
 
-def _get_iam_server(endpoint: str,
-                    errors: list[str] | None,
-                    logger: Logger | None) -> IamServer | None:
-    """
-    Retrieve the registered *IAM* server associated with the service's invocation *endpoint*.
-
-    :param endpoint: the service's invocation endpoint
-    :param errors: incidental error messages
-    :param logger: optional logger
-    :return: the corresponding *IAM* server, or *None* if one could not be obtained
-    """
-    # declare the return variable
-    result: IamServer | None
-
-    if endpoint.startswith("jusbr"):
-        result = IamServer.IAM_JUSRBR
-    elif endpoint.startswith("keycloak"):
-        result = IamServer.IAM_KEYCLOAK
-    else:
-        result = None
-        msg: str = f"Unable to find a IAM server to service endpoint '{endpoint}'"
-        if logger:
-            logger.error(msg=msg)
-        if isinstance(errors, list):
-            errors.append(msg)
-
-    return result
-
-
 def _get_iam_registry(iam_server: IamServer,
                       errors: list[str] | None,
                       logger: Logger | None) -> dict[str, Any]:

{pypomes_iam-0.5.0 → pypomes_iam-0.5.2}/src/pypomes_iam/iam_pomes.py

@@ -4,16 +4,34 @@ import secrets
 import string
 import sys
 from datetime import datetime
+from flask import Request, Response, request
 from logging import Logger
 from pypomes_core import TZ_LOCAL, exc_format
 from typing import Any
 
 from .iam_common import (
     IamServer, _iam_lock,
-    _get_iam_users, _get_iam_registry,
-    _get_login_timeout, _get_user_data,  # _get_public_key
+    _get_iam_users, _get_iam_registry,  # _get_public_key,
+    _get_login_timeout, _get_user_data, _iam_server_from_issuer
 )
-from .token_pomes import token_validate
+from .token_pomes import token_get_claims, token_validate
+
+
+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 user_login(iam_server: IamServer,
@@ -24,7 +42,7 @@ def user_login(iam_server: IamServer,
     Build the URL for redirecting the request to *iam_server*'s authentication page.
 
     These are the expected attributes in *args*:
-        - user-id: optional, identifies the reference user (aliases: 'user_id', 'login')
+        - 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
@@ -41,7 +59,7 @@ def user_login(iam_server: IamServer,
     result: str | None = None
 
     # obtain the optional user's identification
-    user_id: str = args.get("user-id") or args.get("user_id") or args.get("login")
+    user_id: str = args.get("user-id") or args.get("login")
 
     # build the user data
     # ('oauth_state' is a randomly-generated string, thus 'user_data' is always a new entry)
@@ -84,7 +102,7 @@ def user_logout(iam_server: IamServer,
     """
     Logout the user, by removing all data associating it from *iam_server*'s registry.
 
-    The user is identified by the attribute *user-id*, *user_id*, or "login", provided in *args*.
+    The user is identified by the attribute *user-id* or "login", provided in *args*.
     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.
 
@@ -94,7 +112,7 @@ def user_logout(iam_server: IamServer,
     :param logger: optional logger
     """
     # obtain the user's identification
-    user_id: str = args.get("user-id") or args.get("user_id") or args.get("login")
+    user_id: str = args.get("user-id") or args.get("login")
 
     if user_id:
         with _iam_lock:
@@ -115,19 +133,19 @@ def user_token(iam_server: IamServer,
     """
     Retrieve the authentication token for the user, from *iam_server*.
 
-    The user is identified by the attribute *user-id*, *user_id*, or *login*, provided in *args*.
+    The user is identified by the attribute *user-id* or *login*, provided in *args*.
 
     :param iam_server: the reference registered *IAM* server
     :param args: the arguments passed when requesting the service
     :param errors: incidental error messages
     :param logger: optional logger
-    :return: the token for *user_id*, or *None* if error
+    :return: the token for user indicated, or *None* if error
     """
     # initialize the return variable
     result: str | None = None
 
     # obtain the user's identification
-    user_id: str = args.get("user-id") or args.get("user_id") or args.get("login")
+    user_id: str = args.get("user-id") or args.get("login")
 
     err_msg: str | None = None
     if user_id:
@@ -272,7 +290,7 @@ def token_exchange(iam_server: IamServer,
     Request *iam_server* to issue a token in exchange for the token obtained from another *IAM* server.
 
     The expected parameters in *args* are:
-        - user-id: identification for the reference user (aliases: 'user_id', 'login')
+        - user-id: identification for the reference user (alias: 'login')
         - token: the token to be exchanged
 
     The typical data set returned contains the following attributes:
@@ -294,10 +312,10 @@ def token_exchange(iam_server: IamServer,
     result: dict[str, Any] | None = None
 
     # obtain the user's identification
-    user_id: str = args.get("user-id") or args.get("user_id") or args.get("login")
+    user_id: str = args.get("user-id") or args.get("login")
 
-    # obtain the token to be exchanges
-    token: str = args.get("token")
+    # obtain the token to be exchanged
+    token: str = args.get("access-token")
 
     if user_id and token:
         # HAZARD: only 'IAM_KEYCLOAK' is currently supported
@@ -339,6 +357,63 @@ def token_exchange(iam_server: IamServer,
     return result
 
 
+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.
+
+    :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=None)
+                # public_key: str = _get_public_key(iam_server=iam_server,
+                #                                   errors=errors,
+                #                                   logger=logger)
+                public_key = None
+
+                # 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=None)
+                    recipient_attr = registry["recipient-attr"]
+
+            # validate the token
+            if token_validate(token=token,
+                              issuer=issuer,
+                              recipient_id=recipient_id,
+                              recipient_attr=recipient_attr,
+                              public_key=public_key):
+                # token is valid
+                bad_token = False
+
+    # deny the authorization
+    if bad_token:
+        result = Response(response="Authorization failed",
+                          status=401)
+    return result
+
+
 def __post_for_token(iam_server: IamServer,
                      body_data: dict[str, Any],
                      errors: list[str] | None,

{pypomes_iam-0.5.0 → pypomes_iam-0.5.2}/src/pypomes_iam/iam_services.py

@@ -3,7 +3,7 @@ from flask import Request, Response, request, jsonify
 from logging import Logger
 from typing import Any
 
-from .iam_common import IamServer, _iam_lock, _get_iam_server
+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
@@ -33,7 +33,7 @@ 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 (aliases: 'user_id', 'login')
+        - 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
@@ -55,9 +55,9 @@ def service_login() -> Response:
     errors: list[str] = []
     with _iam_lock:
         # retrieve the IAM server
-        iam_server: IamServer = _get_iam_server(endpoint=request.endpoint,
-                                                errors=errors,
-                                                logger=__IAM_LOGGER)
+        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 = user_login(iam_server=iam_server,
@@ -67,8 +67,8 @@ def service_login() -> Response:
             if login_url:
                 result = jsonify({"login-url": login_url})
     if errors:
-        result = Response("; ".join(errors))
-        result.status_code = 400
+        result = Response(response="; ".join(errors),
+                          status=400)
 
     # log the response
     if __IAM_LOGGER:
@@ -85,7 +85,7 @@ def service_logout() -> Response:
     """
     Entry point for the JusBR logout service.
 
-    The user is identified by the attribute *user-id*, *user_id*, or "login", provided as a request parameter.
+    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.
 
@@ -101,9 +101,9 @@ def service_logout() -> Response:
     errors: list[str] = []
     with _iam_lock:
         # retrieve the IAM server
-        iam_server: IamServer = _get_iam_server(endpoint=request.endpoint,
-                                                errors=errors,
-                                                logger=__IAM_LOGGER)
+        iam_server: IamServer = _iam_server_from_endpoint(endpoint=request.endpoint,
+                                                          errors=errors,
+                                                          logger=__IAM_LOGGER)
         if iam_server:
             # logout the user
             user_logout(iam_server=iam_server,
@@ -111,8 +111,8 @@ def service_logout() -> Response:
                         errors=errors,
                         logger=__IAM_LOGGER)
     if errors:
-        result = Response("; ".join(errors))
-        result.status_code = 400
+        result = Response(response="; ".join(errors),
+                          status=400)
     else:
         result = Response(status=204)
 
@@ -142,7 +142,7 @@ def service_callback() -> Response:
     On success, the returned *Response* will contain the following JSON:
         {
             "user-id": <reference-user-identification>,
-            "token": <token>
+            "access-token": <token>
         }
 
     :return: *Response* containing the reference user identification and the token, or *BAD REQUEST*
@@ -155,9 +155,9 @@ def service_callback() -> Response:
     token_data: tuple[str, str] | None = None
     with _iam_lock:
         # retrieve the IAM server
-        iam_server: IamServer = _get_iam_server(endpoint=request.endpoint,
-                                                errors=errors,
-                                                logger=__IAM_LOGGER)
+        iam_server: IamServer = _iam_server_from_endpoint(endpoint=request.endpoint,
+                                                          errors=errors,
+                                                          logger=__IAM_LOGGER)
         if iam_server:
             # process the callback operation
             token_data = login_callback(iam_server=iam_server,
@@ -170,7 +170,7 @@ def service_callback() -> Response:
         result.status_code = 400
     else:
         result = jsonify({"user-id": token_data[0],
-                          "token": token_data[1]})
+                          "access-token": token_data[1]})
     # log the response
     if __IAM_LOGGER:
         __IAM_LOGGER.debug(msg=f"Response {result}, {result.get_data(as_text=True)}")
@@ -186,12 +186,12 @@ def service_token() -> Response:
     """
     Entry point for retrieving a token from the *IAM* server.
 
-    The user is identified by the attribute *user-id*, *user_id*, or "login", provided as a request parameter.
+    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>,
-            "token": <token>
+            "access-token": <token>
         }
 
     :return: *Response* containing the user reference identification and the token, or *BAD REQUEST*
@@ -202,16 +202,16 @@ def service_token() -> Response:
 
     # obtain the user's identification
     args: dict[str, Any] = request.args
-    user_id: str = args.get("user-id") or args.get("user_id") or args.get("login")
+    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 = _get_iam_server(endpoint=request.endpoint,
-                                                    errors=errors,
-                                                    logger=__IAM_LOGGER)
+            iam_server: IamServer = _iam_server_from_endpoint(endpoint=request.endpoint,
+                                                              errors=errors,
+                                                              logger=__IAM_LOGGER)
             if iam_server:
                 # retrieve the token
                 errors: list[str] = []
@@ -227,11 +227,11 @@ def service_token() -> Response:
 
     result: Response
     if errors:
-        result = Response("; ".join(errors))
-        result.status_code = 400
+        result = Response(response="; ".join(errors),
+                          status=400)
     else:
         result = jsonify({"user-id": user_id,
-                          "token": token})
+                          "access-token": token})
     # log the response
     if __IAM_LOGGER:
         __IAM_LOGGER.debug(msg=f"Response {result}, {result.get_data(as_text=True)}")
@@ -247,8 +247,8 @@ def service_exchange() -> Response:
 
     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 (aliases: 'user_id', 'login')
-        - token: the token to be exchanged
+        - 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.
@@ -271,9 +271,9 @@ def service_exchange() -> Response:
     errors: list[str] = []
     with _iam_lock:
         # retrieve the IAM server (currently, only 'IAM_KEYCLOAK' is supported)
-        iam_server: IamServer = _get_iam_server(endpoint=request.endpoint,
-                                                errors=errors,
-                                                logger=__IAM_LOGGER)
+        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:
@@ -284,8 +284,8 @@ def service_exchange() -> Response:
                                         logger=__IAM_LOGGER)
     result: Response
     if errors:
-        result = Response("; ".join(errors))
-        result.status_code = 400
+        result = Response(response="; ".join(errors),
+                          status=400)
     else:
         result = jsonify(token_data)
 

{pypomes_iam-0.5.0 → pypomes_iam-0.5.2}/src/pypomes_iam/jusbr_pomes.py

@@ -24,6 +24,7 @@ JUSBR_ENDPOINT_TOKEN: Final[str] = env_get_str(key=f"{APP_PREFIX}_JUSBR_ENDPOINT
 
 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")
@@ -31,6 +32,7 @@ JUSBR_URL_AUTH_BASE: Final[str] = env_get_str(key=f"{APP_PREFIX}_JUSBR_URL_AUTH_
 
 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,
@@ -47,6 +49,7 @@ def jusbr_setup(flask_app: Flask,
 
     :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)
@@ -64,7 +67,7 @@ def jusbr_setup(flask_app: Flask,
     cache["users"] = {}
     with _iam_lock:
         _IAM_SERVERS[IamServer.IAM_JUSRBR] = {
-            "base-url": base_url,
+            "base-url": f"{base_url}/realms/{realm}",
             "client-id": client_id,
             "client-secret": client_secret,
             "client-timeout": client_timeout,

{pypomes_iam-0.5.0 → pypomes_iam-0.5.2}/src/pypomes_iam/token_pomes.py

@@ -7,6 +7,45 @@ from pypomes_core import exc_format
 from typing import Any
 
 
+def token_get_claims(token: str,
+                     errors: list[str] = None,
+                     logger: Logger = None) -> dict[str, dict[str, Any]] | None:
+    """
+    Retrieve the claims set of a JWT *token*.
+
+    Any well-constructed JWT token may be provided in *token*.
+    Note that neither the token's signature nor its expiration is verified.
+
+    :param token: the refrence token
+    :param errors: incidental error messages
+    :param logger: optional logger
+    :return: the token's claimset, or *None* if error
+    """
+    # initialize the return variable
+    result: dict[str, dict[str, Any]] | None = None
+
+    if logger:
+        logger.debug(msg="Retrieve claims for token")
+
+    try:
+        header: dict[str, Any] = jwt.get_unverified_header(jwt=token)
+        payload: dict[str, Any] = jwt.decode(jwt=token,
+                                             options={"verify_signature": False})
+        result = {
+            "header": 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 retrieving the token's claims: {exc_err}")
+        if isinstance(errors, list):
+            errors.append(exc_err)
+
+    return result
+
+
 def token_validate(token: str,
                    issuer: str = None,
                    recipient_id: str = None,