pypomes-iam 0.7.6__tar.gz → 0.8.1__tar.gz

{pypomes_iam-0.7.6 → pypomes_iam-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pypomes_iam
-Version: 0.7.6
+Version: 0.8.1
 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
@@ -12,6 +12,6 @@ Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.12
 Requires-Dist: flask>=3.1.2
 Requires-Dist: pyjwt>=2.10.1
-Requires-Dist: pypomes-core>=2.8.1
+Requires-Dist: pypomes-core>=2.8.6
 Requires-Dist: pypomes-crypto>=0.4.8
 Requires-Dist: requests>=2.32.5

{pypomes_iam-0.7.6 → pypomes_iam-0.8.1}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pypomes_iam"
-version = "0.7.6"
+version = "0.8.1"
 authors = [
   { name="GT Nunes", email="wisecoder01@gmail.com" }
 ]
@@ -21,7 +21,7 @@ classifiers = [
 dependencies = [
     "Flask>=3.1.2",
     "PyJWT>=2.10.1",
-    "pypomes-core>=2.8.1",
+    "pypomes-core>=2.8.6",
     "pypomes-crypto>=0.4.8",
     "requests>=2.32.5"
 ]

pypomes_iam-0.8.1/src/pypomes_iam/__init__.py

@@ -0,0 +1,49 @@
+from .iam_actions import (
+    iam_callback, iam_exchange,
+    iam_login, iam_logout, iam_get_token
+)
+from .iam_common import (
+    IamServer, IamParam
+)
+from .iam_pomes import (
+    iam_setup_server, iam_setup_endpoints
+)
+from .iam_services import (
+    jwt_required, iam_setup_logger,
+    service_setup_server, service_get_token,
+    service_login, service_logout,
+    service_callback, service_exchange,
+    service_callback_exchange
+)
+from .provider_pomes import (
+    service_get_token, provider_get_token,
+    provider_setup_endpoint, provider_setup_logger, provider_setup_server
+)
+from .token_pomes import (
+    token_get_claims, token_get_values, token_validate
+)
+
+__all__ = [
+    # iam_actions
+    "iam_callback", "iam_exchange",
+    "iam_login", "iam_logout", "iam_get_token",
+    # iam_commons
+    "IamServer", "IamParam",
+    # iam_pomes
+    "iam_setup_server", "iam_setup_endpoints",
+    # iam_services
+    "jwt_required", "iam_setup_logger",
+    "service_setup_server", "service_get_token",
+    "service_login", "service_logout",
+    "service_callback", "service_exchange",
+    "service_callback_exchange",
+    # provider_pomes
+    "provider_setup_server", "provider_get_token",
+    "provider_setup_endpoint", "provider_setup_logger", "provider_setup_server",
+    # token_pomes
+    "token_get_claims", "token_get_values", "token_validate"
+]
+
+from importlib.metadata import version
+__version__ = version("pypomes_iam")
+__version_info__ = tuple(int(i) for i in __version__.split(".") if i.isdigit())

{pypomes_iam-0.7.6 → pypomes_iam-0.8.1}/src/pypomes_iam/iam_actions.py

@@ -13,13 +13,13 @@ 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.
 
@@ -32,6 +32,11 @@ def action_login(iam_server: IamServer,
     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
@@ -51,7 +56,7 @@ def action_login(iam_server: IamServer,
     # ('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}"
+        oauth_state += f"#idp={target_idp}"
 
     with _iam_lock:
         # retrieve the user data from the IAM server's registry
@@ -88,10 +93,10 @@ def action_login(iam_server: IamServer,
     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.
 
@@ -119,23 +124,29 @@ def action_logout(iam_server: IamServer,
                     logger.debug(msg=f"User '{user_id}' removed from {iam_server}'s registry")
 
 
-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")
@@ -154,7 +165,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]
@@ -182,7 +196,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
@@ -210,10 +227,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.
 
@@ -221,6 +238,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
@@ -250,7 +271,7 @@ 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=")
+                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
@@ -315,10 +336,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.
 
@@ -349,12 +370,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:
@@ -367,6 +386,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:
@@ -412,6 +432,7 @@ def action_exchange(iam_server: IamServer,
 def __assert_link(iam_server: IamServer,
                   user_id: str,
                   token: str,
+                  token_issuer: str,
                   errors: list[str] | None,
                   logger: Logger | None) -> None:
     """
@@ -439,7 +460,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}",
@@ -455,12 +476,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,
@@ -469,13 +490,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:
@@ -483,17 +500,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,

{pypomes_iam-0.7.6 → pypomes_iam-0.8.1}/src/pypomes_iam/iam_common.py

@@ -3,7 +3,10 @@ import sys
 from datetime import datetime
 from enum import StrEnum, auto
 from logging import Logger
-from pypomes_core import TZ_LOCAL, exc_format
+from pypomes_core import (
+    APP_PREFIX, TZ_LOCAL, exc_format,
+    env_get_str,  env_get_int, env_get_enums
+)
 from pypomes_crypto import crypto_jwk_convert
 from threading import RLock
 from typing import Any, Final
@@ -21,12 +24,14 @@ class IamParam(StrEnum):
     """
     Parameters for configuring *IAM* servers.
     """
+
     ADMIN_ID = "admin-id"
     ADMIN_SECRET = "admin-secret"
     CLIENT_ID = "client-id"
     CLIENT_REALM = "client-realm"
     CLIENT_SECRET = "client-secret"
     ENDPOINT_CALLBACK = "endpoint-callback"
+    ENDPOINT_CALLBACK_EXCHANGE = "endpoint-callback-exchange"
     ENDPOINT_LOGIN = "endpoint-login"
     ENDPOINT_LOGOUT = "endpoint_logout"
     ENDPOINT_TOKEN = "endpoint-token"
@@ -34,8 +39,9 @@ class IamParam(StrEnum):
     LOGIN_TIMEOUT = "login-timeout"
     PK_EXPIRATION = "pk-expiration"
     PK_LIFETIME = "pk-lifetime"
-    PUBLIC_KEY = "public-key"
     RECIPIENT_ATTR = "recipient-attr"
+    # dynamic attributes
+    PUBLIC_KEY = "public-key"
     URL_BASE = "url-base"
     USERS = "users"
 
@@ -54,31 +60,65 @@ class UserParam(StrEnum):
     REDIRECT_URI = "redirect-uri"
 
 
-# The configuration parameters for the IAM servers are specified dynamically dynamically with *iam_setup()*
-# Specifying configuration parameters with environment variables can be done in two ways:
-#
-# 1. for a single *IAM* server, specify the data set
-#       - *<APP_PREFIX>_IAM_ADMIN_ID*             (optional, needed if administrative duties are performed)
-#       - *<APP_PREFIX>_IAM_ADMIN_PWD*            (optional, needed if administrative duties are performed)
-#       - *<APP_PREFIX>_IAM_CLIENT_ID*            (required)
-#       - *<APP_PREFIX>_IAM_CLIENT_REALM*         (required)
-#       - *<APP_PREFIX>_IAM_CLIENT_SECRET*        (required)
-#       - *<APP_PREFIX>_IAM_ENDPOINT_CALLBACK*    (required)
-#       - *<APP_PREFIX>_IAM_ENDPOINT_EXCHANGE*    (required)
-#       - *<APP_PREFIX>_IAM_ENDPOINT_LOGIN*       (required)
-#       - *<APP_PREFIX>_IAM_ENDPOINT_LOGOUT*      (required)
-#       - *<APP_PREFIX>_IAM_ENDPOINT_PROVIDER*    (optional, needed if requesting tokens to providers)
-#       - *<APP_PREFIX>_IAM_ENDPOINT_TOKEN*       (required)
-#       - *<APP_PREFIX>_IAM_LOGIN_TIMEOUT*        (optional, defaults to no timeout)
-#       - *<APP_PREFIX>_IAM_PK_LIFETIME*          (optional, defaults to non-terminating lifetime)
-#       - *<APP_PREFIX>_IAM_RECIPIENT_ATTR*       (required)
-#       - *<APP_PREFIX>_IAM_URL_BASE*             (required)
-#
-# 2. for multiple *IAM* servers, specify the data set above for each server,
-#    respectively replacing *IAM* with a name in *IamServer* (currently, *JUSBR* and *KEYCLOAK* are supported).
-#
-# 3. the parameters *PUBLIC_KEY*, *PK_EXPIRATION*, and *USERS* cannot be assigned values,
-#    as they are reserved for internal use
+def __get_iam_data() -> dict[IamServer, dict[IamParam, Any]]:
+    """
+    Obtain the configuration data for select *IAM* servers.
+
+    The configuration parameters for the IAM servers are specified dynamically with environment variables,
+    or dynamically with calls to *iam_setup_server()*. Specifying configuration parameters with environment
+    variables can be done by following these steps:
+
+    1. Specify *<APP_PREFIX>_IAM_SERVERS* with a list of names among the values found in *IamServer* class
+       (currently, *jusbr* and *keycloak* are supported), and the data set below for each server, where
+       *<IAM>* stands for the server's name as presented in *IamServer* class:
+          - *<APP_PREFIX>_<IAM>_ADMIN_ID*           (optional, required if administrative duties are performed)
+          - *<APP_PREFIX>_<IAM>_ADMIN_PWD*          (optional, required if administrative duties are performed)
+          - *<APP_PREFIX>_<IAM>_CLIENT_ID*          (required)
+          - *<APP_PREFIX>_<IAM>_CLIENT_REALM*       (required)
+          - *<APP_PREFIX>_<IAM>_CLIENT_SECRET*      (required)
+          - *<APP_PREFIX>_<IAM>_LOGIN_TIMEOUT*      (optional, defaults to no timeout)
+          - *<APP_PREFIX>_<IAM>_PK_LIFETIME*        (optional, defaults to non-terminating lifetime)
+          - *<APP_PREFIX>_<IAM>_RECIPIENT_ATTR*     (required)
+          - *<APP_PREFIX>_<IAM>_URL_BASE*           (required)
+
+    2. A group of special environment variables identifying endpoints for authentication services may be specified,
+       following the same scheme as presented in item *1* above. These are not part of the *IAM* server's setup,
+       but are meant to be used by function *iam_setup_endpoints()*, wherein the values in those variables
+       would represent default values for its parameters, respectively:
+          - *<APP_PREFIX>_<IAM>_ENDPOINT_CALLBACK*
+          - *<APP_PREFIX>_<IAM>_ENDPOINT_CALLBACK_EXCHANGE*
+          - *<APP_PREFIX>_<IAM>_ENDPOINT_EXCHANGE*
+          - *<APP_PREFIX>_<IAM>_ENDPOINT_LOGIN*
+          - *<APP_PREFIX>_<IAM>_ENDPOINT_LOGOUT*
+          - *<APP_PREFIX>_<IAM>_ENDPOINT_TOKEN*
+
+    :return: the configuration data for the select *IAM* servers.
+    """
+    # initialize the return variable
+    result: dict[IamServer, dict[IamParam, Any]] = {}
+
+    servers: list[IamServer] = env_get_enums(key=f"{APP_PREFIX}_IAM_SERVERS",
+                                             enum_class=IamServer) or []
+    for server in servers:
+        prefix = server.name
+        result[server] = {
+            IamParam.ADMIN_ID: env_get_str(key=f"{APP_PREFIX}_{prefix}_ADMIN_ID"),
+            IamParam.ADMIN_SECRET: env_get_str(key=f"{APP_PREFIX}_{prefix}_ADMIN_SECRET"),
+            IamParam.CLIENT_ID: env_get_str(key=f"{APP_PREFIX}_{prefix}_CLIENT_ID"),
+            IamParam.CLIENT_REALM: env_get_str(key=f"{APP_PREFIX}_{prefix}_CLIENT_REALM"),
+            IamParam.CLIENT_SECRET: env_get_str(key=f"{APP_PREFIX}_{prefix}_CLIENT_SECRET"),
+            IamParam.LOGIN_TIMEOUT: env_get_str(key=f"{APP_PREFIX}_{prefix}_LOGIN_TIMEOUT"),
+            IamParam.PK_LIFETIME: env_get_int(key=f"{APP_PREFIX}_{prefix}_PUBLIC_KEY_LIFETIME"),
+            IamParam.RECIPIENT_ATTR: env_get_str(key=f"{APP_PREFIX}_{prefix}_RECIPIENT_ATTR"),
+            IamParam.URL_BASE: env_get_str(key=f"{APP_PREFIX}_{prefix}_URL_AUTH_BASE"),
+            # dynamically set
+            IamParam.PK_EXPIRATION: 0,
+            IamParam.PUBLIC_KEY: None,
+            IamParam.USERS: {}
+        }
+
+    return result
+
 
 # registry structure:
 # { <IamServer>:
@@ -91,6 +131,7 @@ class UserParam(StrEnum):
 #       "client-realm": <str,
 #       "client-timeout": <int>,
 #       "recipient-attr": <str>,
+#       # dynamic attributes
 #       "public-key": <str>,
 #       "pk-lifetime": <int>,
 #       "pk-expiration": <int>,
@@ -112,10 +153,10 @@ class UserParam(StrEnum):
 #   },
 #   ...
 # }
-_IAM_SERVERS: Final[dict[IamServer, dict[IamParam, Any]]] = {}
+_IAM_SERVERS: Final[dict[IamServer, dict[IamParam, Any]]] = __get_iam_data()
 
 
-# the lock protecting the data in '_IAM_SERVERS'
+# the lock protecting the data in '_<IAM>_SERVERS'
 # (because it is 'Final' and set at declaration time, it can be accessed through simple imports)
 _iam_lock: Final[RLock] = RLock()