pyobs-auth 2.0.0.dev0__py3-none-any.whl

pyobs_auth/__init__.py

@@ -0,0 +1,11 @@
+from .client import KeycloakClient
+from .settings import KeycloakSettings, get_settings
+from .validation import TokenValidationError, TokenValidator
+
+__all__ = [
+    "KeycloakSettings",
+    "get_settings",
+    "TokenValidator",
+    "TokenValidationError",
+    "KeycloakClient",
+]

pyobs_auth/apps.py

@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class PyobsAuthConfig(AppConfig):
+    name = "pyobs_auth"
+    default_auto_field = "django.db.models.BigAutoField"

pyobs_auth/authentication.py

@@ -0,0 +1,45 @@
+"""DRF authentication backed by pyobs-auth's JWKS token validation.
+
+Single issuer only (the one Keycloak realm in PYOBS_AUTH) - there is deliberately no multi-issuer
+support here. See pyobs-core's shared-auth design doc for why: any upstream identity provider
+(including a self-hosted observation-portal) is meant to be brokered *behind* Keycloak, not
+validated directly by this class, so archive/robotic-backend/etc. only ever need to trust one
+issuer.
+"""
+
+from __future__ import annotations
+
+from rest_framework import authentication, exceptions
+
+from .settings import get_settings
+from .validation import TokenValidationError, TokenValidator
+
+
+class KeycloakAuthentication(authentication.BaseAuthentication):
+    www_authenticate_realm = "api"
+
+    def authenticate(self, request):
+        auth_header = authentication.get_authorization_header(request).split()
+        if not auth_header or auth_header[0].lower() != b"bearer":
+            return None
+        if len(auth_header) != 2:
+            raise exceptions.AuthenticationFailed("Invalid Authorization header")
+
+        token = auth_header[1].decode()
+        settings = get_settings()
+        validator = TokenValidator(settings)
+
+        try:
+            claims = validator.validate(token)
+        except TokenValidationError as exc:
+            raise exceptions.AuthenticationFailed(str(exc)) from exc
+
+        user_resolver = settings.resolve_user_callable()
+        user = user_resolver(claims)
+        if user is None:
+            raise exceptions.AuthenticationFailed("No local user for this token")
+
+        return (user, claims)
+
+    def authenticate_header(self, request):
+        return f'Bearer realm="{self.www_authenticate_realm}"'

pyobs_auth/client.py

