pypomes-iam 0.8.0__py3-none-any.whl → 0.8.9__py3-none-any.whl

pypomes_iam/iam_pomes.py

@@ -6,11 +6,12 @@ from pypomes_core import (
 )
 
 from .iam_common import (
-    _IAM_SERVERS, IamServer, IamParam, _iam_lock
+    _IAM_SERVERS, IamServer, ServerParam, _iam_lock
 )
 from .iam_services import (
     service_login, service_logout,
-    service_callback, service_callback_exchange, service_exchange, service_get_token
+    service_callback, service_callback_exchange,
+    service_exchange, service_get_token, service_userinfo
 )
 
 
@@ -40,7 +41,7 @@ def iam_setup_server(iam_server: IamServer,
     it is not provided, but *admin_id* and *admin_secret* are, it is obtained from the *IAM* server itself
     the first time it is needed.
 
-    :param iam_server: identifies the supported *IAM* server (currently, *jusbr* or *keycloak*)
+    :param iam_server: identifies the supported *IAM* server
     :param admin_id: identifies the realm administrator
     :param admin_secret: password for the realm administrator
     :param client_id: the client's identification with the *IAM* server
@@ -69,28 +70,28 @@ def iam_setup_server(iam_server: IamServer,
     if "login_timeout" in defaulted_params:
         login_timeout = env_get_str(key=f"{APP_PREFIX}_{prefix}_LOGIN_TIMEOUT")
     if "pk_lifetime" in defaulted_params:
-        pk_lifetime = env_get_int(key=f"{APP_PREFIX}_{prefix}_PUBLIC_KEY_LIFETIME")
+        pk_lifetime = env_get_int(key=f"{APP_PREFIX}_{prefix}_PK_LIFETIME")
     if "recipient_attr" in defaulted_params:
         recipient_attr = env_get_str(key=f"{APP_PREFIX}_{prefix}_RECIPIENT_ATTR")
     if "url_base" in defaulted_params:
-        url_base = env_get_str(key=f"{APP_PREFIX}_{prefix}_URL_AUTH_BASE")
+        url_base = env_get_str(key=f"{APP_PREFIX}_{prefix}_URL_BASE")
 
-    # configure the Keycloak registry
+    # configure the IAM server's registry
     with _iam_lock:
         _IAM_SERVERS[iam_server] = {
-            IamParam.CLIENT_ID: client_id,
-            IamParam.CLIENT_REALM: client_realm,
-            IamParam.CLIENT_SECRET: client_secret,
-            IamParam.RECIPIENT_ATTR: recipient_attr,
-            IamParam.ADMIN_ID: admin_id,
-            IamParam.ADMIN_SECRET: admin_secret,
-            IamParam.LOGIN_TIMEOUT: login_timeout,
-            IamParam.PK_LIFETIME: pk_lifetime,
-            IamParam.URL_BASE: url_base,
+            ServerParam.CLIENT_ID: client_id,
+            ServerParam.CLIENT_REALM: client_realm,
+            ServerParam.CLIENT_SECRET: client_secret,
+            ServerParam.RECIPIENT_ATTR: recipient_attr,
+            ServerParam.ADMIN_ID: admin_id,
+            ServerParam.ADMIN_SECRET: admin_secret,
+            ServerParam.LOGIN_TIMEOUT: login_timeout,
+            ServerParam.PK_LIFETIME: pk_lifetime,
+            ServerParam.URL_BASE: url_base,
             # dynamic attributes
-            IamParam.PK_EXPIRATION: 0,
-            IamParam.PUBLIC_KEY: None,
-            IamParam.USERS: {}
+            ServerParam.PK_EXPIRATION: 0,
+            ServerParam.PUBLIC_KEY: None,
+            ServerParam.USERS: {}
         }
 
 
@@ -102,7 +103,8 @@ def iam_setup_endpoints(flask_app: Flask,
                         exchange_endpoint: str = None,
                         login_endpoint: str = None,
                         logout_endpoint: str = None,
-                        token_endpoint: str = None) -> None:
+                        token_endpoint: str = None,
+                        userinfo_endpoint: str = None) -> None:
     """
     Setup the endpoints for accessing the services provided by *iam_server*.
 
@@ -110,13 +112,14 @@ def iam_setup_endpoints(flask_app: Flask,
     environment variables.
 
     :param flask_app: the Flask application
-    :param iam_server: identifies the supported *IAM* server (currently, *jusbr* or *keycloak*)
+    :param iam_server: identifies the supported *IAM* server
     :param callback_endpoint: endpoint for the callback from the front end
     :param callback_exchange_endpoint: endpoint for the combination callback and exchange
     :param exchange_endpoint: endpoint for requesting token exchange
     :param login_endpoint: endpoint for redirecting user to the *IAM* server's login page
     :param logout_endpoint: endpoint for terminating user access
     :param token_endpoint: endpoint for retrieving authentication token
+    :param userinfo_endpoint: endpoint for retrieving user data
     """
     # obtain the defaulted parameters
     defaulted_params: list[str] = func_defaulted_params.get()
@@ -128,20 +131,22 @@ def iam_setup_endpoints(flask_app: Flask,
     if "callback_exchange_endpoint" in defaulted_params:
         callback_exchange_endpoint = env_get_str(key=f"{APP_PREFIX}_{prefix}_ENDPOINT_CALLBACK_EXCHANGE")
     if "exchange_endpoint" in defaulted_params:
-        callback_endpoint = env_get_str(key=f"{APP_PREFIX}_{prefix}_ENDPOINT_EXCHANGE")
+        exchange_endpoint = env_get_str(key=f"{APP_PREFIX}_{prefix}_ENDPOINT_EXCHANGE")
     if "login_endpoint" in defaulted_params:
         login_endpoint = env_get_str(key=f"{APP_PREFIX}_{prefix}_ENDPOINT_LOGIN")
     if "logout_endpoint" in defaulted_params:
         logout_endpoint = env_get_str(key=f"{APP_PREFIX}_{prefix}_ENDPOINT_LOGOUT")
     if "token_endpoint" in defaulted_params:
         token_endpoint = env_get_str(key=f"{APP_PREFIX}_{prefix}_ENDPOINT_TOKEN")
+    if "userinfo_endpoint" in defaulted_params:
+        userinfo_endpoint = env_get_str(key=f"{APP_PREFIX}_{prefix}_ENDPOINT_USERINFO")
 
     # establish the endpoints
     if callback_endpoint:
         flask_app.add_url_rule(rule=callback_endpoint,
                                endpoint=f"{iam_server}-callback",
                                view_func=service_callback,
-                               methods=["GET"])
+                               methods=["GET", "POST"])
     if callback_exchange_endpoint:
         flask_app.add_url_rule(rule=callback_exchange_endpoint,
                                endpoint=f"{iam_server}-callback-exchange",
@@ -161,9 +166,14 @@ def iam_setup_endpoints(flask_app: Flask,
         flask_app.add_url_rule(rule=logout_endpoint,
                                endpoint=f"{iam_server}-logout",
                                view_func=service_logout,
-                               methods=["GET"])
+                               methods=["POST"])
     if token_endpoint:
         flask_app.add_url_rule(rule=token_endpoint,
                                endpoint=f"{iam_server}-token",
                                view_func=service_get_token,
                                methods=["GET"])
+    if userinfo_endpoint:
+        flask_app.add_url_rule(rule=userinfo_endpoint,
+                               endpoint=f"{iam_server}-userinfo",
+                               view_func=service_userinfo,
+                               methods=["GET"])

pypomes_iam/iam_services.py

@@ -4,13 +4,13 @@ from logging import Logger
 from typing import Any
 
 from .iam_common import (
-    IamServer, IamParam, _iam_lock,
+    IamServer, ServerParam, _iam_lock,
     _get_iam_registry, _get_public_key,
     _iam_server_from_endpoint, _iam_server_from_issuer
 )
 from .iam_actions import (
-    iam_login, iam_logout,
-    iam_get_token, iam_exchange, iam_callback
+    iam_login, iam_logout, iam_callback,
+    iam_exchange, iam_get_token, iam_userinfo
 )
 from .token_pomes import token_get_claims, token_validate
 
@@ -47,19 +47,16 @@ def __request_validate(request: Request) -> Response:
     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
+    :return: *None* if the *request* is valid, otherwise a *Response NOT AUTHORIZED*
     """
     # 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]
+    token: str = __get_bearer_token(request=request)
+    if token:
+        # extract token claims
         claims: dict[str, Any] = token_get_claims(token=token)
         if claims:
             issuer: str = claims["payload"].get("iss")
@@ -77,7 +74,7 @@ def __request_validate(request: Request) -> Response:
                                                                      errors=None,
                                                                      logger=__IAM_LOGGER)
                         if registry:
-                            recipient_attr = registry[IamParam.RECIPIENT_ATTR]
+                            recipient_attr = registry[ServerParam.RECIPIENT_ATTR]
                     public_key = _get_public_key(iam_server=iam_server,
                                                  errors=None,
                                                  logger=__IAM_LOGGER)
@@ -103,6 +100,26 @@ def __request_validate(request: Request) -> Response:
     return result
 
 
+def __get_bearer_token(request: Request) -> str:
+    """
+    Retrieve the bearer token sent in the header of *request*.
+
+    This implementation assumes that HTTP requests are handled with the *Flask* framework.
+
+    :param request: the *request* to retrieve the token from
+    :return: the bearer token, or *None* if not found
+    """
+    # initialize the return variable
+    result: str | None = None
+
+    # retrieve the authorization from the request header
+    auth_header: str = request.headers.get("Authorization")
+    if auth_header and auth_header.startswith("Bearer "):
+        result: str = auth_header.split(" ")[1]
+
+    return result
+
+
 def iam_setup_logger(logger: Logger) -> None:
     """
     Register the logger for HTTP services.
@@ -120,7 +137,7 @@ def service_setup_server() -> Response:
     Entry point to setup a *IAM* server.
 
     These are the expected parameters in the request's body, in a JSON or as form data:
-        - *iam_server*: identifies the supported *IAM* server (currently, *jusbr* or *keycloak*)
+        - *iam_server*: identifies the supported *IAM* server
         - *admin_id*: identifies the realm administrator
         - *admin_secret*: password for the realm administrator
         - *client_id*: the client's identification with the *IAM* server
@@ -145,13 +162,13 @@ def service_setup_server() -> Response:
 
     :return: *Response OK*
     """
+    # retrieve the request arguments
+    args: dict[str, Any] = (dict(request.json) if request.is_json else dict(request.form)) or {}
+
     # log the request
     if __IAM_LOGGER:
-        __IAM_LOGGER.debug(msg=f"{_log_init(request=request)}; {json.dumps(obj=request.args,
-                                                                           ensure_ascii=False)}")
-    # retrieve the arguments
-    args: dict[str, Any] = request.json if request.is_json else request.form
-
+        __IAM_LOGGER.debug(msg=f"Request {request.method}:{request.path}; {json.dumps(obj=args,
+                                                                                      ensure_ascii=False)}")
     # setup the server
     from .iam_pomes import iam_setup_server
     iam_setup_server(**args)
@@ -164,7 +181,7 @@ def service_setup_server() -> Response:
     return result
 
 
-# @flask_app.route(rule=<login_endpoint>,  # IAM_ENDPOINT_LOGIN
+# @flask_app.route(rule=<login_endpoint>,
 #                  methods=["GET"])
 def service_login() -> Response:
     """
@@ -191,10 +208,13 @@ def service_login() -> Response:
     # declare the return variable
     result: Response | None = None
 
+    # retrieve the request arguments
+    args: dict[str, Any] = dict(request.args) or {}
+
     # log the request
     if __IAM_LOGGER:
-        __IAM_LOGGER.debug(msg=_log_init(request=request))
-
+        __IAM_LOGGER.debug(msg=f"Request {request.method}:{request.path}; {json.dumps(obj=args,
+                                                                                      ensure_ascii=False)}")
     errors: list[str] = []
     with _iam_lock:
         # retrieve the IAM server
@@ -204,7 +224,7 @@ def service_login() -> Response:
         if iam_server:
             # obtain the login URL
             login_url: str = iam_login(iam_server=iam_server,
-                                       args=request.args,
+                                       args=args,
                                        errors=errors,
                                        logger=__IAM_LOGGER)
             if login_url:
@@ -220,8 +240,9 @@ def service_login() -> Response:
     return result
 
 
-# @flask_app.route(rule=<logout_endpoint>,  # IAM_ENDPOINT_LOGOUT
-#                  methods=["GET"])
+# @flask_app.route(rule=<logout_endpoint>,
+#                  methods=["POST"])
+@jwt_required
 def service_logout() -> Response:
     """
     Entry point for the *IAM* server's logout service.
@@ -239,10 +260,13 @@ def service_logout() -> Response:
     # declare the return variable
     result: Response | None
 
+    # retrieve the request arguments
+    args: dict[str, Any] = dict(request.args) or {}
+
     # log the request
     if __IAM_LOGGER:
-        __IAM_LOGGER.debug(msg=_log_init(request=request))
-
+        __IAM_LOGGER.debug(msg=f"Request {request.method}:{request.path}; {json.dumps(obj=args,
+                                                                                      ensure_ascii=False)}")
     errors: list[str] = []
     with _iam_lock:
         # retrieve the IAM server
@@ -252,7 +276,7 @@ def service_logout() -> Response:
         if iam_server:
             # logout the user
             iam_logout(iam_server=iam_server,
-                       args=request.args,
+                       args=args,
                        errors=errors,
                        logger=__IAM_LOGGER)
     if errors:
@@ -268,7 +292,7 @@ def service_logout() -> Response:
     return result
 
 
-# @flask_app.route(rule=<callback_endpoint>,  # IAM_ENDPOINT_CALLBACK
+# @flask_app.route(rule=<callback_endpoint>,
 #                  methods=["GET", "POST"])
 def service_callback() -> Response:
     """
@@ -294,10 +318,13 @@ def service_callback() -> Response:
 
     :return: *Response* containing the reference user identification and the token, or *BAD REQUEST*
     """
+    # retrieve the request arguments
+    args: dict[str, Any] = dict(request.args) or {}
+
     # log the request
     if __IAM_LOGGER:
-        __IAM_LOGGER.debug(msg=_log_init(request=request))
-
+        __IAM_LOGGER.debug(msg=f"Request {request.method}:{request.path}; {json.dumps(obj=args,
+                                                                                      ensure_ascii=False)}")
     errors: list[str] = []
     token_data: tuple[str, str] | None = None
     with _iam_lock:
@@ -308,7 +335,7 @@ def service_callback() -> Response:
         if iam_server:
             # process the callback operation
             token_data = iam_callback(iam_server=iam_server,
-                                      args=request.args,
+                                      args=args,
                                       errors=errors,
                                       logger=__IAM_LOGGER)
     result: Response
@@ -325,7 +352,7 @@ def service_callback() -> Response:
     return result
 
 
-# @flask_app.route(rule=<callback_endpoint>,  # KEYCLOAK_ENDPOINT_EXCHANGE
+# @flask_app.route(rule=<callback_endpoint>,
 #                  methods=["POST"])
 def service_exchange() -> Response:
     """
@@ -350,10 +377,13 @@ def service_exchange() -> Response:
 
     :return: *Response* containing the reference user identification and the token, or *BAD REQUEST*
     """
+    # retrieve the request arguments
+    args: dict[str, Any] = dict(request.args) or {}
+
     # log the request
     if __IAM_LOGGER:
-        __IAM_LOGGER.debug(msg=_log_init(request=request))
-
+        __IAM_LOGGER.debug(msg=f"Request {request.method}:{request.path}; {json.dumps(obj=args,
+                                                                                      ensure_ascii=False)}")
     errors: list[str] = []
     with _iam_lock:
         # retrieve the IAM server
@@ -365,7 +395,7 @@ def service_exchange() -> Response:
         if iam_server:
             errors: list[str] = []
             token_info = iam_exchange(iam_server=iam_server,
-                                      args=request.args,
+                                      args=args,
                                       errors=errors,
                                       logger=__IAM_LOGGER)
     result: Response
@@ -415,10 +445,13 @@ def service_callback_exchange() -> Response:
     # declare the return variable
     result: Response | None = None
 
+    # retrieve the request arguments
+    args: dict[str, Any] = dict(request.args) or {}
+
     # log the request
     if __IAM_LOGGER:
-        __IAM_LOGGER.debug(msg=_log_init(request=request))
-
+        __IAM_LOGGER.debug(msg=f"Request {request.method}:{request.path}; {json.dumps(obj=args,
+                                                                                      ensure_ascii=False)}")
     errors: list[str] = []
     with _iam_lock:
         # retrieve the IAM server
@@ -427,7 +460,7 @@ def service_callback_exchange() -> Response:
                                                           logger=__IAM_LOGGER)
         # obtain the login URL
         token_info: tuple[str,  str] = iam_callback(iam_server=iam_server,
-                                                    args=request.args,
+                                                    args=args,
                                                     errors=errors,
                                                     logger=__IAM_LOGGER)
         if token_info:
@@ -457,7 +490,7 @@ def service_callback_exchange() -> Response:
     return result
 
 
-# @flask_app.route(rule=<token_endpoint>,  # IAM_ENDPOINT_TOKEN
+# @flask_app.route(rule=<token_endpoint>,
 #                  methods=["GET"])
 def service_get_token() -> Response:
     """
@@ -477,13 +510,13 @@ def service_get_token() -> Response:
 
     :return: *Response* containing the user reference identification and the token, or *BAD REQUEST*
     """
+    # retrieve the request arguments
+    args: dict[str, Any] = dict(request.args) or {}
+
     # log the request
     if __IAM_LOGGER:
-        __IAM_LOGGER.debug(msg=_log_init(request=request))
-
-    # obtain the request arguments
-    args: dict[str, Any] = request.args
-
+        __IAM_LOGGER.debug(msg=f"Request {request.method}:{request.path}; {json.dumps(obj=args,
+                                                                                      ensure_ascii=False)}")
     errors: list[str] = []
     token_info: dict[str, str] | None = None
     with _iam_lock:
@@ -511,14 +544,55 @@ def service_get_token() -> Response:
     return result
 
 
-def _log_init(request: Request) -> str:
+# @flask_app.route(rule=<token_endpoint>,
+#                  methods=["GET"])
+@jwt_required
+def service_userinfo() -> Response:
     """
-    Build the messages for logging the request entry.
+    Entry point for retrieving user data from the *IAM* server.
 
-    :param request: the Request object
-    :return: the log message
+    When registering this endpoint, the name used in *Flask*'s *endpoint* parameter must be prefixed with
+    the name of the *IAM* server in charge of handling this service. This prefixing is done automatically
+    if the endpoint is established with a call to *iam_setup_endpoints()*.
+
+    The user is identified by the attribute *user-id* or "login", provided as a request parameter.
+
+    On success, the returned *Response* will contain a JSON with information kept by *iam_server* about *user_id*.
+
+    :return: *Response* containing user data, or *BAD REQUEST*
     """
+    # retrieve the request arguments
+    args: dict[str, Any] = dict(request.args) or {}
 
-    params: str = json.dumps(obj=request.args,
-                             ensure_ascii=False)
-    return f"Request {request.method}:{request.path}, params {params}"
+    # log the request
+    if __IAM_LOGGER:
+        __IAM_LOGGER.debug(msg=f"Request {request.method}:{request.path}; {json.dumps(obj=args,
+                                                                                      ensure_ascii=False)}")
+    # retrieve the bearer token
+    args["access-token"] = __get_bearer_token(request=request)
+
+    errors: list[str] = []
+    user_info: dict[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:
+            # retrieve the token
+            errors: list[str] = []
+            user_info = iam_userinfo(iam_server=iam_server,
+                                     args=args,
+                                     errors=errors,
+                                     logger=__IAM_LOGGER)
+    result: Response
+    if errors:
+        result = Response(response="; ".join(errors),
+                          status=400)
+    else:
+        result = jsonify(user_info)
+    if __IAM_LOGGER:
+        # log the response
+        __IAM_LOGGER.debug(msg=f"Response {result}; {json.dumps(obj=user_info,
+                                                                ensure_ascii=False)}")
+    return result