python-general-be-lib 0.11.2__tar.gz → 0.12.0__tar.gz

{python_general_be_lib-0.11.2 → python_general_be_lib-0.12.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: python-general-be-lib
-Version: 0.11.2
-Summary: General purpose backend library — SQLAlchemy CRUD/Geometry repositories, FastAPI exceptions, Pydantic base models, logger utilities.
+Version: 0.12.0
+Summary: General purpose backend library — SQLAlchemy CRUD/Geometry repositories, FastAPI exceptions, Pydantic base models, Keycloak JWT auth, logger utilities.
 Author-email: Andrea Di Placido <a.diplacido@arpes.it>, "Arpes S.r.l." <it.admin@arpes.it>
 License: MIT
 Project-URL: Homepage, https://github.com/Arpes-IS/python-general-be-lib
 Project-URL: Repository, https://github.com/Arpes-IS/python-general-be-lib
 Project-URL: Changelog, https://github.com/Arpes-IS/python-general-be-lib/blob/main/CHANGELOG.md
-Keywords: backend,sqlalchemy,fastapi,pydantic,repository,crud,geoalchemy2
+Keywords: backend,sqlalchemy,fastapi,pydantic,repository,crud,geoalchemy2,keycloak,jwt
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -23,7 +23,10 @@ Requires-Dist: fastapi>=0.100.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: sqlalchemy>=2.0.0
 Requires-Dist: geoalchemy2>=0.14.0
+Provides-Extra: auth
+Requires-Dist: pyjwt[crypto]>=2.8; extra == "auth"
 Provides-Extra: dev
+Requires-Dist: pyjwt[crypto]>=2.8; extra == "dev"
 Requires-Dist: pytest>=7; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: pytest-benchmark>=5; extra == "dev"
@@ -31,13 +34,14 @@ Requires-Dist: testcontainers[postgres]>=4; extra == "dev"
 Requires-Dist: psycopg[binary]>=3; extra == "dev"
 Requires-Dist: build; extra == "dev"
 Requires-Dist: twine; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
 Dynamic: license-file
 
 # python-general-be-lib
 
 Libreria backend general purpose per progetti Python: repository CRUD e spaziali
 su **SQLAlchemy** / **GeoAlchemy2**, eccezioni **FastAPI**, modelli base
-**Pydantic** e utility di logging.
+**Pydantic**, autenticazione **Keycloak** e utility di logging.
 
 - Distribuzione PyPI: `python-general-be-lib`
 - Pacchetto importabile: `general`
@@ -45,6 +49,7 @@ su **SQLAlchemy** / **GeoAlchemy2**, eccezioni **FastAPI**, modelli base
 
 ```bash
 pip install python-general-be-lib
+pip install 'python-general-be-lib[auth]'     # con l'autenticazione Keycloak (pyjwt[crypto])
 ```
 
 ```python
@@ -71,6 +76,8 @@ repo.find(active=True, order_by="name", asc=True)
 | Basi | `Base` (declarative base estesa), `ExtBaseModel`, `CamelExtBaseModel` |
 | Paginazione | `PaginatorRequestModel`, `PaginatorResponseModel` |
 | Eccezioni | `ExceptionInterface` e sottoclassi HTTP (400/401/403/404/422/500/503) |
+| Autenticazione (extra `[auth]`) | `KeycloakAuth`, `AuthContextMiddleware`, `JWTModel`, `RoleChecker` — verifica dei token Keycloak via JWKS, dependency FastAPI, ruoli |
+| Contesto | `current_user`, `current_jwt` — utente e claim della richiesta, per l'audit |
 | Logging | `init_logger`, decorator `@log` |
 
 ---

{python_general_be_lib-0.11.2 → python_general_be_lib-0.12.0}/README.md

@@ -2,7 +2,7 @@
 
 Libreria backend general purpose per progetti Python: repository CRUD e spaziali
 su **SQLAlchemy** / **GeoAlchemy2**, eccezioni **FastAPI**, modelli base
-**Pydantic** e utility di logging.
+**Pydantic**, autenticazione **Keycloak** e utility di logging.
 
 - Distribuzione PyPI: `python-general-be-lib`
 - Pacchetto importabile: `general`
@@ -10,6 +10,7 @@ su **SQLAlchemy** / **GeoAlchemy2**, eccezioni **FastAPI**, modelli base
 
 ```bash
 pip install python-general-be-lib
+pip install 'python-general-be-lib[auth]'     # con l'autenticazione Keycloak (pyjwt[crypto])
 ```
 
 ```python
@@ -36,6 +37,8 @@ repo.find(active=True, order_by="name", asc=True)
 | Basi | `Base` (declarative base estesa), `ExtBaseModel`, `CamelExtBaseModel` |
 | Paginazione | `PaginatorRequestModel`, `PaginatorResponseModel` |
 | Eccezioni | `ExceptionInterface` e sottoclassi HTTP (400/401/403/404/422/500/503) |
+| Autenticazione (extra `[auth]`) | `KeycloakAuth`, `AuthContextMiddleware`, `JWTModel`, `RoleChecker` — verifica dei token Keycloak via JWKS, dependency FastAPI, ruoli |
+| Contesto | `current_user`, `current_jwt` — utente e claim della richiesta, per l'audit |
 | Logging | `init_logger`, decorator `@log` |
 
 ---

python_general_be_lib-0.12.0/general/auth/__init__.py

@@ -0,0 +1,68 @@
+"""Authentication against a Keycloak realm, shared by the backends.
+
+``KeycloakAuth`` verifies the access tokens of a realm — signature through the keys of its
+JWKS endpoint, expiry, audience, issuer — and exposes the FastAPI dependencies built on
+it; ``AuthContextMiddleware`` verifies the token once per request and publishes the user
+and the claims in ``general.context``. It needs the ``[auth]`` extra (``pyjwt[crypto]``).
+
+The public symbols are resolved lazily (PEP 562): importing this package does not import
+the modules behind them, so reaching one of them does not pay for the heavier siblings.
+The ``TYPE_CHECKING`` block is what keeps the static types — without it a type checker
+would see every symbol as ``Any``, silently, and the ``py.typed`` marker would promise
+types the consumer does not get.
+"""
+from typing import TYPE_CHECKING
+
+__all__ = [
+    "AuthContextMiddleware",
+    "JWTModel",
+    "RealmAccessModel",
+    "JwksKeyProvider",
+    "KeycloakAuth",
+    "RoleChecker",
+]
+
+if TYPE_CHECKING:  # i type checker leggono da qui, il runtime no
+    from .jwt_model import JWTModel, RealmAccessModel
+    from .key_provider import JwksKeyProvider
+    from .keycloak_auth import KeycloakAuth, RoleChecker
+    from .middleware import AuthContextMiddleware
+
+_MODULES = {
+    "JWTModel": ".jwt_model",
+    "RealmAccessModel": ".jwt_model",
+    "JwksKeyProvider": ".key_provider",
+    "KeycloakAuth": ".keycloak_auth",
+    "RoleChecker": ".keycloak_auth",
+    "AuthContextMiddleware": ".middleware",
+}
+
+
+def __getattr__(name: str):
+    """Resolve a public symbol, importing its module on first access.
+
+    Args:
+        name (str): Name of the attribute being read.
+
+    Returns:
+        Any: The requested symbol.
+
+    Raises:
+        AttributeError: If the name is not part of the public surface.
+    """
+    module = _MODULES.get(name)
+    if module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    from importlib import import_module
+
+    return getattr(import_module(module, __name__), name)
+
+
+def __dir__() -> list[str]:
+    """List the public surface without importing anything.
+
+    Returns:
+        list[str]: The names in ``__all__``.
+    """
+    return list(__all__)

python_general_be_lib-0.12.0/general/auth/jwt_model.py

@@ -0,0 +1,92 @@
+"""Pydantic models of the claims of a Keycloak access token.
+
+``JWTModel`` declares the standard claims Keycloak puts in an access token. The claims a
+realm adds through its own mappers (``user_id``, ``partner_id``, …) do not belong here:
+each backend declares them in a subclass and passes it to ``KeycloakAuth`` as ``model``.
+"""
+
+__all__ = ["JWTModel", "RealmAccessModel"]
+
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict
+
+
+class RealmAccessModel(BaseModel):
+    """Roles granted to the user, in the shape Keycloak uses for both realm and client roles.
+
+    Attributes:
+        roles (list[str]): Names of the roles. Empty when the claim carries none.
+    """
+    roles: list[str] = []
+
+
+class JWTModel(BaseModel):
+    """Standard claims of a Keycloak access token.
+
+    Every claim is optional, so a token lacking one validates anyway, and the unknown ones
+    are ignored: a realm mapper added after deployment does not break the validation. To
+    read a custom claim, declare it in a subclass.
+
+    Attributes:
+        aud (str | list[str], optional): Audience. Keycloak emits a string with one
+            audience and a list with more than one.
+        sub (str, optional): Identifier of the user in the realm.
+        realm_access (RealmAccessModel, optional): Realm roles of the user.
+        resource_access (dict[str, RealmAccessModel], optional): Client roles of the user,
+            keyed by client id.
+    """
+    model_config = ConfigDict(extra="ignore")
+
+    exp: Optional[int] = None
+    iat: Optional[int] = None
+    jti: Optional[str] = None
+    iss: Optional[str] = None
+    aud: Optional[str | list[str]] = None
+    sub: Optional[str] = None
+    typ: Optional[str] = None
+    azp: Optional[str] = None
+    session_state: Optional[str] = None
+    acr: Optional[str] = None
+    realm_access: Optional[RealmAccessModel] = None
+    resource_access: Optional[dict[str, RealmAccessModel]] = None
+    scope: Optional[str] = None
+    sid: Optional[str] = None
+    email_verified: Optional[bool] = None
+    name: Optional[str] = None
+    preferred_username: Optional[str] = None
+    given_name: Optional[str] = None
+    family_name: Optional[str] = None
+    email: Optional[str] = None
+
+    def roles_of(self, client: Optional[str] = None) -> list[str]:
+        """Return the roles of the user, empty when the token carries none.
+
+        Args:
+            client (str, optional): Client id whose roles are read from
+                ``resource_access``. When omitted, the realm roles are read from
+                ``realm_access``.
+
+        Returns:
+            list[str]: The roles, never ``None``.
+        """
+        if client is None:
+            return self.realm_access.roles if self.realm_access is not None else []
+        access = (self.resource_access or {}).get(client)
+        return access.roles if access is not None else []
+
+    def has_role(self, role: str, client: Optional[str] = None) -> bool:
+        """Tell whether the user holds a role.
+
+        Unlike ``role in jwt.realm_access.roles`` it does not raise when the token carries
+        no roles at all.
+
+        Args:
+            role (str): Name of the role.
+            client (str, optional): Client id the role belongs to. When omitted, the role
+                is looked up among the realm roles.
+
+        Returns:
+            bool: ``True`` if the user holds the role.
+        """
+        return role in self.roles_of(client)

python_general_be_lib-0.12.0/general/auth/key_provider.py

@@ -0,0 +1,203 @@
+"""Signing keys of a Keycloak realm, read from its JWKS endpoint and cached in memory.
+
+The JWKS endpoint (``/protocol/openid-connect/certs``) publishes every active key of the
+realm with its ``kid``, and the token header names the one it was signed with: during a
+key rotation both keys are published, so no token is rejected while it happens. The
+``public_key`` field of the realm endpoint, read by the handlers this module replaces,
+carries one key only.
+"""
+
+__all__ = ["JwksKeyProvider"]
+
+import json
+import logging
+import threading
+import time
+from typing import Any, Callable, Optional
+from urllib.request import urlopen
+
+try:
+    from jwt import PyJWK, PyJWKSet
+except ImportError as e:  # pragma: no cover - dipende dagli extra installati
+    raise ImportError("general.auth needs the [auth] extra: pip install 'python-general-be-lib[auth]'") from e
+
+from ..exception.crud_exceptions import ServiceUnavailableException
+
+
+class JwksKeyProvider:
+    """Thread-safe, in-memory cache of the signing keys of a realm.
+
+    The keys are fetched on the first request, and fetched again when the cache is older
+    than ``ttl`` or a token names a ``kid`` the cache does not know, which is how a key
+    rotation is picked up. Every fetch, forced ones included, is **rate limited** to one per
+    ``min_refresh_interval``: a token naming a made-up ``kid`` cannot turn each request
+    into a call to Keycloak. A failed fetch keeps the keys already cached, so an
+    unreachable Keycloak does not reject tokens it signed before going down.
+
+    Attributes:
+        jwks_url (str): URL of the JWKS endpoint.
+        ttl (float): Seconds after which the cached keys are fetched again.
+        min_refresh_interval (float): Minimum seconds between two fetch attempts.
+        timeout (float): Timeout in seconds of the HTTP request.
+    """
+    __slots__ = (
+        "jwks_url",
+        "ttl",
+        "min_refresh_interval",
+        "timeout",
+        "_fetch",
+        "_lock",
+        "_keys",
+        "_fetched_at",
+        "_last_attempt",
+    )
+
+    def __init__(
+        self,
+        jwks_url: str,
+        ttl: float = 3600,
+        min_refresh_interval: float = 30,
+        timeout: float = 5,
+        fetch: Optional[Callable[[], dict[str, Any]]] = None,
+    ):
+        """Configure the provider. Nothing is fetched until the first key is requested.
+
+        Args:
+            jwks_url (str): URL of the JWKS endpoint, ``http`` or ``https``.
+            ttl (float): Seconds after which the cached keys are fetched again.
+                Default: ``3600``.
+            min_refresh_interval (float): Minimum seconds between two fetch attempts.
+                Default: ``30``.
+            timeout (float): Timeout in seconds of the HTTP request. Default: ``5``.
+            fetch (Callable[[], dict], optional): Function returning the JWKS document,
+                in place of the HTTP request to ``jwks_url``.
+
+        Raises:
+            ValueError: If ``jwks_url`` is not an ``http(s)`` URL.
+        """
+        if not isinstance(jwks_url, str) or not jwks_url.startswith(("http://", "https://")):
+            raise ValueError(f"JwksKeyProvider: jwks_url must be an http(s) URL, got {jwks_url!r}")
+        self.jwks_url = jwks_url
+        self.ttl = ttl
+        self.min_refresh_interval = min_refresh_interval
+        self.timeout = timeout
+        self._fetch = fetch if fetch is not None else self._fetch_jwks
+        self._lock = threading.Lock()
+        self._keys: dict[Optional[str], PyJWK] = {}
+        self._fetched_at: Optional[float] = None
+        self._last_attempt: Optional[float] = None
+
+    def needs_fetch(self, kid: Optional[str]) -> bool:
+        """Tell whether resolving ``kid`` now would make an HTTP request.
+
+        It lets an async caller keep the common case, a fresh key already cached, on the
+        event loop, and move to a worker thread only the calls that would block on the
+        network.
+
+        Args:
+            kid (str, optional): Key id read from the token header.
+
+        Returns:
+            bool: ``True`` if ``get_key`` would fetch the JWKS.
+        """
+        now = time.monotonic()
+        fresh = self._fetched_at is not None and now - self._fetched_at < self.ttl
+        if fresh and self._select(kid) is not None:
+            return False
+        return self._last_attempt is None or now - self._last_attempt >= self.min_refresh_interval
+
+    def get_key(self, kid: Optional[str]) -> Optional[PyJWK]:
+        """Return the signing key named by ``kid``, fetching the JWKS when needed.
+
+        Args:
+            kid (str, optional): Key id read from the token header. A token without one is
+                accepted only while the realm publishes a single signing key.
+
+        Returns:
+            PyJWK | None: The key, or ``None`` if the realm does not publish it.
+
+        Raises:
+            ServiceUnavailableException: If no key has ever been fetched, because the
+                JWKS endpoint is unreachable.
+        """
+        if self.needs_fetch(kid):
+            with self._lock:
+                # ricontrollato sotto lock: un altro thread può aver appena fatto il fetch
+                if self.needs_fetch(kid):
+                    self._refresh()
+        if not self._keys:
+            raise ServiceUnavailableException()
+        return self._select(kid)
+
+    def refresh(self) -> bool:
+        """Fetch the JWKS now, ignoring both the TTL and the rate limit.
+
+        Meant for the startup, to fill the cache before the first request.
+
+        Returns:
+            bool: ``True`` if the fetch succeeded. On failure the keys already cached are
+            kept.
+        """
+        with self._lock:
+            return self._refresh()
+
+    def _refresh(self) -> bool:
+        """Fetch and parse the JWKS, replacing the cache only on success. Call under lock.
+
+        Returns:
+            bool: ``True`` if the fetch succeeded.
+        """
+        # `_last_attempt` si scrive a tentativo **concluso**: scritto prima, chi arriva durante
+        # il primo fetch vedrebbe il rate limit attivo e la cache vuota, e avrebbe un 503
+        # invece di aspettare sul lock l'esito del fetch in corso
+        try:
+            keys = self._parse(self._fetch())
+        except Exception as e:
+            self._last_attempt = time.monotonic()
+            logging.warning(f"JWKS fetch from {self.jwks_url} failed - {e!r}")
+            return False
+        self._keys = keys
+        self._fetched_at = self._last_attempt = time.monotonic()
+        return True
+
+    def _select(self, kid: Optional[str]) -> Optional[PyJWK]:
+        """Look ``kid`` up in the cache, without fetching.
+
+        Args:
+            kid (str, optional): Key id read from the token header.
+
+        Returns:
+            PyJWK | None: The cached key, or ``None`` if it is not there.
+        """
+        keys = self._keys
+        if kid is None:
+            return next(iter(keys.values())) if len(keys) == 1 else None
+        return keys.get(kid)
+
+    def _fetch_jwks(self) -> dict[str, Any]:
+        """Download the JWKS document from ``jwks_url``.
+
+        Returns:
+            dict[str, Any]: The parsed JSON document.
+        """
+        with urlopen(self.jwks_url, timeout=self.timeout) as response:
+            return json.load(response)
+
+    @staticmethod
+    def _parse(jwks: dict[str, Any]) -> dict[Optional[str], PyJWK]:
+        """Keep the signing keys of a JWKS document, keyed by ``kid``.
+
+        Keycloak publishes the encryption keys (``"use": "enc"``) at the same endpoint;
+        they cannot verify a signature, so they are left out.
+
+        Args:
+            jwks (dict[str, Any]): The JWKS document.
+
+        Returns:
+            dict[str | None, PyJWK]: The signing keys.
+
+        Raises:
+            PyJWKSetError: If the document holds no usable signing key.
+        """
+        signing = [key for key in jwks.get("keys", []) if key.get("use", "sig") == "sig"]
+        return {key.key_id: key for key in PyJWKSet.from_dict({"keys": signing}).keys}