pypomes-iam 0.7.4__py3-none-any.whl → 0.8.3__py3-none-any.whl

pypomes_iam/__init__.py

@@ -1,37 +1,45 @@
 from .iam_actions import (
-    action_callback, action_exchange,
-    action_login, action_logout, action_token
+    iam_callback, iam_exchange,
+    iam_login, iam_logout, iam_get_token, iam_userinfo
 )
 from .iam_common import (
     IamServer, IamParam
 )
 from .iam_pomes import (
-    iam_setup, iam_get_env_parameters, iam_get_token
+    iam_setup_server, iam_setup_endpoints
 )
 from .iam_services import (
-     jwt_required, logger_register
+    jwt_required, iam_setup_logger,
+    service_setup_server, service_login, service_logout,
+    service_get_token, service_userinfo, service_callback,
+    service_exchange, service_callback_exchange
 )
 from .provider_pomes import (
-    provider_register, provider_get_token
+    service_get_token, provider_get_token,
+    provider_setup_endpoint, provider_setup_logger, provider_setup_server
 )
 from .token_pomes import (
-    token_validate
+    token_get_claims, token_get_values, token_validate
 )
 
 __all__ = [
     # iam_actions
-    "action_callback", "action_exchange",
-    "action_login", "action_logout", "action_token",
+    "iam_callback", "iam_exchange",
+    "iam_login", "iam_logout", "iam_get_token", "iam_userinfo",
     # iam_commons
     "IamServer", "IamParam",
     # iam_pomes
-    "iam_setup", "iam_get_env_parameters", "iam_get_token",
+    "iam_setup_server", "iam_setup_endpoints",
     # iam_services
-    "jwt_required", "logger_register",
+    "jwt_required", "iam_setup_logger",
+    "service_setup_server", "service_login", "service_logout",
+    "service_get_token", "service_userinfo", "service_callback",
+    "service_exchange", "service_callback_exchange",
     # provider_pomes
-    "provider_register", "provider_get_token",
+    "provider_setup_server", "provider_get_token",
+    "provider_setup_endpoint", "provider_setup_logger", "provider_setup_server",
     # token_pomes
-    "token_validate"
+    "token_get_claims", "token_get_values", "token_validate"
 ]
 
 from importlib.metadata import version

pypomes_iam/iam_actions.py

@@ -13,24 +13,30 @@ from .iam_common import (
     _get_iam_users, _get_iam_registry, _get_public_key,
     _get_login_timeout, _get_user_data, _iam_server_from_issuer
 )
-from .token_pomes import token_get_claims, token_validate
+from .token_pomes import token_get_values, token_validate
 
 
-def action_login(iam_server: IamServer,
-                 args: dict[str, Any],
-                 errors: list[str] = None,
-                 logger: Logger = None) -> str:
+def iam_login(iam_server: IamServer,
+              args: dict[str, Any],
+              errors: list[str] = None,
+              logger: Logger = None) -> str:
     """
     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 (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 appropriate URL for invoking
     the IAM server's authentication page is returned.
 
+    if 'target_idp' is provided as an attribute in *args*, the OAuth2 state variable included in the
+    returned URL will be postfixed with the string *#idp=<target-idp>*. At the callback endpoint,
+    this instructs *iam_server* to act as a broker, forwading the authentication process to the
+    *IAM* server *target-idp*.
+
     :param iam_server: the reference registered *IAM* server
     :param args: the arguments passed when requesting the service
     :param errors: incidental error messages
@@ -43,9 +49,14 @@ def action_login(iam_server: IamServer,
     # obtain the optional user's identification
     user_id: str = args.get("user-id") or args.get("login")
 
+    # obtain the optional target identity provider
+    target_idp: str = args.get("target-idp")
+
     # build the user data
     # ('oauth_state' is a randomly-generated string, thus 'user_data' is always a new entry)
     oauth_state: str = "".join(secrets.choice(string.ascii_letters + string.digits) for _ in range(16))
+    if target_idp:
+        oauth_state += f"#idp={target_idp}"
 
     with _iam_lock:
         # retrieve the user data from the IAM server's registry
@@ -75,19 +86,23 @@ def action_login(iam_server: IamServer,
                               f"&client_id={registry[IamParam.CLIENT_ID]}"
                               f"&redirect_uri={redirect_uri}"
                               f"&state={oauth_state}")
+                    if target_idp:
+                        # HAZARD: the name 'kc_idp_hint' is Keycloak-specific
+                        result += f"&kc_idp_hint={target_idp}"
+
     return result
 
 
-def action_logout(iam_server: IamServer,
-                  args: dict[str, Any],
-                  errors: list[str] = None,
-                  logger: Logger = None) -> None:
+def iam_logout(iam_server: IamServer,
+               args: dict[str, Any],
+               errors: list[str] = None,
+               logger: Logger = None) -> None:
     """
     Logout the user, by removing all data associating it from *iam_server*'s registry.
 