@@ -0,0 +1,119 @@
+"""OIDC client: authorization-code + PKCE for user login, client-credentials for
+service-to-service - both against a single Keycloak realm (see settings.py)."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import secrets
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import urlencode
+
+import requests
+
+from .discovery import fetch_discovery_document
+from .settings import KeycloakSettings
+
+
+class TokenExchangeError(Exception):
+    pass
+
+
+def _b64url(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii")
+
+
+@dataclass(frozen=True)
+class AuthorizationRequest:
+    """Result of starting a login: send the user to `url`, keep `code_verifier` server-side
+    (e.g. in the session) until the callback arrives."""
+
+    url: str
+    state: str
+    code_verifier: str
+
+
+class KeycloakClient:
+    def __init__(self, settings: KeycloakSettings, *, session: requests.Session | None = None) -> None:
+        self._settings = settings
+        self._session = session or requests.Session()
+
+    def _discovery(self):
+        return fetch_discovery_document(self._settings.discovery_url)
+
+    def start_authorization(self, *, redirect_uri: str | None = None) -> AuthorizationRequest:
+        """Build the redirect URL for the authorization-code + PKCE login flow."""
+        document = self._discovery()
+        state = _b64url(secrets.token_bytes(24))
+        code_verifier = _b64url(secrets.token_bytes(48))
+        code_challenge = _b64url(hashlib.sha256(code_verifier.encode("ascii")).digest())
+
+        effective_redirect_uri = redirect_uri or self._settings.redirect_uri
+        if not effective_redirect_uri:
+            raise ValueError("redirect_uri must be set (either PYOBS_AUTH['REDIRECT_URI'] or the redirect_uri arg)")
+
+        params = {
+            "response_type": "code",
+            "client_id": self._settings.client_id,
+            "redirect_uri": effective_redirect_uri,
+            "scope": " ".join(self._settings.scopes),
+            "state": state,
+            "code_challenge": code_challenge,
+            "code_challenge_method": "S256",
+        }
+        url = f"{document.authorization_endpoint}?{urlencode(params)}"
+        return AuthorizationRequest(url=url, state=state, code_verifier=code_verifier)
+
+    def exchange_code(self, *, code: str, code_verifier: str, redirect_uri: str | None = None) -> dict[str, Any]:
+        """Swap an authorization code for tokens (access_token, refresh_token, id_token, ...)."""
+        document = self._discovery()
+        effective_redirect_uri = redirect_uri or self._settings.redirect_uri
+        if not effective_redirect_uri:
+            raise ValueError("redirect_uri must be set (either PYOBS_AUTH['REDIRECT_URI'] or the redirect_uri arg)")
+
+        data = {
+            "grant_type": "authorization_code",
+            "code": code,
+            "redirect_uri": effective_redirect_uri,
+            "client_id": self._settings.client_id,
+            "code_verifier": code_verifier,
+        }
+        if self._settings.client_secret:
+            data["client_secret"] = self._settings.client_secret
+
+        return self._post_token(document.token_endpoint, data)
+
+    def client_credentials_token(self, *, scope: str | None = None) -> dict[str, Any]:
+        """Service-to-service token, e.g. for one pyobs web service to call another's API."""
+        if not self._settings.client_secret:
+            raise ValueError("client_credentials grant requires PYOBS_AUTH['CLIENT_SECRET']")
+
+        document = self._discovery()
+        data = {
+            "grant_type": "client_credentials",
+            "client_id": self._settings.client_id,
+            "client_secret": self._settings.client_secret,
+        }
+        if scope:
+            data["scope"] = scope
+
+        return self._post_token(document.token_endpoint, data)
+
+    def refresh(self, *, refresh_token: str) -> dict[str, Any]:
+        document = self._discovery()
+        data = {
+            "grant_type": "refresh_token",
+            "refresh_token": refresh_token,
+            "client_id": self._settings.client_id,
+        }
+        if self._settings.client_secret:
+            data["client_secret"] = self._settings.client_secret
+
+        return self._post_token(document.token_endpoint, data)
+
+    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)
+        if response.status_code != 200:
+            raise TokenExchangeError(f"token endpoint returned {response.status_code}: {response.text}")
+        return response.json()

pyobs_auth/discovery.py

@@ -0,0 +1,51 @@
+"""OIDC discovery document fetch, cached per issuer for the life of the process."""
+
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass
+
+import requests
+
+
+@dataclass(frozen=True)
+class DiscoveryDocument:
+    issuer: str
+    authorization_endpoint: str
+    token_endpoint: str
+    userinfo_endpoint: str
+    jwks_uri: str
+    end_session_endpoint: str | None = None
+
+
+_cache: dict[str, DiscoveryDocument] = {}
+_lock = threading.Lock()
+
+
+def fetch_discovery_document(discovery_url: str, *, timeout: float = 10.0) -> DiscoveryDocument:
+    with _lock:
+        cached = _cache.get(discovery_url)
+    if cached is not None:
+        return cached
+
+    response = requests.get(discovery_url, timeout=timeout)
+    response.raise_for_status()
+    data = response.json()
+
+    document = DiscoveryDocument(
+        issuer=data["issuer"],
+        authorization_endpoint=data["authorization_endpoint"],
+        token_endpoint=data["token_endpoint"],
+        userinfo_endpoint=data["userinfo_endpoint"],
+        jwks_uri=data["jwks_uri"],
+        end_session_endpoint=data.get("end_session_endpoint"),
+    )
+    with _lock:
+        _cache[discovery_url] = document
+    return document
+
+
+def clear_discovery_cache() -> None:
+    """Only needed for tests - the cache is otherwise process-lifetime."""
+    with _lock:
+        _cache.clear()

pyobs_auth/settings.py

