simple-module-keycloak 0.0.24__tar.gz

simple_module_keycloak-0.0.24/.gitignore

@@ -0,0 +1,64 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+*.egg
+
+# UV
+uv.lock
+
+# Node
+node_modules/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Environment
+.env
+
+# Database
+*.db
+*.sqlite3
+
+# Module-managed runtime state (e.g. uploaded dataset files,
+# default storage_dir for SM_DATASETS_STORAGE_DIR).
+var/
+
+# file_storage filesystem backend default root (override via SM_FILE_STORAGE_FS_ROOT_PATH).
+uploads/
+
+# Vite
+host/static/dist/
+
+# VitePress (docs)
+docs/.vitepress/cache/
+docs/.vitepress/dist/
+
+# Auto-generated frontend module manifest (regenerated by the host at boot
+# or via `make gen-pages`).
+host/client_app/modules.manifest.json
+host/client_app/modules.generated.ts
+host/client_app/modules.generated.css
+
+# Worktrees
+.worktrees/
+
+# Performance profiles
+.memray/
+.benchmarks/
+
+# OS
+.DS_Store
+Thumbs.db
+
+.playwright-cli/*
+.playwright-mcp/*
+host/client_app/.playwright-cli/*
+.superpowers/
+.qa/

simple_module_keycloak-0.0.24/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: simple_module_keycloak
+Version: 0.0.24
+Summary: Keycloak OIDC authentication provider for simple_module — swap with simple_module_users
+Project-URL: Homepage, https://github.com/antosubash/simple_module_python
+Project-URL: Repository, https://github.com/antosubash/simple_module_python
+Author-email: Anto Subash <antosubash@live.com>
+License-Expression: MIT
+Keywords: authentication,fastapi,keycloak,oidc,simple-module
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyjwt[crypto]>=2.8
+Requires-Dist: simple-module-auth==0.0.24
+Requires-Dist: simple-module-core==0.0.24
+Requires-Dist: simple-module-db==0.0.24
+Requires-Dist: simple-module-hosting==0.0.24
+Requires-Dist: simple-module-settings==0.0.24
+Description-Content-Type: text/markdown
+
+# simple_module_keycloak
+
+Keycloak OIDC authentication provider for simple_module. Swap with `simple_module_users` for Keycloak-backed identity management — users, roles, and login all handled by Keycloak.
+
+## Install
+
+Add to your app's `pyproject.toml` dependencies instead of `simple_module_users`:
+
+```toml
+dependencies = [
+    "simple_module_keycloak==0.0.17",
+]
+```
+
+Run `uv sync --all-packages` to install.
+
+## Usage
+
+Set the required environment variables (or configure via the settings admin UI after first boot):
+
+```bash
+SM_KEYCLOAK_SERVER_URL=https://keycloak.example.com
+SM_KEYCLOAK_REALM=my-realm
+SM_KEYCLOAK_CLIENT_ID=my-app
+SM_KEYCLOAK_CLIENT_SECRET=my-secret
+```
+
+The module auto-registers as the auth provider. Browser users are redirected to Keycloak's hosted login page. Mobile clients authenticate directly with Keycloak and send bearer tokens to the framework API.
+
+Keycloak realm roles are mapped to framework permissions via the `role_mapping` setting (default: `admin` and `user` map 1:1).

simple_module_keycloak-0.0.24/README.md

@@ -0,0 +1,30 @@
+# simple_module_keycloak
+
+Keycloak OIDC authentication provider for simple_module. Swap with `simple_module_users` for Keycloak-backed identity management — users, roles, and login all handled by Keycloak.
+
+## Install
+
+Add to your app's `pyproject.toml` dependencies instead of `simple_module_users`:
+
+```toml
+dependencies = [
+    "simple_module_keycloak==0.0.17",
+]
+```
+
+Run `uv sync --all-packages` to install.
+
+## Usage
+
+Set the required environment variables (or configure via the settings admin UI after first boot):
+
+```bash
+SM_KEYCLOAK_SERVER_URL=https://keycloak.example.com
+SM_KEYCLOAK_REALM=my-realm
+SM_KEYCLOAK_CLIENT_ID=my-app
+SM_KEYCLOAK_CLIENT_SECRET=my-secret
+```
+
+The module auto-registers as the auth provider. Browser users are redirected to Keycloak's hosted login page. Mobile clients authenticate directly with Keycloak and send bearer tokens to the framework API.
+
+Keycloak realm roles are mapped to framework permissions via the `role_mapping` setting (default: `admin` and `user` map 1:1).

simple_module_keycloak-0.0.24/keycloak/__init__.py

@@ -0,0 +1 @@
+"""Keycloak OIDC authentication provider for simple_module."""

simple_module_keycloak-0.0.24/keycloak/contracts/__init__.py

@@ -0,0 +1 @@
+"""Keycloak module contracts."""

simple_module_keycloak-0.0.24/keycloak/endpoints/__init__.py

@@ -0,0 +1 @@
+"""Keycloak endpoint routers."""

simple_module_keycloak-0.0.24/keycloak/endpoints/api.py

@@ -0,0 +1,92 @@
+"""Keycloak OIDC API endpoints — login redirect, callback."""
+
+from __future__ import annotations
+
+import logging
+import secrets
+from typing import TYPE_CHECKING
+
+from fastapi import APIRouter, HTTPException, Request
+from starlette.responses import RedirectResponse
+
+if TYPE_CHECKING:
+    from keycloak.settings import KeycloakSettings
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/auth", tags=["keycloak-auth"])
+
+_SESSION_OIDC_STATE = "keycloak_oidc_state"
+_SESSION_OIDC_NONCE = "keycloak_oidc_nonce"
+_SESSION_USER_CTX = "user_ctx"
+_SESSION_ID_TOKEN = "keycloak_id_token"
+_SESSION_NEXT = "next"
+
+
+def _get_settings(request: Request) -> KeycloakSettings:
+    return request.app.state.keycloak.settings
+
+
+def _get_oidc_client(request: Request):
+    from keycloak.oidc import OIDCClient
+
+    s = _get_settings(request)
+    return OIDCClient(
+        server_url=s.server_url,
+        realm=s.realm,
+        client_id=s.client_id,
+        client_secret=s.client_secret,
+    )
+
+
+@router.get("/login")
+async def oidc_login(request: Request):
+    client = _get_oidc_client(request)
+    callback_url = str(request.url_for("oidc_callback"))
+    nonce = secrets.token_urlsafe(32)
+    url, state = client.build_authorization_url(
+        redirect_uri=callback_url,
+        nonce=nonce,
+    )
+    request.session[_SESSION_OIDC_STATE] = state
+    request.session[_SESSION_OIDC_NONCE] = nonce
+    return RedirectResponse(url, status_code=302)
+
+
+@router.get("/callback")
+async def oidc_callback(request: Request):
+    code = request.query_params.get("code")
+    state = request.query_params.get("state")
+
+    expected_state = request.session.pop(_SESSION_OIDC_STATE, None)
+    request.session.pop(_SESSION_OIDC_NONCE, None)
+
+    if not code or not state or state != expected_state:
+        raise HTTPException(status_code=400, detail="Invalid OIDC state")
+
+    client = _get_oidc_client(request)
+    callback_url = str(request.url_for("oidc_callback"))
+
+    try:
+        tokens = await client.exchange_code(code=code, redirect_uri=callback_url)
+    except Exception:
+        logger.exception("Token exchange failed")
+        raise HTTPException(status_code=502, detail="Token exchange failed") from None
+
+    id_token = tokens.get("id_token", "")
+    access_token = tokens.get("access_token", "")
+
+    jwks_cache = request.app.state.keycloak.jwks_cache
+    claims = await jwks_cache.validate_jwt(access_token) if jwks_cache else None
+    if claims is None:
+        raise HTTPException(status_code=401, detail="Token validation failed")
+
+    provider = request.app.state.auth.auth_provider
+    cache_id = await provider._upsert_user_cache(request, claims)
+    user_ctx = provider._claims_to_user_context(claims, cache_id=cache_id)
+
+    request.session[_SESSION_USER_CTX] = user_ctx.to_session_dict()
+    request.session[_SESSION_ID_TOKEN] = id_token
+
+    s = _get_settings(request)
+    next_url = request.session.pop(_SESSION_NEXT, None) or s.login_redirect_url
+    return RedirectResponse(next_url, status_code=303)

simple_module_keycloak-0.0.24/keycloak/endpoints/views.py

@@ -0,0 +1,40 @@
+"""Keycloak Inertia view routes — login page, logout."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Request
+from simple_module_hosting.inertia_deps import InertiaDep
+from starlette.responses import RedirectResponse
+
+router = APIRouter(tags=["keycloak-views"])
+
+_SESSION_ID_TOKEN = "keycloak_id_token"
+_PAGE_LOGIN = "Keycloak/Login"
+
+
+@router.get("/login")
+async def login_page(request: Request, inertia: InertiaDep):
+    return await inertia.render(_PAGE_LOGIN)
+
+
+@router.post("/logout")
+async def logout(request: Request):
+    from keycloak.oidc import OIDCClient
+
+    s = request.app.state.keycloak.settings
+    id_token = request.session.get(_SESSION_ID_TOKEN)
+
+    request.session.clear()
+
+    client = OIDCClient(
+        server_url=s.server_url,
+        realm=s.realm,
+        client_id=s.client_id,
+        client_secret=s.client_secret,
+    )
+    base_url = str(request.base_url).rstrip("/")
+    logout_url = client.build_logout_url(
+        post_logout_redirect_uri=f"{base_url}/keycloak/login",
+        id_token_hint=id_token,
+    )
+    return RedirectResponse(logout_url, status_code=303)

simple_module_keycloak-0.0.24/keycloak/jwks.py

@@ -0,0 +1,113 @@
+"""JWKS key cache and JWT validation for Keycloak tokens."""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any
+
+import httpx
+import jwt
+from jwt.algorithms import RSAAlgorithm
+
+logger = logging.getLogger(__name__)
+
+
+class JWKSCache:
+    """Caches Keycloak's public signing keys and validates JWTs.
+
+    On validation failure with cached keys, refetches JWKS once before
+    rejecting -- this handles Keycloak key rotation gracefully.
+    """
+
+    def __init__(
+        self,
+        jwks_url: str,
+        ttl_seconds: int = 3600,
+        *,
+        issuer: str,
+        audience: str,
+    ) -> None:
+        if not issuer:
+            raise ValueError("issuer is required for JWT validation")
+        if not audience:
+            raise ValueError("audience is required for JWT validation")
+        self._jwks_url = jwks_url
+        self._ttl = ttl_seconds
+        self._issuer = issuer
+        self._audience = audience
+        self._keys: dict[str, Any] = {}
+        self._fetched_at: float = 0
+
+    async def validate_jwt(self, token: str) -> dict[str, Any] | None:
+        """Decode and validate a JWT. Returns claims dict or None."""
+        try:
+            unverified = jwt.get_unverified_header(token)
+        except jwt.exceptions.DecodeError:
+            return None
+
+        kid = unverified.get("kid")
+        if kid is None:
+            return None
+
+        key = await self._get_key(kid)
+        if key is None:
+            return None
+
+        return self._decode(token, key)
+
+    def _decode(self, token: str, key: Any) -> dict[str, Any] | None:
+        try:
+            return jwt.decode(
+                token,
+                key,
+                algorithms=["RS256"],
+                issuer=self._issuer,
+                audience=self._audience,
+            )
+        except (
+            jwt.ExpiredSignatureError,
+            jwt.InvalidIssuerError,
+            jwt.InvalidAudienceError,
+        ):
+            return None
+        except jwt.PyJWTError:
+            logger.exception("JWT validation failed")
+            return None
+
+    async def _get_key(self, kid: str) -> Any | None:
+        if self._is_stale() or kid not in self._keys:
+            await self._fetch_keys()
+
+        if kid in self._keys:
+            return self._keys[kid]
+
+        await self._fetch_keys(force=True)
+        return self._keys.get(kid)
+
+    def _is_stale(self) -> bool:
+        return time.monotonic() - self._fetched_at > self._ttl
+
+    async def _fetch_keys(self, *, force: bool = False) -> None:
+        if not force and not self._is_stale():
+            return
+        try:
+            async with httpx.AsyncClient() as client:
+                resp = await client.get(self._jwks_url, timeout=10)
+                resp.raise_for_status()
+                jwks_data = resp.json()
+        except Exception:
+            logger.exception("Failed to fetch JWKS from %s", self._jwks_url)
+            return
+
+        new_keys: dict[str, Any] = {}
+        for key_data in jwks_data.get("keys", []):
+            kid = key_data.get("kid")
+            if kid and key_data.get("alg") == "RS256":
+                try:
+                    public_key = RSAAlgorithm.from_jwk(key_data)
+                    new_keys[kid] = public_key
+                except Exception:
+                    logger.warning("Failed to parse JWK kid=%s", kid)
+        self._keys = new_keys
+        self._fetched_at = time.monotonic()

simple_module_keycloak-0.0.24/keycloak/locales/en.json

@@ -0,0 +1,15 @@
+{
+  "login": {
+    "redirecting": "Redirecting to identity provider…",
+    "title": "Sign In"
+  },
+  "logout": {
+    "title": "Signed Out",
+    "message": "You have been signed out successfully."
+  },
+  "errors": {
+    "callback_failed": "Authentication failed. Please try again.",
+    "invalid_state": "Invalid authentication state. Please try again.",
+    "token_validation_failed": "Token validation failed."
+  }
+}

simple_module_keycloak-0.0.24/keycloak/models.py

@@ -0,0 +1,21 @@
+"""Keycloak user cache -- maps Keycloak sub to a stable framework UUID."""
+
+from __future__ import annotations
+
+import uuid as uuid_mod
+from datetime import datetime
+
+from simple_module_db.base import create_module_base
+from sqlmodel import Field
+
+Base = create_module_base("keycloak")
+
+
+class KeycloakUserCache(Base, table=True):  # ty: ignore[unsupported-base]
+    __tablename__ = "keycloak_user_cache"
+
+    id: uuid_mod.UUID = Field(default_factory=uuid_mod.uuid4, primary_key=True)
+    keycloak_sub: str = Field(unique=True, index=True)
+    email: str = ""
+    full_name: str | None = None
+    last_login_at: datetime | None = None

simple_module_keycloak-0.0.24/keycloak/module.py

@@ -0,0 +1,83 @@
+"""Keycloak OIDC authentication module."""
+
+from __future__ import annotations
+
+import importlib.resources
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from simple_module_core.menu import MenuItem, MenuRegistry, MenuSection
+from simple_module_core.module import ModuleBase, ModuleMeta
+
+if TYPE_CHECKING:
+    from fastapi import APIRouter, FastAPI
+
+_MODULE_DEPENDENCY_AUTH = "Auth"
+_MODULE_DEPENDENCY_SETTINGS = "Settings"
+
+
+class KeycloakModule(ModuleBase):
+    meta = ModuleMeta(
+        name="Keycloak",
+        route_prefix="/api/keycloak",
+        view_prefix="/keycloak",
+        depends_on=[_MODULE_DEPENDENCY_AUTH, _MODULE_DEPENDENCY_SETTINGS],
+    )
+    _is_auth_provider = True
+
+    def register_settings(self, app: FastAPI) -> None:
+        import importlib
+
+        from keycloak.provider import KeycloakAuthProvider
+        from keycloak.settings import KeycloakSettings
+        from keycloak.state import KeycloakState
+
+        register_module_settings = importlib.import_module(
+            "settings.registration"
+        ).register_module_settings
+
+        register_module_settings(
+            app,
+            "keycloak",
+            KeycloakSettings,
+            lambda s: KeycloakState(settings=s),
+        )
+
+        app.state.auth.auth_provider = KeycloakAuthProvider(app.state.keycloak.settings)
+
+    def register_menu_items(self, registry: MenuRegistry) -> None:
+        registry.add(
+            MenuItem(
+                label="Logout",
+                url="/keycloak/logout",
+                icon="log-out",
+                order=999,
+                section=MenuSection.USER_DROPDOWN,
+                method="post",
+            )
+        )
+
+    def register_routes(self, api_router: APIRouter, view_router: APIRouter) -> None:
+        from keycloak.endpoints.api import router as api
+        from keycloak.endpoints.views import router as views
+
+        api_router.include_router(api)
+        view_router.include_router(views)
+
+    async def on_startup(self, app: FastAPI) -> None:
+        from keycloak.jwks import JWKSCache
+
+        state = app.state.keycloak
+        s = state.settings
+        if s.server_url and s.realm:
+            state.jwks_cache = JWKSCache(
+                jwks_url=(f"{s.server_url}/realms/{s.realm}/protocol/openid-connect/certs"),
+                ttl_seconds=s.jwks_cache_ttl_seconds,
+                issuer=f"{s.server_url}/realms/{s.realm}",
+                audience=s.client_id,
+            )
+            provider = app.state.auth.auth_provider
+            provider.jwks_cache = state.jwks_cache
+
+    def locale_dirs(self) -> dict[str, Path]:
+        return {"keycloak": Path(str(importlib.resources.files(__package__) / "locales"))}

simple_module_keycloak-0.0.24/keycloak/oidc.py

@@ -0,0 +1,85 @@
+"""OIDC helpers for Keycloak -- authorization URL, token exchange, logout."""
+
+from __future__ import annotations
+
+import secrets
+from typing import Any
+from urllib.parse import urlencode
+
+import httpx
+
+
+class OIDCClient:
+    """Thin wrapper around Keycloak's OIDC endpoints."""
+
+    def __init__(
+        self,
+        server_url: str,
+        realm: str,
+        client_id: str,
+        client_secret: str,
+    ) -> None:
+        self._base = f"{server_url.rstrip('/')}/realms/{realm}/protocol/openid-connect"
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._server_url = server_url.rstrip("/")
+        self._realm = realm
+
+    @property
+    def issuer(self) -> str:
+        return f"{self._server_url}/realms/{self._realm}"
+
+    @property
+    def token_endpoint(self) -> str:
+        return f"{self._base}/token"
+
+    @property
+    def jwks_url(self) -> str:
+        return f"{self._base}/certs"
+
+    def build_authorization_url(
+        self,
+        redirect_uri: str,
+        nonce: str,
+        scope: str = "openid email profile",
+    ) -> tuple[str, str]:
+        state = secrets.token_urlsafe(32)
+        params = {
+            "client_id": self._client_id,
+            "redirect_uri": redirect_uri,
+            "response_type": "code",
+            "scope": scope,
+            "state": state,
+            "nonce": nonce,
+        }
+        url = f"{self._base}/auth?{urlencode(params)}"
+        return url, state
+
+    async def exchange_code(
+        self,
+        code: str,
+        redirect_uri: str,
+    ) -> dict[str, Any]:
+        data = {
+            "grant_type": "authorization_code",
+            "code": code,
+            "redirect_uri": redirect_uri,
+            "client_id": self._client_id,
+            "client_secret": self._client_secret,
+        }
+        async with httpx.AsyncClient() as client:
+            resp = await client.post(self.token_endpoint, data=data, timeout=10)
+            resp.raise_for_status()
+            return resp.json()
+
+    def build_logout_url(
+        self,
+        post_logout_redirect_uri: str,
+        id_token_hint: str | None = None,
+    ) -> str:
+        params: dict[str, str] = {
+            "post_logout_redirect_uri": post_logout_redirect_uri,
+        }
+        if id_token_hint:
+            params["id_token_hint"] = id_token_hint
+        return f"{self._base}/logout?{urlencode(params)}"

simple_module_keycloak-0.0.24/keycloak/pages/LoggedOut.tsx

@@ -0,0 +1,13 @@
+import { Link } from '@inertiajs/react';
+
+export default function LoggedOut() {
+  return (
+    <div className="flex min-h-screen flex-col items-center justify-center gap-4">
+      <h1 className="text-2xl font-bold">Signed Out</h1>
+      <p className="text-muted-foreground">You have been signed out successfully.</p>
+      <Link href="/keycloak/login" className="text-primary underline">
+        Sign in again
+      </Link>
+    </div>
+  );
+}

simple_module_keycloak-0.0.24/keycloak/pages/Login.tsx

@@ -0,0 +1,14 @@
+import { router } from '@inertiajs/react';
+import { useEffect } from 'react';
+
+export default function Login() {
+  useEffect(() => {
+    router.get('/api/keycloak/auth/login');
+  }, []);
+
+  return (
+    <div className="flex min-h-screen items-center justify-center">
+      <p className="text-muted-foreground">Redirecting to identity provider...</p>
+    </div>
+  );
+}

simple_module_keycloak-0.0.24/keycloak/provider.py

@@ -0,0 +1,138 @@
+"""KeycloakAuthProvider — resolves users from Keycloak JWTs or session."""
+
+from __future__ import annotations
+
+import logging
+from datetime import UTC
+from typing import TYPE_CHECKING, Any
+
+from auth.contracts.schemas import UserContext
+from starlette.requests import Request
+
+if TYPE_CHECKING:
+    from keycloak.jwks import JWKSCache
+    from keycloak.settings import KeycloakSettings
+
+logger = logging.getLogger(__name__)
+
+_SESSION_USER_CTX_KEY = "user_ctx"
+
+
+class KeycloakAuthProvider:
+    """OIDC auth provider backed by Keycloak."""
+
+    name = "keycloak"
+    _is_auth_provider = True
+
+    def __init__(self, settings: KeycloakSettings | None = None) -> None:
+        self._settings = settings
+        self.jwks_cache: JWKSCache | None = None
+
+    async def resolve_user(self, request: Request) -> UserContext | None:
+        auth_header = request.headers.get("authorization", "")
+        if auth_header.startswith("Bearer "):
+            return await self._resolve_bearer(request, auth_header[7:])
+
+        session = request.scope.get("session", {})
+        return UserContext.from_session_dict(session.get(_SESSION_USER_CTX_KEY))
+
+    def get_login_url(self, request: Request | None, next_url: str | None = None) -> str:
+        return "/keycloak/login"
+
+    def get_logout_url(self, request: Request | None) -> str:
+        return "/keycloak/logout"
+
+    def get_public_paths(self) -> tuple[tuple[str, ...], tuple[str, ...]]:
+        return (
+            ("/keycloak/login", "/keycloak/logout", "/api/keycloak/auth/"),
+            (),
+        )
+
+    def is_bearer_request(self, request: Request | None) -> bool:
+        if request is None:
+            return False
+        return request.headers.get("authorization", "").startswith("Bearer ")
+
+    async def _resolve_bearer(self, request: Request, token: str) -> UserContext | None:
+        if self.jwks_cache is None:
+            logger.warning("JWKS cache not initialized; rejecting bearer token")
+            return None
+        claims = await self.jwks_cache.validate_jwt(token)
+        if claims is None:
+            return None
+
+        cache_id = await self._upsert_user_cache(request, claims)
+        return self._claims_to_user_context(claims, cache_id=cache_id)
+
+    def _claims_to_user_context(
+        self,
+        claims: dict[str, Any],
+        *,
+        cache_id: str,
+    ) -> UserContext:
+        roles_raw = (
+            _extract_nested(claims, self._settings.roles_claim_path) if self._settings else None
+        )
+        mapped = [
+            self._settings.role_mapping[r]
+            for r in (roles_raw or [])
+            if self._settings and r in self._settings.role_mapping
+        ]
+        return UserContext(
+            id=cache_id,
+            email=claims.get("email", ""),
+            name=(claims.get("preferred_username") or claims.get("name", "")),
+            roles=mapped,
+            tenant_id=claims.get("tenant_id"),
+        )
+
+    async def _upsert_user_cache(self, request: Request, claims: dict) -> str:
+        try:
+            from sqlalchemy import select
+
+            from keycloak.models import KeycloakUserCache
+
+            session_factory = request.app.state.sm.db.session_factory
+            sub = claims["sub"]
+            async with session_factory() as db:
+                stmt = select(KeycloakUserCache).where(KeycloakUserCache.keycloak_sub == sub)
+                row = (await db.execute(stmt)).scalar_one_or_none()
+                if row is None:
+                    import uuid as uuid_mod
+                    from datetime import datetime
+
+                    row = KeycloakUserCache(
+                        id=uuid_mod.uuid4(),
+                        keycloak_sub=sub,
+                        email=claims.get("email", ""),
+                        full_name=claims.get("preferred_username"),
+                        last_login_at=datetime.now(UTC),
+                    )
+                    db.add(row)
+                    await db.flush()
+                else:
+                    from datetime import datetime
+
+                    row.email = claims.get("email", row.email)
+                    row.full_name = claims.get("preferred_username", row.full_name)
+                    row.last_login_at = datetime.now(UTC)
+                    await db.flush()
+                return str(row.id)
+        except Exception:
+            logger.exception(
+                "Failed to upsert KeycloakUserCache for sub=%s",
+                claims.get("sub"),
+            )
+            return claims.get("sub", "unknown")
+
+
+def _extract_nested(data: dict, path: str) -> list[str] | None:
+    parts = path.split(".")
+    current: Any = data
+    for part in parts:
+        if not isinstance(current, dict):
+            return None
+        current = current.get(part)
+        if current is None:
+            return None
+    return current if isinstance(current, list) else None

simple_module_keycloak-0.0.24/keycloak/settings.py

@@ -0,0 +1,49 @@
+"""Keycloak module settings -- DB-backed via ``register_module_settings``."""
+
+from __future__ import annotations
+
+from pydantic import Field, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from simple_module_core.dotenv import env_str
+from simple_module_core.environments import NON_PROD_ENVIRONMENTS
+
+
+class KeycloakSettings(BaseSettings):
+    """Keycloak OIDC configuration."""
+
+    model_config = SettingsConfigDict(extra="ignore")
+
+    server_url: str = env_str("SM_KEYCLOAK_SERVER_URL", "")
+    realm: str = env_str("SM_KEYCLOAK_REALM", "")
+    client_id: str = env_str("SM_KEYCLOAK_CLIENT_ID", "")
+    client_secret: str = env_str("SM_KEYCLOAK_CLIENT_SECRET", "")
+
+    roles_claim_path: str = "realm_access.roles"
+    admin_role: str = "admin"
+    login_redirect_url: str = "/dashboard/"
+    jwks_cache_ttl_seconds: int = 3600
+
+    role_mapping: dict[str, str] = Field(
+        default_factory=lambda: {"admin": "admin", "user": "user"},
+    )
+
+    @model_validator(mode="after")
+    def _check_required_in_production(self) -> KeycloakSettings:
+        import os
+
+        env = os.environ.get("SM_ENVIRONMENT", "development")
+        if env in NON_PROD_ENVIRONMENTS:
+            return self
+        missing = []
+        if not self.server_url:
+            missing.append("SM_KEYCLOAK_SERVER_URL")
+        if not self.realm:
+            missing.append("SM_KEYCLOAK_REALM")
+        if not self.client_id:
+            missing.append("SM_KEYCLOAK_CLIENT_ID")
+        if not self.client_secret:
+            missing.append("SM_KEYCLOAK_CLIENT_SECRET")
+        if missing:
+            msg = f"Keycloak settings required in production: {', '.join(missing)}"
+            raise ValueError(msg)
+        return self

simple_module_keycloak-0.0.24/keycloak/state.py

@@ -0,0 +1,18 @@
+"""Module-scoped state container for the keycloak module."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from keycloak.jwks import JWKSCache
+    from keycloak.settings import KeycloakSettings
+
+
+@dataclass
+class KeycloakState:
+    """Keycloak-module singletons. Single slot at ``app.state.keycloak``."""
+
+    settings: KeycloakSettings
+    jwks_cache: JWKSCache | None = None

simple_module_keycloak-0.0.24/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "@simple-module/keycloak",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "dependencies": {}
+}

simple_module_keycloak-0.0.24/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "simple_module_keycloak"
+version = "0.0.24"
+description = "Keycloak OIDC authentication provider for simple_module — swap with simple_module_users"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+authors = [{ name = "Anto Subash", email = "antosubash@live.com" }]
+keywords = ["simple-module", "keycloak", "oidc", "authentication", "fastapi"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Typing :: Typed",
+]
+dependencies = [
+    "simple_module_core==0.0.24",
+    "simple_module_db==0.0.24",
+    "simple_module_hosting==0.0.24",
+    "simple_module_settings==0.0.24",
+    "simple_module_auth==0.0.24",
+    "PyJWT[crypto]>=2.8",
+    "httpx>=0.27",
+]
+
+[project.entry-points.simple_module]
+keycloak = "keycloak.module:KeycloakModule"
+
+[project.urls]
+Homepage = "https://github.com/antosubash/simple_module_python"
+Repository = "https://github.com/antosubash/simple_module_python"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["keycloak"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"package.json" = "keycloak/package.json"
+
+[tool.uv.sources]
+simple_module_core = { workspace = true }
+simple_module_db = { workspace = true }
+simple_module_hosting = { workspace = true }
+simple_module_settings = { workspace = true }
+simple_module_auth = { workspace = true }

simple_module_keycloak-0.0.24/tests/conftest.py

@@ -0,0 +1 @@
+"""Keycloak module test fixtures."""

simple_module_keycloak-0.0.24/tests/test_jwks.py

@@ -0,0 +1,157 @@
+"""Tests for JWKS key cache and JWT validation."""
+
+from __future__ import annotations
+
+import json
+import time
+
+import jwt
+import pytest
+from cryptography.hazmat.primitives.asymmetric import rsa
+from keycloak.jwks import JWKSCache
+
+
+def _generate_rsa_keypair():
+    private_key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
+    public_key = private_key.public_key()
+    return private_key, public_key
+
+
+def _make_jwks_response(public_key, kid="test-key-1"):
+    from jwt.algorithms import RSAAlgorithm
+
+    jwk = json.loads(RSAAlgorithm.to_jwk(public_key))
+    jwk["kid"] = kid
+    jwk["use"] = "sig"
+    jwk["alg"] = "RS256"
+    return {"keys": [jwk]}
+
+
+def _sign_token(private_key, payload, kid="test-key-1"):
+    return jwt.encode(payload, private_key, algorithm="RS256", headers={"kid": kid})
+
+
+@pytest.fixture
+def rsa_keys():
+    return _generate_rsa_keypair()
+
+
+@pytest.fixture
+def valid_payload():
+    now = int(time.time())
+    return {
+        "sub": "user-123",
+        "email": "test@example.com",
+        "preferred_username": "testuser",
+        "iss": "https://auth.example.com/realms/test",
+        "aud": "my-client",
+        "exp": now + 3600,
+        "iat": now,
+        "realm_access": {"roles": ["admin", "user"]},
+    }
+
+
+async def test_validate_jwt_valid_token(rsa_keys, valid_payload, httpx_mock):
+    private_key, public_key = rsa_keys
+    jwks_data = _make_jwks_response(public_key)
+    httpx_mock.add_response(url="https://auth.example.com/jwks", json=jwks_data)
+
+    cache = JWKSCache(
+        jwks_url="https://auth.example.com/jwks",
+        ttl_seconds=3600,
+        issuer="https://auth.example.com/realms/test",
+        audience="my-client",
+    )
+
+    token = _sign_token(private_key, valid_payload)
+    claims = await cache.validate_jwt(token)
+    assert claims is not None
+    assert claims["sub"] == "user-123"
+    assert claims["email"] == "test@example.com"
+
+
+async def test_validate_jwt_expired_token(rsa_keys, valid_payload, httpx_mock):
+    private_key, public_key = rsa_keys
+    valid_payload["exp"] = int(time.time()) - 100
+    jwks_data = _make_jwks_response(public_key)
+    httpx_mock.add_response(url="https://auth.example.com/jwks", json=jwks_data)
+
+    cache = JWKSCache(
+        jwks_url="https://auth.example.com/jwks",
+        ttl_seconds=3600,
+        issuer="https://auth.example.com/realms/test",
+        audience="my-client",
+    )
+
+    token = _sign_token(private_key, valid_payload)
+    claims = await cache.validate_jwt(token)
+    assert claims is None
+
+
+async def test_validate_jwt_wrong_issuer(rsa_keys, valid_payload, httpx_mock):
+    private_key, public_key = rsa_keys
+    jwks_data = _make_jwks_response(public_key)
+    httpx_mock.add_response(url="https://auth.example.com/jwks", json=jwks_data)
+
+    cache = JWKSCache(
+        jwks_url="https://auth.example.com/jwks",
+        ttl_seconds=3600,
+        issuer="https://wrong-issuer.com/realms/test",
+        audience="my-client",
+    )
+
+    token = _sign_token(private_key, valid_payload)
+    claims = await cache.validate_jwt(token)
+    assert claims is None
+
+
+async def test_validate_jwt_wrong_audience(rsa_keys, valid_payload, httpx_mock):
+    private_key, public_key = rsa_keys
+    jwks_data = _make_jwks_response(public_key)
+    httpx_mock.add_response(url="https://auth.example.com/jwks", json=jwks_data)
+
+    cache = JWKSCache(
+        jwks_url="https://auth.example.com/jwks",
+        ttl_seconds=3600,
+        issuer="https://auth.example.com/realms/test",
+        audience="wrong-client",
+    )
+
+    token = _sign_token(private_key, valid_payload)
+    claims = await cache.validate_jwt(token)
+    assert claims is None
+
+
+async def test_jwks_cache_refetches_on_unknown_kid(rsa_keys, valid_payload):
+    """When a token has a kid not in cache, refetch JWKS once before rejecting."""
+    private_key, public_key = rsa_keys
+    jwks_data = _make_jwks_response(public_key, kid="rotated-key")
+
+    call_count = 0
+
+    async def counting_fetch(self, *, force=False):
+        nonlocal call_count
+        call_count += 1
+        if call_count == 1:
+            self._keys = {}
+            self._fetched_at = __import__("time").monotonic()
+        else:
+            from jwt.algorithms import RSAAlgorithm
+
+            for kd in jwks_data["keys"]:
+                self._keys[kd["kid"]] = RSAAlgorithm.from_jwk(kd)
+            self._fetched_at = __import__("time").monotonic()
+
+    cache = JWKSCache(
+        jwks_url="https://auth.example.com/jwks",
+        ttl_seconds=3600,
+        issuer="https://auth.example.com/realms/test",
+        audience="my-client",
+    )
+    cache._fetch_keys = counting_fetch.__get__(cache, JWKSCache)
+
+    token = _sign_token(private_key, valid_payload, kid="rotated-key")
+    claims = await cache.validate_jwt(token)
+    assert claims is not None
+    assert claims["sub"] == "user-123"
+    assert call_count == 2

simple_module_keycloak-0.0.24/tests/test_keycloak_module.py

@@ -0,0 +1,22 @@
+"""Tests for KeycloakModule lifecycle."""
+
+from __future__ import annotations
+
+from auth.contracts.provider import AuthProvider
+
+
+def test_keycloak_module_meta():
+    from keycloak.module import KeycloakModule
+
+    mod = KeycloakModule()
+    assert mod.meta.name == "Keycloak"
+    assert mod.meta.depends_on == ["Auth", "Settings"]
+    assert mod._is_auth_provider is True
+
+
+def test_keycloak_provider_satisfies_protocol():
+    from keycloak.provider import KeycloakAuthProvider
+
+    provider = KeycloakAuthProvider()
+    assert isinstance(provider, AuthProvider)
+    assert provider.name == "keycloak"

simple_module_keycloak-0.0.24/tests/test_keycloak_provider.py

@@ -0,0 +1,94 @@
+"""Tests for KeycloakAuthProvider."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock
+
+import pytest
+from auth.contracts.provider import AuthProvider
+from auth.contracts.schemas import UserContext
+from keycloak.provider import KeycloakAuthProvider
+from keycloak.settings import KeycloakSettings
+
+
+@pytest.fixture
+def settings():
+    return KeycloakSettings(
+        server_url="https://auth.example.com",
+        realm="test",
+        client_id="my-app",
+        client_secret="secret",
+        role_mapping={
+            "admin": "admin",
+            "user": "user",
+            "editor": "editor",
+        },
+    )
+
+
+@pytest.fixture
+def provider(settings):
+    return KeycloakAuthProvider(settings)
+
+
+def test_satisfies_protocol(provider):
+    assert isinstance(provider, AuthProvider)
+
+
+def test_name(provider):
+    assert provider.name == "keycloak"
+
+
+def test_login_url(provider):
+    assert provider.get_login_url(None) == "/keycloak/login"
+
+
+def test_logout_url(provider):
+    assert provider.get_logout_url(None) == "/keycloak/logout"
+
+
+def test_public_paths(provider):
+    prefixes, _exact = provider.get_public_paths()
+    assert "/keycloak/login" in prefixes
+    assert "/api/keycloak/auth/" in prefixes
+
+
+def test_is_bearer_request(provider):
+    req = MagicMock()
+    req.headers = {"authorization": "Bearer abc"}
+    assert provider.is_bearer_request(req) is True
+
+    req.headers = {}
+    assert provider.is_bearer_request(req) is False
+
+
+def test_claims_to_user_context(provider):
+    claims = {
+        "sub": "kc-user-123",
+        "email": "test@example.com",
+        "preferred_username": "testuser",
+        "realm_access": {"roles": ["admin", "unknown_role", "user"]},
+    }
+    ctx = provider._claims_to_user_context(claims, cache_id="aaaaaaaa-0000-0000-0000-000000000001")
+    assert isinstance(ctx, UserContext)
+    assert ctx.id == "aaaaaaaa-0000-0000-0000-000000000001"
+    assert ctx.email == "test@example.com"
+    assert ctx.name == "testuser"
+    assert sorted(ctx.roles) == ["admin", "user"]
+
+
+def test_claims_to_user_context_no_roles(provider):
+    claims = {"sub": "kc-user-456", "email": "noroles@example.com"}
+    ctx = provider._claims_to_user_context(claims, cache_id="bbbb")
+    assert ctx.roles == []
+
+
+def test_extract_roles_custom_claim_path(settings):
+    settings.roles_claim_path = "resource_access.my-app.roles"
+    provider = KeycloakAuthProvider(settings)
+    claims = {
+        "sub": "x",
+        "resource_access": {"my-app": {"roles": ["admin"]}},
+    }
+    ctx = provider._claims_to_user_context(claims, cache_id="cccc")
+    assert ctx.roles == ["admin"]

simple_module_keycloak-0.0.24/tests/test_oidc.py

@@ -0,0 +1,70 @@
+"""Tests for OIDC discovery and token exchange helpers."""
+
+from __future__ import annotations
+
+import pytest
+from keycloak.oidc import OIDCClient
+
+
+@pytest.fixture
+def oidc_client():
+    return OIDCClient(
+        server_url="https://auth.example.com",
+        realm="test",
+        client_id="my-app",
+        client_secret="secret123",
+    )
+
+
+def test_authorization_url(oidc_client):
+    url, state = oidc_client.build_authorization_url(
+        redirect_uri="https://app.example.com/callback",
+        nonce="test-nonce",
+    )
+    assert "auth.example.com/realms/test/protocol/openid-connect/auth" in url
+    assert "client_id=my-app" in url
+    assert "redirect_uri=" in url
+    assert "response_type=code" in url
+    assert "scope=openid" in url
+    assert "nonce=test-nonce" in url
+    assert state is not None
+    assert len(state) > 0
+
+
+def test_token_endpoint_url(oidc_client):
+    assert oidc_client.token_endpoint == (
+        "https://auth.example.com/realms/test/protocol/openid-connect/token"
+    )
+
+
+def test_logout_url(oidc_client):
+    url = oidc_client.build_logout_url(
+        post_logout_redirect_uri="https://app.example.com/login",
+        id_token_hint="token123",
+    )
+    assert "auth.example.com/realms/test/protocol/openid-connect/logout" in url
+    assert "post_logout_redirect_uri=" in url
+    assert "id_token_hint=token123" in url
+
+
+def test_issuer(oidc_client):
+    assert oidc_client.issuer == "https://auth.example.com/realms/test"
+
+
+async def test_exchange_code(oidc_client, httpx_mock):
+    httpx_mock.add_response(
+        url=oidc_client.token_endpoint,
+        json={
+            "access_token": "at-123",
+            "id_token": "id-123",
+            "refresh_token": "rt-123",
+            "token_type": "Bearer",
+            "expires_in": 300,
+        },
+    )
+    tokens = await oidc_client.exchange_code(
+        code="auth-code-xyz",
+        redirect_uri="https://app.example.com/callback",
+    )
+    assert tokens["access_token"] == "at-123"
+    assert tokens["id_token"] == "id-123"

simple_module_keycloak-0.0.24/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../host/client_app/tsconfig.json",
+  "include": ["keycloak/**/*.ts", "keycloak/**/*.tsx"]
+}