-    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.
+    The user is identified by the attribute *user-id* or *login*, provided in *args*.
+    A logout request is sent to *iam_server* and, if successful, remove all data relating to the user
+    from the *IAM* server's registry.
 
     :param iam_server: the reference registered *IAM* server
     :param args: the arguments passed when requesting the service
@@ -99,33 +114,90 @@ def action_logout(iam_server: IamServer,
 
     if user_id:
         with _iam_lock:
-            # retrieve the data for all users in the IAM server's registry
-            users: dict[str, dict[str, Any]] = _get_iam_users(iam_server=iam_server,
-                                                              errors=errors,
-                                                              logger=logger) or {}
-            if user_id in users:
-                users.pop(user_id)
-                if logger:
-                    logger.debug(msg=f"User '{user_id}' removed from {iam_server}'s registry")
+            # retrieve the IAM server's registry and the data for all users therein
+            registry: dict[str, Any] = _get_iam_registry(iam_server,
+                                                         errors=errors,
+                                                         logger=logger)
+            users: dict[str, dict[str, Any]] = registry[IamParam.USERS] if registry else {}
+            user_data: dict[str, Any] = users.get(user_id)
+            if user_data:
+                # request the IAM server to logout 'client_id'
+                client_secret: str = __get_client_secret(iam_server=iam_server,
+                                                         errors=errors,
+                                                         logger=logger)
+                if client_secret:
+                    url: str = (f"{registry[IamParam.URL_BASE]}/realms/{registry[IamParam.CLIENT_REALM]}"
+                                "/protocol/openid-connect/logout")
+                    header_data: dict[str, str] = {
+                        "Content-Type": "application/x-www-form-urlencoded"
+                    }
+                    body_data: dict[str, Any] = {
+                        "client_id": registry[IamParam.CLIENT_ID],
+                        "client_secret": client_secret,
+                        "refresh_token": user_data[UserParam.REFRESH_TOKEN]
+                    }
+                    #  log the POST
+                    if logger:
+                        logger.debug(msg=f"POST {url}")
+                    try:
+                        response: requests.Response = requests.post(url=url,
+                                                                    headers=header_data,
+                                                                    data=body_data)
+                        if response.status_code in [200, 204]:
+                            # request succeeded
+                            if logger:
+                                logger.debug(msg=f"POST success")
+                        else:
+                            # request failed, report the problem
+                            msg: str = f"POST failure, status {response.status_code}, reason {response.reason}"
+                            if logger:
+                                logger.error(msg=msg)
+                            if isinstance(errors, list):
+                                errors.append(msg)
+                    except Exception as e:
+                        # the operation raised an exception
+                        msg: str = exc_format(exc=e,
+                                              exc_info=sys.exc_info())
+                        if logger:
+                            logger.error(msg=msg)
+                        if isinstance(errors, list):
+                            errors.append(msg)
 
+                    if not errors and user_id in users:
+                        users.pop(user_id)
+                        if logger:
+                            logger.debug(msg=f"User '{user_id}' removed from {iam_server}'s registry")
+    else:
+        msg: str = "User identification not provided"
+        if logger:
+            logger.error(msg=msg)
+        if isinstance(errors, list):
+            errors.append(msg)
 
-def action_token(iam_server: IamServer,
-                 args: dict[str, Any],
-                 errors: list[str] = None,
-                 logger: Logger = None) -> str:
+
+def iam_get_token(iam_server: IamServer,
+                  args: dict[str, Any],
+                  errors: list[str] = None,
+                  logger: Logger = None) -> dict[str, str]:
     """
     Retrieve the authentication token for the user, from *iam_server*.
 
     The user is identified by the attribute *user-id* or *login*, provided in *args*.
 
+    On success, the returned *dict* will contain the following JSON:
+        {
+            "access-token": <token>,
+            "user-id": <user-identification
+        }
+
     :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 indicated, or *None* if error
+    :return: the user identification and token issued, or *None* if error
     """
     # initialize the return variable
-    result: str | None = None
+    result: dict[str, str] | None = None
 
     # obtain the user's identification
     user_id: str = args.get("user-id") or args.get("login")
@@ -144,7 +216,10 @@ def action_token(iam_server: IamServer,
                 access_expiration: int = user_data.get(UserParam.ACCESS_EXPIRATION)
                 now: int = int(datetime.now(tz=TZ_LOCAL).timestamp())
                 if now < access_expiration:
-                    result = token
+                    result = {
+                        "access-token": token,
+                        "user-id": user_id
+                    }
                 else:
                     # access token has expired
                     refresh_token: str = user_data[UserParam.REFRESH_TOKEN]
@@ -152,7 +227,7 @@ def action_token(iam_server: IamServer,
                         refresh_expiration: int = user_data[UserParam.REFRESH_EXPIRATION]
                         if now < refresh_expiration:
                             header_data: dict[str, str] = {
-                                "Content-Type": "application/json"
+                                "Content-Type": "application/x-www-form-urlencoded"
                             }
                             body_data: dict[str, str] = {
                                 "grant_type": "refresh_token",
@@ -172,7 +247,10 @@ def action_token(iam_server: IamServer,
                                                                                    now=now,
                                                                                    errors=errors,
                                                                                    logger=logger)
-                                result = token_info[1]
+                                result = {
+                                    "access-token": token_info[1],
+                                    "user-id": user_id
+                                }
                             else:
                                 # refresh token is no longer valid
                                 user_data[UserParam.REFRESH_TOKEN] = None
@@ -200,10 +278,10 @@ def action_token(iam_server: IamServer,
     return result
 
 
-def action_callback(iam_server: IamServer,
-                    args: dict[str, Any],
-                    errors: list[str] = None,
-                    logger: Logger = None) -> tuple[str, str] | None:
+def iam_callback(iam_server: IamServer,
+                 args: dict[str, Any],
+                 errors: list[str] = None,
+                 logger: Logger = None) -> tuple[str, str] | None:
     """
     Entry point for the callback from *iam_server* via the front-end application, on authentication operations.
 
@@ -211,6 +289,10 @@ def action_callback(iam_server: IamServer,
         - *state*: used to enhance security during the authorization process, typically to provide *CSRF* protection
         - *code*: the temporary authorization code provided by *iam_server*, to be exchanged for the token
 
+    if *state* is postfixed with the string *#idp=<target-idp>*, this instructs *iam_server* to act as a broker,
+    forwarding the authentication process to the *IAM* server *target-idp*. This mechanism fully dispenses with
+    the flows 'callback-exchange', and 'callback' followed by 'exchange'.
+
     :param iam_server: the reference registered *IAM* server
     :param args: the arguments passed when requesting the service
     :param errors: incidental errors
@@ -240,6 +322,10 @@ def action_callback(iam_server: IamServer,
             if int(datetime.now(tz=TZ_LOCAL).timestamp()) > expiration:
                 errors.append("Operation timeout")
             else:
+                pos: int = oauth_state.rfind("#idp=")
+                target_idp: str = oauth_state[pos+4:] if pos > 0 else None
+                target_iam = IamServer(target_idp) if target_idp in IamServer else None
+                target_data: dict[str, Any] = user_data.copy() if target_iam else None
                 users.pop(oauth_state)
                 code: str = args.get("code")
                 header_data: dict[str, str] = {
@@ -264,6 +350,33 @@ def action_callback(iam_server: IamServer,
                                                   now=now,
                                                   errors=errors,
                                                   logger=logger)
+                    if target_iam:
+                        if logger:
+                            logger.debug(msg=f"Requesting to IAM server '{iam_server}' "
+                                             f"the token issued by '{target_iam}' ")
+                        registry: dict[str, Any] = _get_iam_registry(iam_server,
+                                                                     errors=errors,
+                                                                     logger=logger)
+                        url: str = (f"{registry[IamParam.URL_BASE]}/realms/"
+                                    f"{registry[IamParam.CLIENT_REALM]}/broker/{target_idp}/token")
+                        header_data: dict[str, str] = {
+                            "Authorization": f"Bearer {result[1]}",
+                            "Content-Type": "application/json"
+                        }
+                        token_data = __get_for_data(url=url,
+                                                    header_data=header_data,
+                                                    params=None,
+                                                    errors=errors,
+                                                    logger=logger)
+                        if not errors:
+                            token_info: tuple[str, str] = __validate_and_store(iam_server=target_iam,
+                                                                               user_data=target_data,
+                                                                               token_data=token_data,
+                                                                               now=now,
+                                                                               errors=errors,
+                                                                               logger=logger)
+                            if token_info and logger:
+                                logger.debug(msg=f"Token obtained: {json.dumps(obj=token_info)}")
         else:
             msg: str = f"State '{oauth_state}' not found in {iam_server}'s registry"
             if logger:
@@ -274,10 +387,10 @@ def action_callback(iam_server: IamServer,
     return result
 
 
-def action_exchange(iam_server: IamServer,
-                    args: dict[str, Any],
-                    errors: list[str] = None,
-                    logger: Logger = None) -> tuple[str, str]:
+def iam_exchange(iam_server: IamServer,
+                 args: dict[str, Any],
+                 errors: list[str] = None,
+                 logger: Logger = None) -> tuple[str, str]:
     """
     Request *iam_server* to issue a token in exchange for the token obtained from another *IAM* server.
 
@@ -308,12 +421,10 @@ def action_exchange(iam_server: IamServer,
 
     # obtain the token to be exchanged
     token: str = args.get("access-token") if user_id else None
-    token_claims: dict[str, dict[str, Any]] = token_get_claims(token=token,
-                                                               errors=errors,
-                                                               logger=logger) if token else None
-    token_issuer: str = _iam_server_from_issuer(issuer=token_claims["payload"]["iss"],
+    token_issuer: tuple[str] = token_get_values(token=token,
+                                                keys=("iss",),
                                                 errors=errors,
-                                                logger=logger) if token_claims else None
+                                                logger=logger)
     if not errors:
         # HAZARD: only 'IAM_KEYCLOAK' is currently supported
         with _iam_lock:
@@ -326,6 +437,7 @@ def action_exchange(iam_server: IamServer,
                 __assert_link(iam_server=iam_server,
                               user_id=user_id,
                               token=token,
+                              token_issuer=token_issuer[0],
                               errors=errors,
                               logger=logger)
                 if not errors:
@@ -368,9 +480,64 @@ def action_exchange(iam_server: IamServer,
     return result
 
 
+def iam_userinfo(iam_server: IamServer,
+                 args: dict[str, Any],
+                 errors: list[str] = None,
+                 logger: Logger = None) -> dict[str, Any] | None:
+    """
+    Obtain user data from *iam_server*.
+
+    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 user information requested, or *None* if error
+    """
+    # initialize the return variable
+    result: dict[str, Any] | None = None
+
+    # obtain the user's identification
+    user_id: str = args.get("user-id") or args.get("login")
+
+    err_msg: str | None = None
+    if user_id:
+        with _iam_lock:
+            # retrieve the IAM server's registry and the user data therein
+            registry: dict[str, Any] = _get_iam_registry(iam_server,
+                                                         errors=errors,
+                                                         logger=logger)
+            user_data: dict[str, Any] = registry[IamParam.USERS].get(user_id)
+            if user_data:
+                url: str = (f"{registry[IamParam.URL_BASE]}/realms/{registry[IamParam.CLIENT_REALM]}"
+                            "/protocol/openid-connect/userinfo")
+                header_data: dict[str, str] = {
+                    "Authorization": f"Bearer {args.get('access-token')}"
+                }
+                result = __get_for_data(url=url,
+                                        header_data=header_data,
+                                        params=None,
+                                        errors=errors,
+                                        logger=logger)
+            else:
+                err_msg = f"Unknown user '{user_id}'"
+    else:
+        err_msg: str = "User identification not provided"
+
+    if err_msg:
+        if logger:
+            logger.error(msg=err_msg)
+        if isinstance(errors, list):
+            errors.append(err_msg)
+
+    return result
+
+
 def __assert_link(iam_server: IamServer,
                   user_id: str,
                   token: str,
+                  token_issuer: str,
                   errors: list[str] | None,
                   logger: Logger | None) -> None:
     """
@@ -398,7 +565,7 @@ def __assert_link(iam_server: IamServer,
         # obtain the internal user identification for 'user_id'
         if logger:
             logger.debug(msg="Obtaining internal identification "
-                             f"for user {user_id} in IAM server {iam_server}")
+                             f"for user '{user_id}' in IAM server '{iam_server}'")
         url: str = f"{registry[IamParam.URL_BASE]}/admin/realms/{registry[IamParam.CLIENT_REALM]}/users"
         header_data: dict[str, str] = {
             "Authorization": f"Bearer {admin_token}",
@@ -414,12 +581,12 @@ def __assert_link(iam_server: IamServer,
                                                      errors=errors,
                                                      logger=logger)
         if users:
-            # verify whether the 'oidc' protocol is referred to in an
-            # association between 'user_id' and the internal user identification
+            # verify whether the IAM server that issued the token is a federated identity provider
+            # in the associations between 'user_id' and the internal user identification
             internal_id: str = users[0].get("id")
             if logger:
-                logger.debug(msg="Obtaining the providers federated with "
-                                 f"IAM server '{iam_server}' for internal identification '{internal_id}'")
+                logger.debug(msg="Obtaining the providers federated in IAM server "
+                                 f"'{iam_server}', for internal identification '{internal_id}'")
             url = (f"{registry[IamParam.URL_BASE]}/admin/realms/"
                    f"{registry[IamParam.CLIENT_REALM]}/users/{internal_id}/federated-identity")
             providers: list[dict[str, Any]] = __get_for_data(url=url,
@@ -428,13 +595,9 @@ def __assert_link(iam_server: IamServer,
                                                              errors=errors,
                                                              logger=logger)
             no_link: bool = True
-            claims: dict[str, dict[str, Any]] = token_get_claims(token=token,
-                                                                 errors=errors,
-                                                                 logger=logger)
-            issuer: str = claims["payload"]["iss"] if claims else None
-            provider_name: str = _iam_server_from_issuer(issuer=issuer,
+            provider_name: str = _iam_server_from_issuer(issuer=token_issuer,
                                                          errors=errors,
-                                                         logger=logger) if issuer else None
+                                                         logger=logger)
             if provider_name:
                 for provider in providers:
                     if provider.get("identityProvider") == provider_name:
@@ -442,17 +605,17 @@ def __assert_link(iam_server: IamServer,
                         break
                 if no_link:
                     # link the identities
-                    claims: dict[str, dict[str, Any]] = token_get_claims(token=token,
-                                                                         errors=errors,
-                                                                         logger=logger)
-                    if claims:
-                        token_sub: str = claims["payload"]["sub"]
+                    token_sub: tuple[str] = token_get_values(token=token,
+                                                             keys=("sub",),
+                                                             errors=errors,
+                                                             logger=logger)
+                    if token_sub:
                         if logger:
                             logger.debug(msg="Creating an association between identifications "
-                                             f"'{user_id}' and '{token_sub}' in IAM server {iam_server}")
+                                             f"'{user_id}' and '{token_sub}' in IAM server '{iam_server}'")
                         url += f"/{provider_name}"
                         json_data: dict[str, Any] = {
-                            "userId": token_sub,
+                            "userId": token_sub[0],
                             "userName": user_id
                         }
                         __post_json(url=url,
@@ -756,8 +919,8 @@ def __post_for_token(iam_server: IamServer,
                 body_data["client_id"] = registry[IamParam.CLIENT_ID]
 
             # build the URL
-            base_url: str = f"{registry[IamParam.URL_BASE]}/realms/{registry[IamParam.CLIENT_REALM]}"
-            url: str = f"{base_url}/protocol/openid-connect/token"
+            url: str = (f"{registry[IamParam.URL_BASE]}/realms/"
+                        f"{registry[IamParam.CLIENT_REALM]}/protocol/openid-connect/token")
             #  'client_secret' data must not be shown in log
             msg: str = f"POST {url}, {json.dumps(obj=body_data,
                                                  ensure_ascii=False)}"
@@ -839,6 +1002,8 @@ def __validate_and_store(iam_server: IamServer,
     # initialize the return variable
     result: tuple[str, str] | None = None
 
+    if logger:
+        logger.debug(msg=f"Validating and storing the token")
     with _iam_lock:
         # retrieve the IAM server's registry
         registry: dict[str, Any] = _get_iam_registry(iam_server=iam_server,