@@ -0,0 +1,85 @@
+"""Config surface for pyobs-auth: one shared Keycloak realm, one client per service.
+
+Read from the Django ``PYOBS_AUTH`` setting, e.g.::
+
+    PYOBS_AUTH = {
+        "SERVER_URL": "https://keycloak.example.org",
+        "REALM": "pyobs",
+        "CLIENT_ID": "archive",
+        "CLIENT_SECRET": os.getenv("KEYCLOAK_CLIENT_SECRET"),
+        "REDIRECT_URI": "https://archive.example.org/accounts/keycloak/callback/",
+        # dotted path to a callable(claims: dict) -> django.contrib.auth.models.User
+        "USER_RESOLVER": "pyobs_archive.authentication.keycloak.resolve_user",
+    }
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from importlib import import_module
+from typing import Any
+
+
+@dataclass(frozen=True)
+class KeycloakSettings:
+    server_url: str
+    realm: str
+    client_id: str
+    client_secret: str | None = None
+    audience: str | None = None
+    redirect_uri: str | None = None
+    scopes: tuple[str, ...] = field(default_factory=lambda: ("openid", "profile", "email"))
+    user_resolver: str | None = None
+
+    @property
+    def issuer(self) -> str:
+        return f"{self.server_url.rstrip('/')}/realms/{self.realm}"
+
+    @property
+    def discovery_url(self) -> str:
+        return f"{self.issuer}/.well-known/openid-configuration"
+
+    @property
+    def expected_audience(self) -> str:
+        return self.audience or self.client_id
+
+    def resolve_user_callable(self) -> Callable[[dict[str, Any]], Any]:
+        if not self.user_resolver:
+            raise ImproperlyConfiguredError(
+                "PYOBS_AUTH['USER_RESOLVER'] is not set - pyobs-auth needs a"
+                " callable(claims: dict) -> User to map a validated token to a local user"
+            )
+        module_path, _, attr = self.user_resolver.rpartition(".")
+        if not module_path:
+            raise ImproperlyConfiguredError(f"PYOBS_AUTH['USER_RESOLVER'] is not a dotted path: {self.user_resolver!r}")
+        module = import_module(module_path)
+        return getattr(module, attr)
+
+
+class ImproperlyConfiguredError(Exception):
+    pass
+
+
+def get_settings() -> KeycloakSettings:
+    """Build KeycloakSettings from Django's PYOBS_AUTH setting."""
+    from django.conf import settings as django_settings
+
+    raw: dict[str, Any] | None = getattr(django_settings, "PYOBS_AUTH", None)
+    if not raw:
+        raise ImproperlyConfiguredError("PYOBS_AUTH setting is missing")
+
+    missing = [key for key in ("SERVER_URL", "REALM", "CLIENT_ID") if not raw.get(key)]
+    if missing:
+        raise ImproperlyConfiguredError(f"PYOBS_AUTH is missing required key(s): {', '.join(missing)}")
+
+    return KeycloakSettings(
+        server_url=raw["SERVER_URL"],
+        realm=raw["REALM"],
+        client_id=raw["CLIENT_ID"],
+        client_secret=raw.get("CLIENT_SECRET"),
+        audience=raw.get("AUDIENCE"),
+        redirect_uri=raw.get("REDIRECT_URI"),
+        scopes=tuple(raw.get("SCOPES", ("openid", "profile", "email"))),
+        user_resolver=raw.get("USER_RESOLVER"),
+    )

pyobs_auth/urls.py

@@ -0,0 +1,10 @@
+from django.urls import path
+
+from .views import CallbackView, LoginView
+
+app_name = "pyobs_auth"
+
+urlpatterns = [
+    path("login/", LoginView.as_view(), name="login"),
+    path("callback/", CallbackView.as_view(), name="callback"),
+]

pyobs_auth/validation.py

