pyobs-auth 2.0.0.dev10__tar.gz → 2.1.0__tar.gz

{pyobs_auth-2.0.0.dev10 → pyobs_auth-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyobs-auth
-Version: 2.0.0.dev10
+Version: 2.1.0
 Summary: Shared Keycloak/OIDC authentication client for pyobs web services
 Author-email: Tim-Oliver Husser <thusser@uni-goettingen.de>
 License-Expression: MIT

{pyobs_auth-2.0.0.dev10 → pyobs_auth-2.1.0}/pyobs_auth/authentication.py

@@ -9,19 +9,25 @@ issuer.
 This class is written to be safe to stack alongside another Bearer-scheme authenticator that
 can't be modified (e.g. an existing legacy OAuth2 BearerAuthentication) - see below.
 
-A resolved user with `is_active=False` is refused - USER_RESOLVER implementations mint new
-accounts inactive by convention, giving each service an independent local activation gate on top
-of whatever access control Keycloak itself does (a kill switch that doesn't depend on Keycloak
-realm/client config alone).
+The primary authorization gate is claims-based (`PYOBS_AUTH['REQUIRED_GROUPS']`/`REQUIRED_ROLES'`,
+see `pyobs_auth.authorization`) - Keycloak group/role membership carried in the token, checked
+before the user's first login even needs to happen. The local `is_active` check only applies when
+`PYOBS_AUTH['ENFORCE_LOCAL_ACTIVE']` is set, preserving it as an opt-in, Keycloak-independent kill
+switch rather than the default gate.
 """
 
 from __future__ import annotations
 
+import logging
+
 from rest_framework import authentication, exceptions
 
+from .authorization import AuthorizationError, authorize
 from .settings import get_settings
 from .validation import TokenValidationError, TokenValidator
 
+_logger = logging.getLogger(__name__)
+
 
 class KeycloakAuthentication(authentication.BaseAuthentication):
     www_authenticate_realm = "api"
@@ -51,11 +57,21 @@ class KeycloakAuthentication(authentication.BaseAuthentication):
         except TokenValidationError as exc:
             raise exceptions.AuthenticationFailed(str(exc)) from exc
 
+        # Checked before resolving a local user - an unauthorized caller must not mint a User
+        # row just by presenting a validly-signed-but-ungrouped token.
+        try:
+            authorize(claims, settings)
+        except AuthorizationError as exc:
+            raise exceptions.AuthenticationFailed(str(exc)) from exc
+        except ValueError:
+            _logger.exception("PYOBS_AUTH['REQUIRED_ROLES'] is malformed")
+            raise
+
         user_resolver = settings.resolve_user_callable()
         user = user_resolver(claims)
         if user is None:
             raise exceptions.AuthenticationFailed("No local user for this token")
-        if not user.is_active:
+        if settings.enforce_local_active and not user.is_active:
             raise exceptions.AuthenticationFailed("Account pending activation")
 
         return (user, claims)

pyobs_auth-2.1.0/pyobs_auth/authorization.py

@@ -0,0 +1,61 @@
+"""Claims-based authorization gate: Keycloak group/role membership as the authorization source
+of truth, replacing per-service local `is_active` activation. See pyobs-core's
+`specs/design/shared-authz-keycloak.md` and ADR `0014-centralized-authorization-via-keycloak-groups.md`
+for the reasoning.
+
+Neither `REQUIRED_GROUPS` nor `REQUIRED_ROLES` set -> `authorize()` always passes (opt-in gate,
+current behavior unchanged). Both set -> both must pass (AND, not OR) - there's no fleet use case
+today that needs "either this group or that role", and OR would be a silent surprise for whoever
+sets both expecting an AND.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .settings import KeycloakSettings
+
+
+class AuthorizationError(Exception):
+    pass
+
+
+def _has_required_groups(claims: dict[str, Any], required_groups: tuple[str, ...]) -> bool:
+    groups = set(claims.get("groups") or [])
+    return all(group in groups for group in required_groups)
+
+
+def _has_required_roles(claims: dict[str, Any], required_roles: tuple[str, ...]) -> bool:
+    realm_roles = set((claims.get("realm_access") or {}).get("roles") or [])
+    resource_access = claims.get("resource_access") or {}
+
+    for required in required_roles:
+        kind, _, name = required.partition(":")
+        if kind == "realm":
+            if name not in realm_roles:
+                return False
+        elif kind == "client":
+            client_id, _, role = name.partition(":")
+            client_roles = set((resource_access.get(client_id) or {}).get("roles") or [])
+            if role not in client_roles:
+                return False
+        else:
+            raise ValueError(
+                f"malformed PYOBS_AUTH['REQUIRED_ROLES'] entry {required!r} -"
+                " expected 'realm:<role>' or 'client:<client_id>:<role>'"
+            )
+    return True
+
+
+def authorize(claims: dict[str, Any], settings: KeycloakSettings) -> None:
+    """Raise AuthorizationError unless `claims` satisfies every configured REQUIRED_GROUPS entry
+    (full group paths, e.g. `/pyobs-archive`) and every configured REQUIRED_ROLES entry (realm
+    roles as `realm:<role>`, client roles as `client:<client_id>:<role>`).
+    """
+    if not settings.required_groups and not settings.required_roles:
+        return
+
+    if not _has_required_groups(claims, settings.required_groups):
+        raise AuthorizationError("not authorized")
+    if not _has_required_roles(claims, settings.required_roles):
+        raise AuthorizationError("not authorized")

{pyobs_auth-2.0.0.dev10 → pyobs_auth-2.1.0}/pyobs_auth/client.py

@@ -11,13 +11,22 @@ from typing import Any
 from urllib.parse import urlencode
 
 import requests
+from requests.exceptions import RequestException
 
 from .discovery import fetch_discovery_document
 from .settings import KeycloakSettings
 
 
 class TokenExchangeError(Exception):
-    pass
+    """`error_code` is the OAuth `error` field from the token endpoint's JSON body, when the
+    endpoint responded at all (e.g. "invalid_grant" for a revoked/expired/reused refresh token).
+    None for a connection-level failure or a non-JSON/unrecognized response - callers that need to
+    tell "genuinely revoked" apart from "couldn't even ask" should check this rather than assume
+    every TokenExchangeError means the former."""
+
+    def __init__(self, message: str, *, error_code: str | None = None) -> None:
+        super().__init__(message)
+        self.error_code = error_code
 
 
 def _b64url(raw: bytes) -> str:
@@ -137,7 +146,20 @@ class KeycloakClient:
         return f"{document.end_session_endpoint}?{urlencode(params)}"
 
     def _post_token(self, token_endpoint: str, data: dict[str, str]) -> dict[str, Any]:
-        response = self._session.post(token_endpoint, data=data, timeout=10.0)
+        try:
+            response = self._session.post(token_endpoint, data=data, timeout=10.0)
+        except RequestException as exc:
+            raise TokenExchangeError(f"could not reach token endpoint: {exc}") from exc
+
         if response.status_code != 200:
-            raise TokenExchangeError(f"token endpoint returned {response.status_code}: {response.text}")
+            error_code = None
+            try:
+                body = response.json()
+            except ValueError:
+                body = None
+            if isinstance(body, dict):
+                error_code = body.get("error")
+            raise TokenExchangeError(
+                f"token endpoint returned {response.status_code}: {response.text}", error_code=error_code
+            )
         return response.json()

pyobs_auth-2.1.0/pyobs_auth/middleware.py

@@ -0,0 +1,152 @@
+"""Session-refresh middleware: once the access token that established a browser session has
+expired, silently exchange the stored refresh token for a new one, re-validate the resulting
+claims, and re-run the authorization gate - ending the session if it now fails.
+
+Without this, a plain Django session never re-contacts Keycloak after login, so a revoked group/
+role (or a synced local flag like `is_superuser`) would only take effect at the user's next login,
+bounded only by `SESSION_COOKIE_AGE`, not by any token lifetime. See pyobs-core's
+`specs/design/shared-authz-keycloak.md`, "Revocation model and freshness".
+
+Runs lazily, on whichever request happens to land after expiry - no background task, and no
+Keycloak round trip at all while the cached access token is still valid, so this doesn't add a
+per-request network dependency.
+
+Add to `MIDDLEWARE`, after `AuthenticationMiddleware` (needs `request.user`)::
+
+    MIDDLEWARE = [
+        ...,
+        "django.contrib.auth.middleware.AuthenticationMiddleware",
+        "pyobs_auth.middleware.KeycloakSessionRefreshMiddleware",
+    ]
+
+A no-op for any request whose session doesn't carry both a refresh token and an access-token
+expiry - i.e. sessions never established via `CallbackView` (a local-password session), sessions
+established before this middleware existed, and sessions where `CallbackView` declined to store
+the refresh token at all (a cookie-backed `SESSION_ENGINE` - see `views.py`).
+
+A failed refresh only ends the session when Keycloak's token endpoint says the grant is actually
+invalid (`error: "invalid_grant"`) - a network error or a 5xx from Keycloak itself leaves the
+session as-is and lets the next request retry, so a Keycloak outage doesn't mass-log-out every
+active session. `invalid_grant` itself is ambiguous between "genuinely revoked" and "a harmless
+race between two concurrent requests both refreshing the same soon-to-be-invalidated token" (only
+relevant if the realm has refresh-token rotation/revocation enabled) - handled by re-reading the
+session from its store before giving up.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import Callable
+from importlib import import_module
+
+from django.conf import settings as django_settings
+from django.contrib.auth import logout
+from django.http import HttpRequest, HttpResponse
+
+from .authorization import AuthorizationError, authorize
+from .client import KeycloakClient, TokenExchangeError
+from .settings import get_settings
+from .validation import TokenValidationError, TokenValidator
+from .views import SESSION_ACCESS_EXPIRES_KEY, SESSION_REFRESH_TOKEN_KEY
+
+_logger = logging.getLogger(__name__)
+
+
+class KeycloakSessionRefreshMiddleware:
+    def __init__(self, get_response: Callable[[HttpRequest], HttpResponse]) -> None:
+        self.get_response = get_response
+
+    def __call__(self, request: HttpRequest) -> HttpResponse:
+        self._maybe_refresh(request)
+        return self.get_response(request)
+
+    def _maybe_refresh(self, request: HttpRequest) -> None:
+        expires_at = request.session.get(SESSION_ACCESS_EXPIRES_KEY)
+        refresh_token = request.session.get(SESSION_REFRESH_TOKEN_KEY)
+        if expires_at is None or refresh_token is None:
+            return
+        if time.time() < expires_at:
+            return
+
+        settings = get_settings()
+        client = KeycloakClient(settings)
+        try:
+            tokens = client.refresh(refresh_token=refresh_token)
+        except TokenExchangeError as exc:
+            self._handle_refresh_failure(request, exc)
+            return
+
+        access_token = tokens.get("access_token")
+        if not access_token:
+            logout(request)
+            return
+
+        validator = TokenValidator(settings)
+        try:
+            claims = validator.validate(access_token)
+        except TokenValidationError:
+            logout(request)
+            return
+
+        if settings.enforce_local_active and not request.user.is_active:
+            logout(request)
+            return
+        try:
+            authorize(claims, settings)
+        except AuthorizationError:
+            logout(request)
+            return
+        except ValueError:
+            _logger.exception("PYOBS_AUTH['REQUIRED_ROLES'] is malformed")
+            raise
+
+        # Re-run the resolver so a claim-derived local flag (e.g. portal's `is_superuser` synced
+        # from a client role) picks up a change made in Keycloak since login, not just at next
+        # login - and so the *current* request sees it too, not only the next one.
+        user_resolver = settings.resolve_user_callable()
+        refreshed_user = user_resolver(claims)
+        if refreshed_user is None:
+            logout(request)
+            return
+        request.user = refreshed_user
+
+        request.session[SESSION_ACCESS_EXPIRES_KEY] = claims["exp"]
+        new_refresh_token = tokens.get("refresh_token")
+        if new_refresh_token:
+            request.session[SESSION_REFRESH_TOKEN_KEY] = new_refresh_token
+
+    def _handle_refresh_failure(self, request: HttpRequest, exc: TokenExchangeError) -> None:
+        if exc.error_code != "invalid_grant":
+            # Keycloak unreachable, a 5xx, a malformed response, etc. - not evidence of
+            # revocation. Leave the session as-is; the next request retries. No backoff/
+            # rate-limiting here - retrying every request during an outage is an accepted
+            # tradeoff at this fleet's scale. debug, not warning: during an outage this fires
+            # once per expired session per request, which would otherwise flood logs.
+            _logger.debug("Keycloak refresh_token grant failed (not invalid_grant): %s", exc)
+            return
+
+        # invalid_grant can mean a genuinely revoked/expired grant, or a benign race: two
+        # concurrent requests both saw the access token as expired and both tried to refresh the
+        # same refresh token - if the realm rotates/revokes refresh tokens on use, only the first
+        # succeeds and the second gets invalid_grant even though nothing was actually revoked.
+        # Re-read the session fresh from its store (not the in-memory request.session, which may
+        # be stale relative to what the concurrent request already wrote) before giving up.
+        fresh = self._fresh_session(request)
+        fresh_expires_at = fresh.get(SESSION_ACCESS_EXPIRES_KEY) if fresh is not None else None
+        if fresh_expires_at is not None and fresh_expires_at > time.time():
+            request.session[SESSION_ACCESS_EXPIRES_KEY] = fresh_expires_at
+            fresh_refresh_token = fresh.get(SESSION_REFRESH_TOKEN_KEY)
+            if fresh_refresh_token is not None:
+                request.session[SESSION_REFRESH_TOKEN_KEY] = fresh_refresh_token
+            return
+
+        logout(request)
+
+    @staticmethod
+    def _fresh_session(request: HttpRequest):
+        session_key = request.session.session_key
+        if not session_key:
+            return None
+        engine = import_module(django_settings.SESSION_ENGINE)
+        return engine.SessionStore(session_key=session_key)

{pyobs_auth-2.0.0.dev10 → pyobs_auth-2.1.0}/pyobs_auth/settings.py

@@ -11,6 +11,10 @@ Read from the Django ``PYOBS_AUTH`` setting, e.g.::
         "POST_LOGOUT_REDIRECT_URI": "https://archive.example.org/",
         # dotted path to a callable(claims: dict) -> django.contrib.auth.models.User
         "USER_RESOLVER": "pyobs_archive.authentication.keycloak.resolve_user",
+        # optional claims-based authorization gate - see pyobs_auth.authorization
+        "REQUIRED_GROUPS": ["/pyobs-archive"],
+        "REQUIRED_ROLES": ["client:archive:archive-admin"],
+        "ENFORCE_LOCAL_ACTIVE": False,
     }
 """
 
@@ -34,6 +38,9 @@ class KeycloakSettings:
     scopes: tuple[str, ...] = field(default_factory=lambda: ("openid", "profile", "email"))
     user_resolver: str | None = None
     idp_hint: str | None = None
+    required_groups: tuple[str, ...] = field(default_factory=tuple)
+    required_roles: tuple[str, ...] = field(default_factory=tuple)
+    enforce_local_active: bool = False
 
     @property
     def issuer(self) -> str:
@@ -64,6 +71,25 @@ class ImproperlyConfiguredError(Exception):
     pass
 
 
+def _as_tuple(value: Any) -> tuple[str, ...]:
+    """A bare string (a common mistake for a "one group" REQUIRED_GROUPS/REQUIRED_ROLES value)
+    would otherwise silently `tuple()`-split into individual characters instead of raising -
+    normalize it to a one-element tuple instead."""
+    if value is None:
+        return ()
+    if isinstance(value, str):
+        return (value,)
+    return tuple(value)
+
+
+def _as_bool(value: Any) -> bool:
+    """`bool("False")` is True - a string value (e.g. from naive env-var parsing) needs an
+    explicit check rather than Python's default truthiness."""
+    if isinstance(value, str):
+        return value.strip().lower() in ("true", "1", "yes")
+    return bool(value)
+
+
 def get_settings() -> KeycloakSettings:
     """Build KeycloakSettings from Django's PYOBS_AUTH setting."""
     from django.conf import settings as django_settings
@@ -87,4 +113,7 @@ def get_settings() -> KeycloakSettings:
         scopes=tuple(raw.get("SCOPES", ("openid", "profile", "email"))),
         user_resolver=raw.get("USER_RESOLVER"),
         idp_hint=raw.get("IDP_HINT"),
+        required_groups=_as_tuple(raw.get("REQUIRED_GROUPS")),
+        required_roles=_as_tuple(raw.get("REQUIRED_ROLES")),
+        enforce_local_active=_as_bool(raw.get("ENFORCE_LOCAL_ACTIVE", False)),
     )

