nextlayer-sdk-python 1.0.2__tar.gz → 1.1.0__tar.gz

{nextlayer_sdk_python-1.0.2 → nextlayer_sdk_python-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: nextlayer-sdk-python
-Version: 1.0.2
+Version: 1.1.0
 Summary: Client utilities to interact with next layer public APIs
 Author: Wolfgang Powisch
 Author-email: wolfgang.powisch@nextlayer.at
@@ -11,10 +11,12 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Requires-Dist: PyYAML (>=6.0,<7.0)
-Requires-Dist: pydantic (>=2.10.6,<3.0.0)
+Requires-Dist: httpx (>=0.28.1,<0.29.0)
+Requires-Dist: pydantic (>=2.12.5,<3.0.0)
 Requires-Dist: pyjwt (>=2.10.1,<3.0.0)
-Requires-Dist: python-keycloak (>=3.0.0,<4.0.0)
+Requires-Dist: python-keycloak (>=5.8.1,<6.0.0)
 Description-Content-Type: text/markdown
 
 # nextlayer-sdk-python

{nextlayer_sdk_python-1.0.2 → nextlayer_sdk_python-1.1.0}/pyproject.toml

@@ -3,7 +3,7 @@ name = "nextlayer-sdk-python"
 packages = [
     { include = "nextlayer", from="src" }
 ]
-version = "v1.0.2"
+version = "v1.1.0"
 description = "Client utilities to interact with next layer public APIs"
 readme = "README.md"
 authors = ["Wolfgang Powisch <wolfgang.powisch@nextlayer.at>"]
@@ -18,21 +18,21 @@ nextlayer-auth = "nextlayer.sdk.auth:main"
 
 [tool.poetry.dependencies]
 python = "^3.11"
-python-keycloak = "^3.0.0"
+python-keycloak = "^5.8.1"
 PyYAML = "^6.0"
 pyjwt = "^2.10.1"
-pydantic = "^2.10.6"
+pydantic = "^2.12.5"
+httpx = "^0.28.1"
 
 [tool.poetry.group.dev.dependencies]
 pytest = "*"
 pytest-cov = "*"  # pytest-cov >= 6 requires python 3.9
-httpx = "^0.28.1"
 bandit = "*"
 black = "*"
 mypy = "*"
 isort = "*"
 types-pyyaml = "*"
-pre-commit = "^4.1.0"
+pre-commit = "*"
 
 [build-system]
 requires = ["poetry-core>=1.0.0"]

{nextlayer_sdk_python-1.0.2 → nextlayer_sdk_python-1.1.0}/src/nextlayer/sdk/__init__.py

@@ -1,2 +1,2 @@
 # do not edit this version line, it will be updated in CI-Pipeline!
-__version__ = "v1.0.2"
+__version__ = "v1.1.0"

{nextlayer_sdk_python-1.0.2 → nextlayer_sdk_python-1.1.0}/src/nextlayer/sdk/auth.py

@@ -14,10 +14,7 @@ from keycloak import KeycloakOpenID
 from keycloak.exceptions import KeycloakGetError
 from pydantic import BaseModel, Field
 
-from . import errors
-
-# Retrieve/Refresh Token on demand from next layer IAM
-
+from . import auth_code_browser_flow, errors, utils
 
 log = logging.getLogger(__name__)
 
@@ -26,21 +23,8 @@ DEFAULT_CLIENT_ID = "nextlayer-sdk-python"
 DEFAULT_REALM = "nlcustomers"
 
 
-def _get_current_user_homedir() -> str:
-    try:
-        # this is the reliable/correct method, that also works in cases
-        # where e.g. process-manager like gunicorn changes the efective UID
-        # but preserves the environment
-        import pwd
-
-        return pwd.getpwuid(os.getuid()).pw_dir
-    except Exception:
-        # fallback for (non-unix) platforms without `pwd` module
-        return os.path.expanduser("~")
-
-
 def _get_default_config_filename(realm: str) -> str:
-    homedir = _get_current_user_homedir()
+    homedir = utils.get_current_user_homedir()
     default_fn = os.path.join(homedir, ".nextlayer-sdk", f"auth.{realm}.yml")
     if os.path.exists(default_fn):
         return default_fn
@@ -51,23 +35,26 @@ def _get_default_config_filename(realm: str) -> str:
 
 
 class PersistentConfig(BaseModel):
+    """persisted data (usually stored in YAML file)"""
+
+    # user defined config values (and their defaults):
     server_url: str = DEFAULT_KEYCLOAK_URL
     realm_name: str = DEFAULT_REALM
     client_id: str = DEFAULT_CLIENT_ID
     username: str | None = None
     password: str | None = None
+    extra_params: dict[str, Any] = Field(default_factory=dict)
 
+    # state updated by NlAuth itself:
     expires_at: float | None = None
     refresh_expires_at: float | None = None
     tokens: Any | None = None
 
-    extra_params: dict[str, Any] = Field(default_factory=dict)
-
 
 class FilePerRealmAuthStore:
-    def __init__(self, filename: str):
+    def __init__(self, filename: str, config: PersistentConfig):
         self.config_filename: str = filename
-        self.config = PersistentConfig()
+        self.config = config
         self.config_read_mtime = 0
 
         self.read_config()
@@ -84,16 +71,18 @@ class FilePerRealmAuthStore:
 
     def read_config(self):
         if not os.path.isfile(self.config_filename):
-            self.config = PersistentConfig()
+            self.config = self.config.__class__()
             return
         log.debug(f"reading config from {self.config_filename}")
         self.config_read_mtime = self.mtime
         with open(self.config_filename) as fil:
-            self.config = PersistentConfig.model_validate(yaml.safe_load(fil) or {})
+            self.config = self.config.__class__.model_validate(
+                yaml.safe_load(fil) or {}
+            )
 
     def write_config(self):
         log.debug(f"writing config to {self.config_filename}")
-        # in the yaml we only want to store keys that have been explicitly
+        # in the YAML we only want to store keys that have been explicitly
         # set to some (non-default) value
         data = self.config.model_dump(
             exclude_none=True, exclude_unset=True, exclude_defaults=True
@@ -119,23 +108,40 @@ class FilePerRealmAuthStore:
 class NlAuth(object):
     def __init__(
         self,
-        config_filename=None,
-        server_url=None,
-        realm_name=None,
-        client_id=None,
-        username=None,
+        config_filename: str | None = None,
+        server_url: str | None = None,
+        realm_name: str | None = None,
+        client_id: str | None = None,
+        username: str | None = None,
+        ask_totp=False,
+        browser_login=False,
+        # optional customizations of pre-defined defaults:
+        config_defaults: PersistentConfig | None = None,
+        browser_login_redirect_uri: str | None = None,
+        username_envvar="NEXTLAYERSDK_USERNAME",
+        password_envvar="NEXTLAYERSDK_PASSWORD",
     ):
+        if config_defaults is None:
+            config_defaults = PersistentConfig()
+
+        self.username_envvar = username_envvar
+        self.password_envvar = password_envvar
+
+        self.ask_totp = ask_totp
+        self.browser_login = browser_login
+        self.browser_login_redirect_uri = browser_login_redirect_uri
+
         self.config_filename = config_filename or _get_default_config_filename(
-            realm_name or DEFAULT_REALM
+            realm_name or config_defaults.realm_name
         )
-        self.store = FilePerRealmAuthStore(self.config_filename)
+        self.store = FilePerRealmAuthStore(self.config_filename, config_defaults)
 
         new_server_url = (server_url or self.store.config.server_url).rstrip("/") + "/"
         new_realm_name = realm_name or self.store.config.realm_name
         new_client_id = client_id or self.store.config.client_id
         self.username = (
             username
-            or os.environ.get("NEXTLAYERSDK_USERNAME")
+            or os.environ.get(self.username_envvar)
             or self.store.config.username
         )
 
@@ -199,40 +205,53 @@ class NlAuth(object):
         log.debug(
             f"do_login for realm {self.store.config.realm_name} on {self.store.config.server_url}"
         )
-        password = (
-            password
-            or os.environ.get("NEXTLAYERSDK_PASSWORD")
-            or self.store.config.password
-        )
+        if self.browser_login:
+            tokens = auth_code_browser_flow.start_authorization_flow(
+                self.keycloak_openid,
+                redirect_uri=self.browser_login_redirect_uri,
+            )
+        else:
+            password = (
+                password
+                or os.environ.get(self.password_envvar)
+                or self.store.config.password
+            )
 
-        # Interactive:
-        if (not self.username or not password) and sys.stdin.isatty():
-            if not self.username:
-                self.username = getpass.getuser()
-            if not password:
-                print(
-                    "# Note: If you want to log in with another username, just press Enter.\n"
-                    "#       The password you enter will be used once to obtain new\n"
-                    "#       tokens from IAM and will not be stored anywhere. Once the\n"
-                    "#       refresh token expires, you will need to enter it again."
+            totp_secret: int | None = None
+
+            # Interactive:
+            if (not self.username or not password) and sys.stdin.isatty():
+                if not self.username:
+                    self.username = getpass.getuser()
+                if not password:
+                    sys.stderr.write(
+                        "# Note: If you want to log in with another username, just press Enter.\n"
+                        "#       The password you enter will be used once to obtain new\n"
+                        "#       tokens from IAM and will not be stored anywhere. Once the\n"
+                        "#       refresh token expires, you will need to enter it again.\n"
+                    )
+                    password = getpass.getpass(f"Password for {self.username}: ")
+                if not password:
+                    self.username = input("Username: ")
+                    if self.username:
+                        self.store.config.username = self.username
+                        self.store.write_config()
+                    password = getpass.getpass(f"Password for {self.username}: ")
+                if self.ask_totp:
+                    totp_secret = int(input("TOTP/2FA secret: "))
+
+            if not self.username or not password:
+                raise errors.AuthenticationError(
+                    f"failed to set {self.username_envvar}/{self.password_envvar} from config,env-var,interactive"
                 )
-                password = getpass.getpass(f"Password for {self.username}: ")
-            if not password:
-                self.username = input("Username: ")
-                if self.username:
-                    self.store.config.username = self.username
-                    self.store.write_config()
-                password = getpass.getpass(f"Password for {self.username}: ")
-
-        if not self.username or not password:
-            raise errors.AuthenticationError(
-                "failed to set NEXTLAYERSDK_USERNAME/PASSWORD from config,env-var,interactive"
-            )
 
-        extra = self.store.config.extra_params
+            extra = self.store.config.extra_params
+
+            log.debug(f"make keycloak token-request for user {self.username}")
+            tokens = self.keycloak_openid.token(
+                self.username, password, totp=totp_secret, **extra
+            )
 
-        log.debug(f"make keycloak token-request for user {self.username}")
-        tokens = self.keycloak_openid.token(self.username, password, **extra)
         access_token = self.update_tokens(tokens)
         self.store.write_config()
         return access_token
@@ -241,10 +260,10 @@ class NlAuth(object):
         try:
             log.debug("make keycloak token-refresh")
             tokens = self.keycloak_openid.refresh_token(
-                self.store.config.tokens["refresh_token"]
+                (self.store.config.tokens or {}).get("refresh_token") or ""
             )
         except KeycloakGetError as e:
-            # e.g. 400: b'{"error":"invalid_grant", "error_description":"Session not active"}'
+            # e.g., 400: b'{"error":"invalid_grant", "error_description":"Session not active"}'
             # ... when session has been deleted in Keycloak and refresh_token cannot be used anymore
             sys.stderr.write("token refresh failed: %s\n" % (e,))
             return self.do_login()
@@ -265,7 +284,9 @@ class NlAuth(object):
             elif self.token_expired():
                 access_token = self.do_refresh()
             else:
-                access_token = self.store.config.tokens["access_token"]
+                access_token = (self.store.config.tokens or {}).get(
+                    "access_token"
+                ) or ""
             return access_token
         except errors.NextlayerSdkError:
             raise
@@ -276,12 +297,17 @@ class NlAuth(object):
         access_token = self.get_access_token()
 
         log.debug("obtaining certs from keycloak for token-verification")
-        return jwt.decode(
+        info = jwt.decode(
             access_token,
             key=jwt.PyJWK(self.keycloak_openid.certs()["keys"][0]),
             options=dict(verify_aud=False),
             algorithms=["HS256", "RS256"],
         )
+        access_token_remaining_seconds = info["exp"] - time.time()
+        log.debug(
+            f"access token expires in {access_token_remaining_seconds:.0f} seconds"
+        )
+        return info
 
 
 def parse_commandline_args():
@@ -307,6 +333,18 @@ def parse_commandline_args():
     )
     parser.add_argument("-u", "--username", help="username")
     parser.add_argument("-a", "--aud", help="set audience - default: not set")
+    parser.add_argument(
+        "-t",
+        "--totp",
+        action="store_true",
+        help="ask for TOTP/2FA secret on interactive login",
+    )
+    parser.add_argument(
+        "-b",
+        "--browser",
+        action="store_true",
+        help="use authorization code flow with browser",
+    )
     parser.add_argument("-v", "--verbose", action="store_true")
     parser.add_argument(
         "command",
@@ -333,6 +371,8 @@ def main() -> int:
             realm_name=args.realm,
             client_id=args.client_id,
             username=args.username,
+            ask_totp=args.totp,
+            browser_login=args.browser,
         )
 
         if args.aud:

nextlayer_sdk_python-1.1.0/src/nextlayer/sdk/auth_code_browser_flow.py

@@ -0,0 +1,130 @@
+import base64
+import hashlib
+import logging
+import os
+import platform
+import sys
+import webbrowser
+from urllib.parse import parse_qs, urlparse
+
+from keycloak import KeycloakOpenID
+
+from nextlayer.sdk.errors import AuthenticationError
+
+from . import utils
+
+log = logging.getLogger(__name__)
+
+
+def start_authorization_flow(k_client: KeycloakOpenID, redirect_uri: str | None = None):
+    """
+    Starts the Browser-based Authorization Code Flow with State, Nonce and PKCE.
+    """
+    if redirect_uri is None:
+        redirect_uri = "https://login-callback.nextlayer.at/"
+
+    if not sys.stdin.isatty():
+        raise AuthenticationError(
+            "Cannot start browser based authorization flow in non-interactive mode."
+        )
+
+    # Generate security parameters
+    state = utils.generate_random_string(16)
+    nonce = utils.generate_random_string(16)
+
+    # PKCE Params
+    # 1. Code Verifier (random String, 43-128 characters)
+    code_verifier = utils.generate_random_string(64)
+    # 2. Code Challenge (SHA256 Hash of Verifier, Base64 urlsafe)
+    _hashed_verifier = hashlib.sha256(code_verifier.encode("utf-8")).digest()
+    code_challenge = (
+        base64.urlsafe_b64encode(_hashed_verifier).rstrip(b"=").decode("utf-8")
+    )
+    code_challenge_method = "S256"
+
+    # generate Auth URL
+    auth_url = k_client.auth_url(
+        redirect_uri=redirect_uri,
+        scope="openid",
+        state=state,  # CSRF Protection
+        nonce=nonce,  # OIDC Protection
+        # code_challenge=code_challenge,
+        # code_challenge_method=code_challenge_method,
+    )
+    # not yet supported by the python-keycloak library, so we need to add PKCE params manually
+    auth_url += f"&code_challenge={code_challenge}&code_challenge_method={code_challenge_method}"
+
+    sys.stderr.write("\n1. Please open the following URL in your browser to log in:")
+    sys.stderr.write("-" * 70 + "\n")
+    sys.stderr.write(auth_url + "\n")
+    sys.stderr.write("-" * 70 + "\n")
+
+    if platform.system() == "Windows" or os.environ.get("DISPLAY"):
+        # open the URL in the default browser on supported platforms
+        try:
+            webbrowser.open_new_tab(auth_url)
+            sys.stderr.write("The login page was opened in your default browser.\n")
+        except Exception:
+            pass
+
+    sys.stderr.write(
+        f"\n2. Please copy the complete redirect URL (starting with {redirect_uri}?) and paste it here:\n"
+    )
+    try:
+        redirect_full_url = input("> ")
+    except (EOFError, KeyboardInterrupt):
+        sys.stderr.write("\nInput cancelled.\n")
+        raise AuthenticationError(
+            "No Callback-URL entered - Authorization flow aborted."
+        )
+
+    # Parse the entered URL and extract State/Code
+    try:
+        parsed_url = urlparse(redirect_full_url)
+        query_params = parse_qs(parsed_url.query)
+
+        if "code" not in query_params or "state" not in query_params:
+            log.error("Code or State-Param missing in Redirect-URL.")
+            raise AuthenticationError("missing code or state-param in redirect URL")
+
+        # Verify the returned State against the initially sent
+        returned_state = query_params["state"][0]
+        if returned_state != state:
+            log.warning(
+                "SECURITY ERROR: The returned 'state' does not match the sent state."
+            )
+            log.debug(f"Sent: {state}, Received: {returned_state}")
+            raise AuthenticationError("Attack attempt detected (CSRF)")
+
+        auth_code = query_params["code"][0]
+        log.debug(
+            f"[OK] State verified and authorization code successfully received: {auth_code[:10]}..."
+        )
+
+    except Exception as e:
+        log.error(f"ERROR parsing URL: {e}")
+        raise AuthenticationError("Invalid Redirect URL")
+
+    # Exchange code for token (with Code Verifier for PKCE)
+    log.debug("Exchanging code for Access Token (with PKCE Verifier)...")
+    try:
+        token_response = k_client.token(
+            grant_type="authorization_code",
+            code=auth_code,
+            redirect_uri=redirect_uri,
+            code_verifier=code_verifier,  # key for PKCE
+        )
+
+        id_token = token_response.get("id_token") or ""
+        sys.stderr.write("\n--- SUCCESS! Token received ---\n")
+
+        # # Validate ID Token and verify Nonce
+        id_token_nonce = k_client.decode_token(id_token).get("nonce")
+        if id_token_nonce != nonce:
+            raise AuthenticationError("Nonce mismatch in ID Token!")
+
+        return token_response
+
+    except Exception as e:
+        log.error(f"ERROR during token exchange (Token endpoint call): {e}")
+        raise

{nextlayer_sdk_python-1.0.2 → nextlayer_sdk_python-1.1.0}/src/nextlayer/sdk/auth_httpx.py

@@ -7,7 +7,12 @@ from .auth import NlAuth
 
 class NlHttpxAuth(httpx.Auth):
     def __init__(self, *args, **kwargs):
-        self.nlauth = NlAuth(*args, **kwargs)
+        if len(args) == 1 and len(kwargs) == 0 and isinstance(args[0], NlAuth):
+            # pass an existing NlAuth instance directly
+            self.nlauth = args[0]
+        else:
+            # pass all arguments to NlAuth constructor and create NlAuth instance internally
+            self.nlauth = NlAuth(*args, **kwargs)
 
     def auth_flow(
         self, request: httpx.Request

nextlayer_sdk_python-1.1.0/src/nextlayer/sdk/utils.py

@@ -0,0 +1,19 @@
+import base64
+import os
+
+
+def generate_random_string(length=32):
+    return base64.urlsafe_b64encode(os.urandom(length)).rstrip(b"=").decode("utf-8")
+
+
+def get_current_user_homedir() -> str:
+    try:
+        # this is the reliable/correct method that also works in cases
+        # where e.g., process-manager like gunicorn changes the effective UID
+        # but preserves the environment
+        import pwd
+
+        return pwd.getpwuid(os.getuid()).pw_dir
+    except Exception:
+        # fallback for (non-unix) platforms without `pwd` module
+        return os.path.expanduser("~")