@@ -0,0 +1,78 @@
+"""Local, stateless bearer-token validation against a Keycloak realm's JWKS.
+
+No per-request network round-trip to Keycloak (unlike introspection-style validation) - the
+realm's signing keys are fetched once and cached (PyJWKClient does its own key-id-keyed caching,
+refetching only on a cache miss, e.g. after key rotation).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import jwt
+from jwt import PyJWKClient
+
+from .discovery import fetch_discovery_document
+from .settings import KeycloakSettings
+
+_jwk_clients: dict[str, PyJWKClient] = {}
+
+
+class TokenValidationError(Exception):
+    pass
+
+
+def clear_jwk_client_cache() -> None:
+    """Only needed for tests - the cache is otherwise process-lifetime."""
+    _jwk_clients.clear()
+
+
+def _jwk_client_for(jwks_uri: str) -> PyJWKClient:
+    client = _jwk_clients.get(jwks_uri)
+    if client is None:
+        client = PyJWKClient(jwks_uri)
+        _jwk_clients[jwks_uri] = client
+    return client
+
+
+class TokenValidator:
+    """Validates bearer tokens issued by one Keycloak realm (see KeycloakSettings)."""
+
+    def __init__(self, settings: KeycloakSettings) -> None:
+        self._settings = settings
+
+    def unverified_issuer(self, token: str) -> str | None:
+        """Peek at the (unverified) `iss` claim without validating the token.
+
+        Lets a caller cheaply tell "not mine" from "mine but invalid" before deciding whether to
+        raise - relevant if multiple authenticators are ever stacked against the same Bearer
+        header (see pyobs-core's shared-auth design doc for why that matters).
+        """
+        try:
+            claims = jwt.decode(token, options={"verify_signature": False, "verify_aud": False, "verify_exp": False})
+        except jwt.InvalidTokenError:
+            return None
+        return claims.get("iss")
+
+    def validate(self, token: str) -> dict[str, Any]:
+        document = fetch_discovery_document(self._settings.discovery_url)
+        jwk_client = _jwk_client_for(document.jwks_uri)
+
+        try:
+            signing_key = jwk_client.get_signing_key_from_jwt(token)
+        except jwt.PyJWKClientError as exc:
+            raise TokenValidationError(f"could not resolve signing key: {exc}") from exc
+
+        try:
+            claims: dict[str, Any] = jwt.decode(
+                token,
+                signing_key.key,
+                algorithms=["RS256"],
+                issuer=document.issuer,
+                audience=self._settings.expected_audience,
+                options={"require": ["exp", "iat", "sub"]},
+            )
+        except jwt.InvalidTokenError as exc:
+            raise TokenValidationError(str(exc)) from exc
+
+        return claims

pyobs_auth/views.py

@@ -0,0 +1,78 @@
+"""Browser-facing login flow: authorization-code + PKCE redirect to Keycloak and back.
+
+Not a django.contrib.auth AUTHENTICATION_BACKENDS class - that shape fits a synchronous
+credential check (username+password in, User out), not a redirect-based OIDC flow. These are
+plain Django views instead; wire them in via pyobs_auth.urls.
+"""
+
+from __future__ import annotations
+
+from django.conf import settings as django_settings
+from django.contrib.auth import login
+from django.http import HttpRequest, HttpResponse, HttpResponseBadRequest, HttpResponseRedirect
+from django.views import View
+
+from .client import KeycloakClient, TokenExchangeError
+from .settings import get_settings
+from .validation import TokenValidationError, TokenValidator
+
+SESSION_STATE_KEY = "pyobs_auth_state"
+SESSION_CODE_VERIFIER_KEY = "pyobs_auth_code_verifier"
+SESSION_NEXT_KEY = "pyobs_auth_next"
+
+
+class LoginView(View):
+    def get(self, request: HttpRequest) -> HttpResponse:
+        settings = get_settings()
+        client = KeycloakClient(settings)
+        authorization = client.start_authorization()
+
+        request.session[SESSION_STATE_KEY] = authorization.state
+        request.session[SESSION_CODE_VERIFIER_KEY] = authorization.code_verifier
+        request.session[SESSION_NEXT_KEY] = request.GET.get("next", "/")
+
+        return HttpResponseRedirect(authorization.url)
+
+
+class CallbackView(View):
+    def get(self, request: HttpRequest) -> HttpResponse:
+        error = request.GET.get("error")
+        if error:
+            return HttpResponseBadRequest(f"Keycloak login failed: {error}")
+
+        code = request.GET.get("code")
+        state = request.GET.get("state")
+        expected_state = request.session.pop(SESSION_STATE_KEY, None)
+        code_verifier = request.session.pop(SESSION_CODE_VERIFIER_KEY, None)
+        next_url = request.session.pop(SESSION_NEXT_KEY, "/")
+
+        if not code or not state or not code_verifier or state != expected_state:
+            return HttpResponseBadRequest("Invalid or expired login state")
+
+        settings = get_settings()
+        client = KeycloakClient(settings)
+
+        try:
+            tokens = client.exchange_code(code=code, code_verifier=code_verifier)
+        except TokenExchangeError as exc:
+            return HttpResponseBadRequest(f"Token exchange failed: {exc}")
+
+        access_token = tokens.get("access_token")
+        if not access_token:
+            return HttpResponseBadRequest("No access_token in Keycloak's response")
+
+        validator = TokenValidator(settings)
+        try:
+            claims = validator.validate(access_token)
+        except TokenValidationError as exc:
+            return HttpResponseBadRequest(f"Received an invalid token: {exc}")
+
+        user_resolver = settings.resolve_user_callable()
+        user = user_resolver(claims)
+        if user is None:
+            return HttpResponseBadRequest("No local user for this token")
+
+        backend = getattr(django_settings, "PYOBS_AUTH_LOGIN_BACKEND", "django.contrib.auth.backends.ModelBackend")
+        login(request, user, backend=backend)
+
+        return HttpResponseRedirect(next_url)

pyobs_auth-2.0.0.dev0.dist-info/METADATA

@@ -0,0 +1,12 @@
+Metadata-Version: 2.5
+Name: pyobs-auth
+Version: 2.0.0.dev0
+Summary: Shared Keycloak/OIDC authentication client for pyobs web services
+Author-email: Tim-Oliver Husser <thusser@uni-goettingen.de>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: django<6,>=5.2
+Requires-Dist: djangorestframework>=3.15
+Requires-Dist: pyjwt[crypto]<3,>=2.10.1
+Requires-Dist: requests<3,>=2.32.3

pyobs_auth-2.0.0.dev0.dist-info/RECORD

@@ -0,0 +1,14 @@
+pyobs_auth/__init__.py,sha256=vCI7zULdAAll7fiHPhxlra7xfwbPvPAZwtITHExPYn8,280
+pyobs_auth/apps.py,sha256=gWeEqL9TK3x6owVKHbnUujttu3Nt-qGcquQC7wLb4nY,151
+pyobs_auth/authentication.py,sha256=ejjWWvg39COSUVRxyTX0pOpOYjZSyNNzJ3_0Npk03nY,1708
+pyobs_auth/client.py,sha256=6WltZrcnJNahwpProomt-q4cDeaq5VRhnerEiTGg61Q,4648
+pyobs_auth/discovery.py,sha256=a7d6uqA8ebMHrRrfy-pHNvyP_RRAO87UOuAryiKiico,1360
+pyobs_auth/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyobs_auth/settings.py,sha256=MhHnhsdrlhpLzC7GhVjQEaMhxKz6aDeUFju1J5ieJjM,3051
+pyobs_auth/urls.py,sha256=6fMyNdX7jDyl-wVUXAyUG4HjJngrfR_rk9i2PKt0lGA,236
+pyobs_auth/validation.py,sha256=cOuG6kl4_O03BWACJZfhsPLuEYQvj36FxBYk-adneyI,2673
+pyobs_auth/views.py,sha256=euZ433EcO0mrBoTCmCbRHCrKmbyR0bV1HvIVa6V8lxA,3123
+pyobs_auth-2.0.0.dev0.dist-info/METADATA,sha256=a13okJuEHBtqPzenRZz7ZPFDDAvEP2FNjgN7r0D7xAg,410
+pyobs_auth-2.0.0.dev0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+pyobs_auth-2.0.0.dev0.dist-info/licenses/LICENSE,sha256=Gi2yBbEZraESTIWbTnc4elzshQaXpW4QBs9FBotLG7A,1099
+pyobs_auth-2.0.0.dev0.dist-info/RECORD,,

pyobs_auth-2.0.0.dev0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pyobs_auth-2.0.0.dev0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Tim-Oliver Husser
+thusser@uni-goettingen.de
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.