{pyobs_auth-2.0.0.dev10 → pyobs_auth-2.1.0}/pyobs_auth/views.py

@@ -7,22 +7,31 @@ plain Django views instead; wire them in via pyobs_auth.urls.
 
 from __future__ import annotations
 
+import logging
+
 from django.conf import settings as django_settings
 from django.contrib.auth import login, logout
 from django.http import HttpRequest, HttpResponse, HttpResponseRedirect
 from django.shortcuts import render
 from django.views import View
 
+from .authorization import AuthorizationError, authorize
 from .client import KeycloakClient, TokenExchangeError
 from .settings import get_settings
 from .validation import TokenValidationError, TokenValidator
 
+_logger = logging.getLogger(__name__)
+
 SESSION_STATE_KEY = "pyobs_auth_state"
 SESSION_CODE_VERIFIER_KEY = "pyobs_auth_code_verifier"
 SESSION_NEXT_KEY = "pyobs_auth_next"
 # Presence of this key is also how LogoutView tells "this session came from Keycloak" apart from
 # a plain local-password session, so it knows whether to also end the Keycloak SSO session.
 SESSION_ID_TOKEN_KEY = "pyobs_auth_id_token"
+# Both read by KeycloakSessionRefreshMiddleware - absence of either means this session predates
+# the middleware or wasn't established via Keycloak, so it leaves the session alone.
+SESSION_REFRESH_TOKEN_KEY = "pyobs_auth_refresh_token"
+SESSION_ACCESS_EXPIRES_KEY = "pyobs_auth_access_expires"
 
 
 def _error_response(request: HttpRequest, message: str) -> HttpResponse:
@@ -86,11 +95,21 @@ class CallbackView(View):
         except TokenValidationError as exc:
             return _error_response(request, f"Received an invalid token: {exc}")
 
+        # Checked before resolving a local user - an unauthorized caller must not mint a User
+        # row just by presenting a validly-signed-but-ungrouped token.
+        try:
+            authorize(claims, settings)
+        except AuthorizationError:
+            return _error_response(request, "You are not authorized to use this service. Contact an administrator.")
+        except ValueError:
+            _logger.exception("PYOBS_AUTH['REQUIRED_ROLES'] is malformed")
+            raise
+
         user_resolver = settings.resolve_user_callable()
         user = user_resolver(claims)
         if user is None:
             return _error_response(request, "No local user for this token")
-        if not user.is_active:
+        if settings.enforce_local_active and not user.is_active:
             return _error_response(request, "This account is pending activation. Contact an administrator.")
 
         backend = getattr(django_settings, "PYOBS_AUTH_LOGIN_BACKEND", "django.contrib.auth.backends.ModelBackend")
@@ -100,6 +119,28 @@ class CallbackView(View):
         id_token = tokens.get("id_token")
         if id_token:
             request.session[SESSION_ID_TOKEN_KEY] = id_token
+        # Kept so KeycloakSessionRefreshMiddleware can silently refresh and re-authorize once the
+        # access token expires, instead of a browser session outliving revocation until logout -
+        # see pyobs-core's shared-authz-keycloak.md "Revocation model and freshness".
+        refresh_token = tokens.get("refresh_token")
+        if refresh_token:
+            session_engine = getattr(django_settings, "SESSION_ENGINE", "django.contrib.sessions.backends.db")
+            if session_engine.endswith(".signed_cookies"):
+                # A cookie-backed session serializes into the browser - signed, but not
+                # encrypted, so storing a bearer credential that can mint fresh access tokens
+                # indefinitely there would hand it to the client. Skip storing it; the session
+                # simply won't be refreshable (KeycloakSessionRefreshMiddleware is a no-op for
+                # it), same as before this feature existed.
+                _logger.warning(
+                    "SESSION_ENGINE=%s is cookie-backed - not storing the Keycloak refresh token "
+                    "in the session. KeycloakSessionRefreshMiddleware will be a no-op for this "
+                    "session; group/role revocation only takes effect at next login. Switch to a "
+                    "server-side SESSION_ENGINE (db/cached_db) to enable session refresh.",
+                    session_engine,
+                )
+            else:
+                request.session[SESSION_REFRESH_TOKEN_KEY] = refresh_token
+                request.session[SESSION_ACCESS_EXPIRES_KEY] = claims["exp"]
 
         return HttpResponseRedirect(next_url)
 

{pyobs_auth-2.0.0.dev10 → pyobs_auth-2.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pyobs-auth"
-version = "2.0.0.dev10"
+version = "2.1.0"
 description = "Shared Keycloak/OIDC authentication client for pyobs web services"
 authors = [{ name = "Tim-Oliver Husser", email = "thusser@uni-goettingen.de" }]
 requires-python = ">=3.11"