pypomes-iam 0.6.2__py3-none-any.whl → 0.8.2__py3-none-any.whl

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,66 @@ 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*
+          - *<APP_PREFIX>_<IAM>_ENDPOINT_USERINFO*
+
+    :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 +132,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 +154,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()
 

pypomes_iam/iam_pomes.py

@@ -1,37 +1,39 @@
 from flask import Flask
-from logging import Logger
-from pypomes_core import APP_PREFIX, env_get_int, env_get_str
-from typing import Any
+from pypomes_core import (
+    APP_PREFIX,
+    env_get_int, env_get_str,
+    func_capture_params, func_defaulted_params
+)
 
 from .iam_common import (
     _IAM_SERVERS, IamServer, IamParam, _iam_lock
 )
-from .iam_actions import action_token
 from .iam_services import (
-    service_login, service_logout, service_callback, service_exchange, service_token
+    service_login, service_logout,
+    service_callback, service_callback_exchange,
+    service_exchange, service_get_token, service_userinfo
 )
 
 
-def iam_setup(flask_app: Flask,
-              iam_server: IamServer,
-              base_url: str,
-              client_id: str,
-              client_realm: str,
-              client_secret: str | None,
-              recipient_attribute: str,
-              admin_id: str = None,
-              admin_secret: str = None,
-              login_timeout: int = None,
-              public_key_lifetime: int = None,
-              callback_endpoint: str = None,
-              exchange_endpoint: str = None,
-              login_endpoint: str = None,
-              logout_endpoint: str = None,
-              token_endpoint: str = None) -> None:
+@func_capture_params
+def iam_setup_server(iam_server: IamServer,
+                     admin_id: str = None,
+                     admin_secret: str = None,
+                     client_id: str = None,
+                     client_realm: str = None,
+                     client_secret: str = None,
+                     login_timeout: int = None,
+                     pk_lifetime: int = None,
+                     recipient_attr: str = None,
+                     url_base: str = None) -> None:
     """
-    Establish the provided parameters for configuring the *IAM* server *iam_server*.
+    Setup the *IAM* server *iam_server*.
+
+    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_* are required only if administrative are task are planned.
+    The parameters *admin_id* and *admin_* are required only if performing administrative task are intended.
     The optional parameter *client_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.
 
@@ -39,47 +41,122 @@ def iam_setup(flask_app: Flask,
     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 flask_app: the Flask application
-    :param iam_server: identifies the supported *IAM* server (*jusbr* or *keycloak*)
-    :param base_url: base URL to request services
-    :param client_id: the client's identification with the *IAM* server
-    :param client_realm: the client realm
-    :param client_secret: the client's password with the *IAM* server
-    :param recipient_attribute: attribute in the token's payload holding the token's subject
+    :param iam_server: identifies the supported *IAM* server (currently, *jusbr* or *keycloak*)
     :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
+    :param client_realm: the client's realm
+    :param client_secret: the client's password with the *IAM* server
     :param login_timeout: timeout for login authentication (in seconds,defaults to no timeout)
-    :param public_key_lifetime: how long to use *IAM* server's public key, before refreshing it (in seconds)
-    :param callback_endpoint: endpoint for the callback from the front end
-    :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 pk_lifetime: how long to use *IAM* server's public key, before refreshing it (in seconds)
+    :param recipient_attr: attribute in the token's payload holding the token's subject
+    :param url_base: base URL to request services
     """
+    # obtain the defaulted parameters
+    defaulted_params: list[str] = func_defaulted_params.get()
+
+    # read from the environment variables
+    prefix: str = iam_server.name
+    if "admin_id" in defaulted_params:
+        admin_id = env_get_str(key=f"{APP_PREFIX}_{prefix}_ADMIN_ID")
+    if "admin_secret" in defaulted_params:
+        admin_secret = env_get_str(key=f"{APP_PREFIX}_{prefix}_ADMIN_SECRET")
+    if "client_id" in defaulted_params:
+        client_id = env_get_str(key=f"{APP_PREFIX}_{prefix}_CLIENT_ID")
+    if "client_realm" in defaulted_params:
+        client_realm = env_get_str(key=f"{APP_PREFIX}_{prefix}_CLIENT_REALM")
+    if "client_secret" in defaulted_params:
+        client_secret = env_get_str(key=f"{APP_PREFIX}_{prefix}_CLIENT_SECRET")
+    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")
+    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")
 
     # configure the Keycloak registry
     with _iam_lock:
         _IAM_SERVERS[iam_server] = {
-            IamParam.URL_BASE: base_url,
             IamParam.CLIENT_ID: client_id,
             IamParam.CLIENT_REALM: client_realm,
             IamParam.CLIENT_SECRET: client_secret,
-            IamParam.RECIPIENT_ATTR: recipient_attribute,
+            IamParam.RECIPIENT_ATTR: recipient_attr,
             IamParam.ADMIN_ID: admin_id,
             IamParam.ADMIN_SECRET: admin_secret,
             IamParam.LOGIN_TIMEOUT: login_timeout,
-            IamParam.PK_LIFETIME: public_key_lifetime,
+            IamParam.PK_LIFETIME: pk_lifetime,
+            IamParam.URL_BASE: url_base,
+            # dynamic attributes
             IamParam.PK_EXPIRATION: 0,
             IamParam.PUBLIC_KEY: None,
             IamParam.USERS: {}
         }
 
