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

pypomes_iam/iam_services.py

@@ -9,8 +9,8 @@ from .iam_common import (
     _iam_server_from_endpoint, _iam_server_from_issuer
 )
 from .iam_actions import (
-    action_login, action_logout,
-    action_token, action_exchange, action_callback
+    iam_login, iam_logout,
+    iam_get_token, iam_exchange, iam_callback
 )
 from .token_pomes import token_get_claims, token_validate
 
@@ -23,7 +23,10 @@ def jwt_required(func: callable) -> callable:
     """
     Create a decorator to authenticate service endpoints with JWT tokens.
 
+    The decorated function must be a registered endpoint to a *Flask* application.
+
     :param func: the function being decorated
+    :return: the return from the call to *func*, or a *Response NOT AUTHORIZED* if the authentication failed
     """
     # ruff: noqa: ANN003 - Missing type annotation for *{name}
     def wrapper(*args, **kwargs) -> Response:
@@ -60,6 +63,7 @@ def __request_validate(request: Request) -> Response:
         claims: dict[str, Any] = token_get_claims(token=token)
         if claims:
             issuer: str = claims["payload"].get("iss")
+            public_key: str | None = None
             recipient_attr: str | None = None
             recipient_id: str = request.values.get("user-id") or request.values.get("login")
             with _iam_lock:
@@ -74,17 +78,17 @@ def __request_validate(request: Request) -> Response:
                                                                      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)
+                    public_key = _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):
+            if 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:
@@ -99,7 +103,7 @@ def __request_validate(request: Request) -> Response:
     return result
 
 
-def logger_register(logger: Logger) -> None:
+def iam_setup_logger(logger: Logger) -> None:
     """
     Register the logger for HTTP services.
 
@@ -109,17 +113,71 @@ def logger_register(logger: Logger) -> None:
     __IAM_LOGGER = logger
 
 
-# @flask_app.route(rule=<login_endpoint>,  # JUSBR_ENDPOINT_LOGIN
-#                  methods=["GET"])
-# @flask_app.route(rule=<login_endpoint>,  # KEYCLOAK_ENDPOINT_LOGIN
+# @flask_app.route(rule=<setup_server_endpoint>,
+#                  methods=["POST"])
+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*)
+        - *admin_id*: identifies the realm administrator
+        - *admin_secret*: password for the realm administrator
+        - *client_id*: the client's identification with the *IAM* server
+        - *client_realm*: the client's realm
+        - *client_secret*: the client's password with the *IAM* server
+        - *login_timeout*: timeout for login authentication (in seconds,defaults to no timeout)
+        - *k_lifetime*: how long to use *IAM* server's public key, before refreshing it (in seconds)
+        - *recipient_attr*: attribute in the token's payload holding the token's subject
+        - *rl_base*: base URL to request services
+
+    For the parameters not effectively passed, an attempt is made to obtain a value from the corresponding
+    environment variables. Most parameters are required to have values, which must be assigned either
+    throught the function invocation, or from the corresponding environment variables.
+
+    The parameters *admin_id* and *admin_secret* are required only if performing administrative tasks is intended.
+    The optional parameter *ogin_timeout* refers to the maximum time in seconds allowed for the user
+    to login at the *IAM* server's login page, and defaults to no time limit.
+
+    The parameter *client_secret* is required in most requests to the *IAM* server. In the case
+    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.
+
+    :return: *Response OK*
+    """
+    # 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
+
+    # setup the server
+    from .iam_pomes import iam_setup_server
+    iam_setup_server(**args)
+    result = Response(status=200)
+
+    # log the response
+    if __IAM_LOGGER:
+        __IAM_LOGGER.debug(msg=f"Response {result}")
+
+    return result
+
+
+# @flask_app.route(rule=<login_endpoint>,  # IAM_ENDPOINT_LOGIN
 #                  methods=["GET"])
 def service_login() -> Response:
     """
-    Entry point for the IAM server's login service.
+    Entry point for the *IAM* server's login service.
+
+    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()*.
 
     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
+        -target-idp: optionally, identify a target identity provider for the login operation
 
     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
@@ -145,10 +203,10 @@ def service_login() -> Response:
                                                           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)
+            login_url: str = iam_login(iam_server=iam_server,
+                                       args=request.args,
+                                       errors=errors,
+                                       logger=__IAM_LOGGER)
             if login_url:
                 result = jsonify({"login-url": login_url})
     if errors:
@@ -157,18 +215,20 @@ def service_login() -> Response:
 
     # log the response
     if __IAM_LOGGER:
-        __IAM_LOGGER.debug(msg=f"Response {result}, {result.get_data(as_text=True)}")
+        __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
+# @flask_app.route(rule=<logout_endpoint>,  # IAM_ENDPOINT_LOGOUT
 #                  methods=["GET"])
 def service_logout() -> Response:
     """
