nextlayer-sdk-python 1.2.0__tar.gz → 1.3.0__tar.gz

{nextlayer_sdk_python-1.2.0 → nextlayer_sdk_python-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextlayer-sdk-python
-Version: 1.2.0
+Version: 1.3.0
 Summary: Client utilities to interact with next layer public APIs
 Author: Wolfgang Powisch
 Author-email: wolfgang.powisch@nextlayer.at
@@ -51,6 +51,10 @@ variable or directly passed to the `NlAuth` constructor.
 Alternatively the password can be suppliend in the `NEXTLAYERSDK_PASSWORD` environment
 variable.
 
+For machine-to-machine authentication (no user account), a `client_secret` can be
+supplied instead of `username`/`password` - see
+[Client Credentials Grant](#client-credentials-grant-service-accounts) below.
+
 ## Usage
 
 ```python
@@ -86,6 +90,29 @@ client = httpx.Client(
 print(client.get("/users/self").json())
 ```
 
+### Client Credentials Grant (service accounts)
+
+For machine-to-machine authentication without a user account, supply a
+`client_secret` instead of `username`/`password`:
+
+```python
+nlauth = NlAuth(client_id="your_id", client_secret="topsecret")
+access_token = nlauth.get_access_token()
+```
+
+The `client_id`/`client_secret` can also be set via the `NEXTLAYERSDK_CLIENT_ID`/
+`NEXTLAYERSDK_CLIENT_SECRET` environment variables.
+Whenever a `client_secret` is present (non-empty), `NlAuth` auto-detects it and uses
+the OAuth2 `client_credentials` grant instead of the password grant - no `username`
+is needed or used. It is mutually exclusive with `browser_login=True` (passing both
+raises `ValueError`).
+
+Note: `client_secret` is deliberately **not** exposed as a `nextlayer-auth` CLI flag -
+command-line arguments are visible to other local users via `ps`/process listings and
+get persisted in shell history. Use the environment variable, the config file, or the
+constructor param instead.
+
+
 ## Usage fron commandline
 
 The package also installs a commandline utility `nextlayer-auth` which takes care

{nextlayer_sdk_python-1.2.0 → nextlayer_sdk_python-1.3.0}/README.md

@@ -30,6 +30,10 @@ variable or directly passed to the `NlAuth` constructor.
 Alternatively the password can be suppliend in the `NEXTLAYERSDK_PASSWORD` environment
 variable.
 
+For machine-to-machine authentication (no user account), a `client_secret` can be
+supplied instead of `username`/`password` - see
+[Client Credentials Grant](#client-credentials-grant-service-accounts) below.
+
 ## Usage
 
 ```python
@@ -65,6 +69,29 @@ client = httpx.Client(
 print(client.get("/users/self").json())
 ```
 
+### Client Credentials Grant (service accounts)
+
+For machine-to-machine authentication without a user account, supply a
+`client_secret` instead of `username`/`password`:
+
+```python
+nlauth = NlAuth(client_id="your_id", client_secret="topsecret")
+access_token = nlauth.get_access_token()
+```
+
+The `client_id`/`client_secret` can also be set via the `NEXTLAYERSDK_CLIENT_ID`/
+`NEXTLAYERSDK_CLIENT_SECRET` environment variables.
+Whenever a `client_secret` is present (non-empty), `NlAuth` auto-detects it and uses
+the OAuth2 `client_credentials` grant instead of the password grant - no `username`
+is needed or used. It is mutually exclusive with `browser_login=True` (passing both
+raises `ValueError`).
+
+Note: `client_secret` is deliberately **not** exposed as a `nextlayer-auth` CLI flag -
+command-line arguments are visible to other local users via `ps`/process listings and
+get persisted in shell history. Use the environment variable, the config file, or the
+constructor param instead.
+
+
 ## Usage fron commandline
 
 The package also installs a commandline utility `nextlayer-auth` which takes care

{nextlayer_sdk_python-1.2.0 → nextlayer_sdk_python-1.3.0}/pyproject.toml

@@ -3,7 +3,7 @@ name = "nextlayer-sdk-python"
 packages = [
     { include = "nextlayer", from="src" }
 ]
-version = "1.2.0"
+version = "1.3.0"
 description = "Client utilities to interact with next layer public APIs"
 readme = "README.md"
 authors = ["Wolfgang Powisch <wolfgang.powisch@nextlayer.at>"]

{nextlayer_sdk_python-1.2.0 → nextlayer_sdk_python-1.3.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.2.0"
+__version__ = "v1.3.0"

{nextlayer_sdk_python-1.2.0 → nextlayer_sdk_python-1.3.0}/src/nextlayer/sdk/auth.py

@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+import asyncio
 import datetime
 import getpass
 import json
@@ -11,7 +12,7 @@ from typing import Any
 import jwt
 import yaml
 from keycloak import KeycloakOpenID
-from keycloak.exceptions import KeycloakGetError
+from keycloak.exceptions import KeycloakOperationError
 from pydantic import BaseModel, Field
 
 from . import auth_code_browser_flow, errors, utils
@@ -43,6 +44,7 @@ class PersistentConfig(BaseModel):
     client_id: str = DEFAULT_CLIENT_ID
     username: str | None = None
     password: str | None = None
+    client_secret: str | None = None
     extra_params: dict[str, Any] = Field(default_factory=dict)
 
     # state updated by NlAuth itself:
@@ -113,19 +115,24 @@ class NlAuth(object):
         realm_name: str | None = None,
         client_id: str | None = None,
         username: str | None = None,
+        client_secret: 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,
+        client_id_envvar="NEXTLAYERSDK_CLIENT_ID",
         username_envvar="NEXTLAYERSDK_USERNAME",
         password_envvar="NEXTLAYERSDK_PASSWORD",
+        client_secret_envvar="NEXTLAYERSDK_CLIENT_SECRET",
     ):
         if config_defaults is None:
             config_defaults = PersistentConfig()
 
+        self.client_id_envvar = client_id_envvar
         self.username_envvar = username_envvar
         self.password_envvar = password_envvar
+        self.client_secret_envvar = client_secret_envvar
 
         self.ask_totp = ask_totp
         self.browser_login = browser_login
@@ -138,12 +145,24 @@ class NlAuth(object):
 
         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
+        new_client_id = (
+            client_id
+            or os.environ.get(self.client_id_envvar)
+            or self.store.config.client_id
+        )
         self.username = (
             username
             or os.environ.get(self.username_envvar)
             or self.store.config.username
         )
+        self.client_secret = (
+            client_secret
+            or os.environ.get(self.client_secret_envvar)
+            or self.store.config.client_secret
+        )
+
+        if self.browser_login and self.client_secret:
+            raise ValueError("browser_login and client_secret are mutually exclusive")
 
         self.store.config.server_url = new_server_url
         self.store.config.realm_name = new_realm_name
@@ -151,15 +170,26 @@ class NlAuth(object):
 
         if self.username:
             self.store.config.username = self.username
+        # unlike username/client_id, client_secret is intentionally never written
+        # back into self.store.config here - like password, it must not be
+        # persisted to the YAML config file in plaintext.
 
         # Configure client
         self.keycloak_openid = KeycloakOpenID(
             server_url=new_server_url,
             client_id=new_client_id,
             realm_name=new_realm_name,
+            client_secret_key=self.client_secret,
             verify=True,
         )
 
+        # shared by NlHttpxAuth.async_auth_flow() so that multiple async Auth
+        # wrappers around the same NlAuth instance (e.g. one per API client,
+        # all backed by one shared NlAuth singleton) serialize their
+        # get_access_token() calls instead of racing concurrent
+        # do_refresh()/do_login() calls against Keycloak.
+        self.async_lock = asyncio.Lock()
+
     def token_expired(self) -> bool:
         now = int(time.time())
         exp_at = self.store.config.expires_at
@@ -190,13 +220,19 @@ class NlAuth(object):
 
     def update_tokens(self, tokens: dict[str, Any]) -> str:
         log.debug(
-            f"update_tokens: expires_in={tokens['expires_in']!r} refresh_expires_in={tokens['refresh_expires_in']!r}"
+            f"update_tokens: expires_in={tokens['expires_in']!r} refresh_expires_in={tokens.get('refresh_expires_in')!r}"
         )
         self.store.config.expires_at = int(time.time()) + int(
             tokens["expires_in"] * 0.75
         )
-        self.store.config.refresh_expires_at = int(time.time()) + int(
-            (tokens["refresh_expires_in"] or 86400) * 0.75
+        refresh_expires_in = tokens.get("refresh_expires_in")
+        # client_credentials grant responses typically have no refresh_token /
+        # refresh_expires_in at all - there is nothing to refresh in that case,
+        # so None (rather than some made-up default) is the correct value here
+        self.store.config.refresh_expires_at = (
+            int(time.time()) + int(refresh_expires_in * 0.75)
+            if refresh_expires_in is not None
+            else None
         )
         self.store.config.tokens = tokens
         return tokens["access_token"]
@@ -210,6 +246,12 @@ class NlAuth(object):
                 self.keycloak_openid,
                 redirect_uri=self.browser_login_redirect_uri,
             )
+        elif self.client_secret:
+            extra = self.store.config.extra_params
+            log.debug("make keycloak token-request via client_credentials grant")
+            tokens = self.keycloak_openid.token(
+                grant_type="client_credentials", **extra
+            )
         else:
             password = (
                 password
@@ -262,9 +304,12 @@ class NlAuth(object):
             tokens = self.keycloak_openid.refresh_token(
                 (self.store.config.tokens or {}).get("refresh_token") or ""
             )
-        except KeycloakGetError as e:
+        except KeycloakOperationError as e:
             # 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
+            # note: the keycloak-python client raises KeycloakPostError (not
+            # KeycloakGetError) here - KeycloakOperationError is their common
+            # base class, so this also covers that case
             sys.stderr.write("token refresh failed: %s\n" % (e,))
             return self.do_login()
 
@@ -279,7 +324,12 @@ class NlAuth(object):
                 self.store.reload_if_modified()
             except FileNotFoundError:
                 pass
-            if self.refresh_expired():
+            if self.client_secret and self.token_expired():
+                # client_credentials grant tokens come without a refresh_token
+                # (see do_login()), so request a fresh one directly instead of
+                # attempting a refresh that would only fail
+                access_token = self.do_login()
+            elif not self.client_secret and self.refresh_expired():
                 access_token = self.do_login()
             elif self.token_expired():
                 access_token = self.do_refresh()
@@ -332,6 +382,10 @@ def parse_commandline_args():
         "-i", "--client-id", help=f"keycloak client_id - default: {DEFAULT_CLIENT_ID}"
     )
     parser.add_argument("-u", "--username", help="username")
+    # Deliberately no --client-secret CLI flag: command-line arguments are visible
+    # to other local users via `ps`/process listings and get persisted in shell
+    # history. Use the NEXTLAYERSDK_CLIENT_SECRET environment variable, the config
+    # file, or the NlAuth(client_secret=...) constructor param instead.
     parser.add_argument("-a", "--aud", help="set audience - default: not set")
     parser.add_argument(
         "-t",

{nextlayer_sdk_python-1.2.0 → nextlayer_sdk_python-1.3.0}/src/nextlayer/sdk/auth_httpx.py

@@ -14,7 +14,6 @@ class NlHttpxAuth(httpx.Auth):
         else:
             # pass all arguments to NlAuth constructor and create NlAuth instance internally
             self.nlauth = NlAuth(*args, **kwargs)
-        self._lock = asyncio.Lock()
 
     def auth_flow(
         self, request: httpx.Request
@@ -27,9 +26,12 @@ class NlHttpxAuth(httpx.Auth):
     ) -> AsyncGenerator[httpx.Request, httpx.Response]:
         # NlAuth.get_access_token() does blocking file I/O and, on refresh/login,
         # a blocking HTTP call to Keycloak - offload it so it doesn't stall the
-        # event loop. The lock avoids concurrent coroutines all triggering
-        # redundant refresh/login calls when the token expires under load.
-        async with self._lock:
+        # event loop. The lock lives on the NlAuth instance (not here) so that
+        # multiple NlHttpxAuth wrappers sharing one NlAuth (e.g. one per API
+        # client, backed by a shared NlAuth singleton) also share the lock -
+        # otherwise they could still race concurrent refresh/login calls
+        # against Keycloak, which the lock is meant to prevent.
+        async with self.nlauth.async_lock:
             access_token = await asyncio.to_thread(self.nlauth.get_access_token)
         request.headers["Authorization"] = "Bearer " + access_token
         yield request