+
+@func_capture_params
+def iam_setup_endpoints(flask_app: Flask,
+                        iam_server: IamServer,
+                        callback_endpoint: str = None,
+                        callback_exchange_endpoint: str = None,
+                        exchange_endpoint: str = None,
+                        login_endpoint: str = None,
+                        logout_endpoint: str = None,
+                        token_endpoint: str = None,
+                        userinfo_endpoint: str = None) -> None:
+    """
+    Setup the endpoints for accessing the services provided by *iam_server*.
+
+    For the parameters not effectively passed, an attempt is made to obtain a value from the corresponding
+    environment variables.
+
+    :param flask_app: the Flask application
+    :param iam_server: identifies the supported *IAM* server (currently, *jusbr* or *keycloak*)
+    :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()
+
+    # read from the environment variables
+    prefix: str = iam_server.name
+    if "callback_endpoint" in defaulted_params:
+        callback_endpoint = env_get_str(key=f"{APP_PREFIX}_{prefix}_ENDPOINT_CALLBACK")
+    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")
+    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"])
+    if callback_exchange_endpoint:
+        flask_app.add_url_rule(rule=callback_exchange_endpoint,
+                               endpoint=f"{iam_server}-callback-exchange",
+                               view_func=service_callback_exchange,
+                               methods=["GET"])
+    if exchange_endpoint:
+        flask_app.add_url_rule(rule=exchange_endpoint,
+                               endpoint=f"{iam_server}-exchange",
+                               view_func=service_exchange,
+                               methods=["POST"])
     if login_endpoint:
         flask_app.add_url_rule(rule=login_endpoint,
                                endpoint=f"{iam_server}-login",
@@ -89,68 +166,14 @@ def iam_setup(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_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"])
-    if exchange_endpoint:
-        flask_app.add_url_rule(rule=exchange_endpoint,
-                               endpoint=f"{iam_server}-exchange",
-                               view_func=service_exchange,
-                               methods=["POST"])
-
-
-def iam_get_env_parameters(iam_prefix: str = None) -> dict[str, Any]:
-    """
-    Retrieve the set parameters for a *IAM* server from the environment.
-
-    the parameters are returned ready to be used as a '**kwargs' parameter set in a call to *iam_setup()*,
-    and sorted in the order appropriate to use them instead with a '*args' parameter set.
-
-    :param iam_prefix: the prefix classifying the parameters
-    :return: the sorted parameters classified by *prefix*
-    """
-    return {
-        "base_url": env_get_str(key=f"{APP_PREFIX}_{iam_prefix}_URL_AUTH_BASE"),
-        "client_id": env_get_str(key=f"{APP_PREFIX}_{iam_prefix}_CLIENT_ID"),
-        "client_realm": env_get_str(key=f"{APP_PREFIX}_{iam_prefix}_CLIENT_REALM"),
-        "client_secret": env_get_str(key=f"{APP_PREFIX}_{iam_prefix}_CLIENT_SECRET"),
-        "recipient_attribute": env_get_str(key=f"{APP_PREFIX}_{iam_prefix}_RECIPIENT_ATTR"),
-        "admin_id": env_get_str(key=f"{APP_PREFIX}_{iam_prefix}_ADMIN_ID"),
-        "admin_secret": env_get_str(key=f"{APP_PREFIX}_{iam_prefix}_ADMIN_SECRET"),
-        "login_timeout": env_get_str(key=f"{APP_PREFIX}_{iam_prefix}_LOGIN_TIMEOUT"),
-        "public_key_lifetime": env_get_int(key=f"{APP_PREFIX}_{iam_prefix}_PUBLIC_KEY_LIFETIME"),
-        "callback_endpoint": env_get_str(key=f"{APP_PREFIX}_{iam_prefix}_ENDPOINT_CALLBACK"),
-        "exchange_endpoint": env_get_str(key=f"{APP_PREFIX}_{iam_prefix}_ENDPOINT_EXCHANGE"),
-        "login_endpoint": env_get_str(key=f"{APP_PREFIX}_{iam_prefix}_ENDPOINT_LOGIN"),
-        "logout_endpoint": env_get_str(key=f"{APP_PREFIX}_{iam_prefix}_ENDPOINT_LOGOUT"),
-        "token_endpoint": env_get_str(key=f"{APP_PREFIX}_{iam_prefix}_ENDPOINT_TOKEN")
-    }
-
-
-def iam_get_token(iam_server: IamServer,
-                  user_id: str,
-                  errors: list[str] = None,
-                  logger: Logger = None) -> str:
-    """
-    Retrieve an authentication token for *user_id*.
-
-    :param iam_server: identifies the *IAM* server
-    :param user_id: identifies the user
-    :param errors: incidental errors
-    :param logger: optional logger
-    :return: the uthentication tokem
-    """
-    # declare the return variable
-    result: str
-
-    # retrieve the token
-    args: dict[str, Any] = {"user-id": user_id}
-    with _iam_lock:
-        result = action_token(iam_server=iam_server,
-                              args=args,
-                              errors=errors,
-                              logger=logger)
-    return result