-    Entry point for the IAM server's logout service.
+    Entry point for the *IAM* server's logout service.
+
+    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.
     If successful, remove all data relating to the user from the *IAM* server's registry.
@@ -191,30 +251,32 @@ def service_logout() -> Response:
                                                           logger=__IAM_LOGGER)
         if iam_server:
             # logout the user
-            action_logout(iam_server=iam_server,
-                          args=request.args,
-                          errors=errors,
-                          logger=__IAM_LOGGER)
+            iam_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:
+        # log the response
         __IAM_LOGGER.debug(msg=f"Response {result}")
 
     return result
 
 
-# @flask_app.route(rule=<callback_endpoint>,  # JUSBR_ENDPOINT_CALLBACK
+# @flask_app.route(rule=<callback_endpoint>,  # IAM_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.
+    Entry point for the callback from the *IAM* server on authentication operation.
+
+    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()*.
 
     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,
@@ -245,10 +307,10 @@ def service_callback() -> Response:
                                                           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)
+            token_data = iam_callback(iam_server=iam_server,
+                                      args=request.args,
+                                      errors=errors,
+                                      logger=__IAM_LOGGER)
     result: Response
     if errors:
         result = jsonify({"errors": "; ".join(errors)})
@@ -263,60 +325,131 @@ def service_callback() -> Response:
     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:
+# @flask_app.route(rule=<callback_endpoint>,  # KEYCLOAK_ENDPOINT_EXCHANGE
+#                  methods=["POST"])
+def service_exchange() -> Response:
     """
-    Entry point for retrieving a token from the *IAM* server.
+    Entry point for requesting the *IAM* server to exchange the token.
 
-    The user is identified by the attribute *user-id* or "login", provided as a request parameter.
+    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()*.
+
+    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.
+
+    The expected request parameters are:
+        - user-id: identification for the reference user (alias: 'login')
+        - access-token: the token to be exchanged
 
     On success, the returned *Response* will contain the following JSON:
         {
             "user-id": <reference-user-identification>,
-            "access-token": <token>
+            "access-token": <the-exchanged-token>
         }
 
-    :return: *Response* containing the user reference identification and the token, or *BAD REQUEST*
+    :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))
 
-    # 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)
-
+    with _iam_lock:
+        # retrieve the IAM server
+        iam_server: IamServer = _iam_server_from_endpoint(endpoint=request.endpoint,
+                                                          errors=errors,
+                                                          logger=__IAM_LOGGER)
+        # exchange the token
+        token_info: tuple[str, str] | None = None
+        if iam_server:
+            errors: list[str] = []
+            token_info = iam_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({"user-id": user_id,
-                          "access-token": token})
+        result = jsonify({"user-id": token_info[0],
+                          "access-token": token_info[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}; {result.get_data(as_text=True)}")
+
+    return result
+
+
+# @flask_app.route(rule=/iam/jusbr:callback-exchange,
+#                  methods=["GET"])
+def service_callback_exchange() -> Response:
+    """
+    Entry point for the callback from the IAM server on authentication operation, with subsequent token exchange.
+
+    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, and suffixed with the string *_to_*
+    followed by the name of the *IAM* server in charge of the token exchange. The prefixing, but not the suffixing,
+    is done automatically if the endpoint is established with a call to *iam_setup_endpoints()*.
+
+    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.
+    This token is stored and thereafter, a corresponding token is requested from another IAM *server*,
+    in a scheme known as "token exchange". This new token, along with the reference user identification,
+    are then stored. Note that the original token is the one actually returned.
+
+    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": <the-original-token>
+        }
+
+    :return: *Response* containing the reference user identification and the token, or *BAD REQUEST*
+    """
+    # 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)
+        # obtain the login URL
+        token_info: tuple[str,  str] = iam_callback(iam_server=iam_server,
+                                                    args=request.args,
+                                                    errors=errors,
+                                                    logger=__IAM_LOGGER)
+        if token_info:
+            args: dict[str, str] = {
+                "user-id": token_info[0],
+                "access-token": token_info[1]
+            }
+            # retrieve the exchange IAM server
+            pos: int = request.endpoint.index("_to_")
+            exchange_server: IamServer = _iam_server_from_endpoint(endpoint=request.endpoint[pos+4],
+                                                                   errors=errors,
+                                                                   logger=__IAM_LOGGER)
+            token_info = iam_exchange(iam_server=exchange_server,
+                                      args=args,
+                                      logger=__IAM_LOGGER)
+            if token_info:
+                result = jsonify({"user-id": token_info[0],
+                                  "access-token": token_info[1]})
+    if errors:
+        result = Response("; ".join(errors))
+        result.status_code = 400
+
     if __IAM_LOGGER:
         # log the response (the returned data is not logged, as it contains the token)
         __IAM_LOGGER.debug(msg=f"Response {result}")
@@ -324,19 +457,17 @@ def service_token() -> Response:
     return result
 
 
-# @flask_app.route(rule=<callback_endpoint>,  # KEYCLOAK_ENDPOINT_EXCHANGE
-#                  methods=["POST"])
-def service_exchange() -> Response:
+# @flask_app.route(rule=<token_endpoint>,  # IAM_ENDPOINT_TOKEN
+#                  methods=["GET"])
+def service_get_token() -> Response:
     """
-    Entry point for requesting the *IAM* server to exchange the token.
+    Entry point for retrieving a token from the *IAM* server.
 
-    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
+    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()*.
 
-    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.
+    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:
         {
@@ -344,37 +475,38 @@ def service_exchange() -> Response:
             "access-token": <token>
         }
 
-    :return: *Response* containing the token data, or *BAD REQUEST*
+    :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 request arguments
+    args: dict[str, Any] = request.args
+
     errors: list[str] = []
+    token_info: dict[str, str] | None = None
     with _iam_lock:
-        # retrieve the IAM server (currently, only 'IAM_KEYCLOAK' is supported)
+        # retrieve the IAM server
         iam_server: IamServer = _iam_server_from_endpoint(endpoint=request.endpoint,
                                                           errors=errors,
                                                           logger=__IAM_LOGGER)
-        # exchange the token
-        token_info: tuple[str, str] | None = None
         if iam_server:
+            # retrieve the token
             errors: list[str] = []
-            token_info = action_exchange(iam_server=iam_server,
-                                         args=request.args,
-                                         errors=errors,
-                                         logger=__IAM_LOGGER)
+            token_info = iam_get_token(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-id": token_info[0],
-                          "access-token": token_info[1]})
-
-    # log the response
+        result = jsonify(token_info)
     if __IAM_LOGGER:
-        __IAM_LOGGER.debug(msg=f"Response {result}, {result.get_data(as_text=True)}")
+        # log the response (the returned data is not logged, as it contains the token)
+        __IAM_LOGGER.debug(msg=f"Response {result}")
 
     return result