simple-module-oidc 0.0.43__py3-none-any.whl

oidc/persistence.py

@@ -0,0 +1,28 @@
+"""Issuer-scoped adapter for shared cache persistence."""
+
+from auth.oidc_common.persistence import upsert_user_cache
+from simple_module_db import independent_session
+from starlette.requests import Request
+
+from oidc.models import OidcUserCache
+
+
+class CachePersistence:
+    async def _upsert_user_cache(
+        self, request: Request, claims: dict, *, throttle_login: bool = False
+    ) -> str | None:
+        try:
+            issuer, subject = self._identity(claims)
+        except ValueError:
+            return None
+        name = self._display_name(claims)
+        return await upsert_user_cache(
+            request,
+            model=OidcUserCache,
+            identity={"issuer": issuer, "subject": subject},
+            email=self._email(claims),
+            name=name,
+            update_name=bool(name),
+            throttle_login=throttle_login,
+            session_factory=independent_session,
+        )

oidc/presets.py

@@ -0,0 +1,59 @@
+"""Provider presets — per-IdP defaults layered onto OidcSettings.
+
+A preset fills in claim names and (optionally) derives the discovery URL so a
+well-known provider needs only a handful of env vars. ``generic`` is the
+fallback for any OIDC-compliant IdP given an explicit discovery URL.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Preset:
+    """Defaults applied to unset OidcSettings fields for a named provider."""
+
+    name: str
+    # Template filled with ``tenant_id`` to derive the discovery URL when one is
+    # not supplied explicitly. Empty ⇒ discovery URL must be configured directly.
+    discovery_url_template: str = ""
+    uid_claim: str = "sub"
+    username_claim: str = "preferred_username"
+    email_claim: str = "email"
+    name_claim: str = "name"
+    roles_claim_path: str = ""
+    scope: str = "openid email profile"
+
+    def discovery_url(self, tenant_id: str) -> str:
+        """Render the discovery URL from ``tenant_id`` (empty if not templated)."""
+        if not self.discovery_url_template:
+            return ""
+        return self.discovery_url_template.format(tenant_id=tenant_id)
+
+
+PRESETS: dict[str, Preset] = {
+    # Microsoft Entra ID (Azure AD), v2.0 endpoints. Single-tenant: the tenant
+    # GUID goes in ``tenant_id`` (a domain name would not match the GUID issuer
+    # the discovery document reports). App roles arrive in the
+    # ``roles`` claim; ``oid`` is the stable per-tenant user object id.
+    "entra": Preset(
+        name="entra",
+        discovery_url_template=(
+            "https://login.microsoftonline.com/{tenant_id}/v2.0/.well-known/openid-configuration"
+        ),
+        uid_claim="oid",
+        scope="openid email profile offline_access",
+        roles_claim_path="roles",
+    ),
+    # Any OIDC-compliant provider (Auth0, Okta, Zitadel, Authentik, Keycloak, ...)
+    # configured with an explicit ``discovery_url``.
+    "generic": Preset(name="generic"),
+}
+
+
+def get_preset(name: str) -> Preset:
+    """Return a supported preset; typos must not silently change security policy."""
+    if name not in PRESETS:
+        raise ValueError(f"Unknown OIDC preset: {name}")
+    return PRESETS[name]

oidc/provider.py

@@ -0,0 +1,172 @@
+"""OidcAuthProvider — resolves users from Oidc JWTs or session."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from auth.contracts.schemas import UserContext
+from auth.contracts.tokens import AUTH_KIND_BEARER, is_api_token, parse_bearer
+from auth.oidc_common.claims import extract_nested as _extract_nested
+from auth.oidc_common.tenant import trusted_tenant, without_tenant_roles
+from simple_module_hosting.session import SESSION_EXPIRES_AT_KEY, session_has_expired
+from starlette.requests import Request
+
+from oidc.constants import LOGIN_PATH, LOGOUT_PATH, SESSION_USER_KEY
+from oidc.persistence import CachePersistence
+from oidc.renewal import SessionRenewal
+
+if TYPE_CHECKING:
+    from oidc.jwks import JWKSCache
+    from oidc.settings import OidcSettings
+    from oidc.state import OidcState
+
+logger = logging.getLogger(__name__)
+
+
+class OidcAuthProvider(CachePersistence, SessionRenewal):
+    """Generic OIDC authentication with issuer-scoped identities."""
+
+    name = "oidc"
+    _is_auth_provider = True
+
+    def __init__(
+        self, settings: OidcSettings | None = None, *, state: OidcState | None = None
+    ) -> None:
+        self._initial_settings = settings
+        # The module's state object: a settings save or the boot-time DB
+        # hydration swaps ``state.settings``, so reading through it keeps
+        # ``trust_tenant_claim`` / ``role_mapping`` edits live.
+        self._state = state
+        self.jwks_cache: JWKSCache | None = None
+        self._warned_tenant_roles: set[str] = set()
+
+    @property
+    def _settings(self) -> OidcSettings | None:
+        live = getattr(self._state, "settings", None)
+        return live if live is not None else self._initial_settings
+
+    async def resolve_user(self, request: Request) -> UserContext | None:
+        credential = parse_bearer(request.headers.get("authorization"))
+        if credential is not None:
+            # An ``api_tokens`` credential is not a JWT: skip the parse and
+            # leave it to the principal resolver that owns it.
+            if is_api_token(credential):
+                return None
+            return await self._resolve_bearer(request, credential)
+
+        session = request.scope.get("session", {})
+        if not self._accept_session(session):
+            return None
+        # Renew authority from the IdP at expiry, without interrupting the request.
+        if type(session.get(SESSION_EXPIRES_AT_KEY)) is not int or session_has_expired(session):
+            return await self._refresh_session(request)
+        ctx = UserContext.from_session_dict(session.get(SESSION_USER_KEY))
+        if ctx is not None:
+            # The cookie froze what was decided at login; re-decide with the
+            # current settings, so turning trust_tenant_claim off takes effect
+            # on sessions that already exist.
+            ctx.tenant_id = self._trusted_tenant(ctx.tenant_id)
+            ctx.roles = self._without_tenant_roles(ctx.roles)
+        return ctx
+
+    def get_login_url(self, request: Request | None, next_url: str | None = None) -> str:
+        return LOGIN_PATH
+
+    def get_logout_url(self, request: Request | None) -> str:
+        return LOGOUT_PATH
+
+    def is_bearer_request(self, request: Request | None) -> bool:
+        if request is None:
+            return False
+        return parse_bearer(request.headers.get("authorization")) is not None
+
+    async def _resolve_bearer(self, request: Request, token: str) -> UserContext | None:
+        if self.jwks_cache is None or not self._settings or not self._settings.api_audience:
+            logger.debug("OIDC bearer authentication unavailable")
+            return None
+        claims = await self.jwks_cache.validate_jwt(token, audience=self._settings.api_audience)
+        if claims is None or not self._allowed_api_client(claims):
+            return None
+
+        cache_id = await self._upsert_user_cache(request, claims, throttle_login=True)
+        if cache_id is None:
+            return None
+        ctx = self._claims_to_user_context(claims, cache_id=cache_id)
+        # Full rights, but a bearer credential: it may not manage API tokens
+        # (``auth.contracts.tokens.AUTH_KIND_BEARER``). The browser sign-in
+        # builds the same context from the callback and keeps ``"session"``.
+        ctx.auth_kind = AUTH_KIND_BEARER
+        return ctx
+
+    def _allowed_api_client(self, claims: dict[str, Any]) -> bool:
+        """Whether the client that obtained this API token may call us.
+
+        Fails closed: a token naming no client (no ``azp``/``appid``) is refused.
+        """
+        s = self._settings
+        client = claims.get("azp") or claims.get("appid")
+        if not isinstance(client, str) or not client or not s:
+            return False
+        if client == s.client_id or client in s.api_allowed_client_ids:
+            return True
+        logger.info("OIDC bearer token from a client not in api_allowed_client_ids")
+        return False
+
+    def _claims_to_user_context(
+        self,
+        claims: dict[str, Any],
+        *,
+        cache_id: str,
+    ) -> UserContext:
+        s = self._settings
+        roles_raw = _extract_nested(claims, s.roles_claim_path) if s else None
+        mapping = s.role_mapping if s else {}
+        mapped = [mapping[r] for r in (roles_raw or []) if isinstance(r, str) and r in mapping]
+        return UserContext(
+            id=cache_id,
+            email=self._email(claims) or "",
+            email_verified=bool(
+                (not s or s.provider != "entra") and claims.get("email_verified") is True
+            ),
+            name=self._display_name(claims),
+            roles=self._without_tenant_roles(mapped),
+            tenant_id=self._trusted_tenant(claims.get("tenant_id")),
+        )
+
+    def _email(self, claims: dict[str, Any]) -> str | None:
+        """The configured email claim, or ``None`` when absent or not a string."""
+        value = claims.get(self._settings.email_claim if self._settings else "email")
+        return value if isinstance(value, str) else None
+
+    def _display_name(self, claims: dict[str, Any]) -> str:
+        s = self._settings
+        for name in (
+            s.username_claim if s else "preferred_username",
+            s.name_claim if s else "name",
+        ):
+            value = claims.get(name)
+            if isinstance(value, str) and value:
+                return value
+        return ""
+
+    def _subject(self, claims: dict[str, Any]) -> str:
+        key = self._settings.uid_claim if self._settings else "sub"
+        subject = claims.get(key)
+        if not isinstance(subject, str) or not subject.strip():
+            raise ValueError("Missing configured OIDC identity claim")
+        return subject
+
+    def _identity(self, claims: dict[str, Any]) -> tuple[str, str]:
+        issuer = claims.get("iss")
+        if not isinstance(issuer, str) or not issuer:
+            raise ValueError("Missing OIDC issuer")
+        return issuer, self._subject(claims)
+
+    def _trusted_tenant(self, value: Any) -> str | None:
+        return trusted_tenant(
+            value, trust_claim=bool(self._settings and self._settings.trust_tenant_claim)
+        )
+
+    def _without_tenant_roles(self, roles: list[str]) -> list[str]:
+        return without_tenant_roles(roles, warned=self._warned_tenant_roles, provider="Oidc")

oidc/renewal.py

@@ -0,0 +1,85 @@
+"""OIDC identity-token adapter for shared browser renewal."""
+
+from auth.oidc_common.renewal import refresh_session
+from auth.oidc_common.session import SessionKeys, accept_authority, authority_marker
+
+from oidc.constants import (
+    SESSION_IDENTITY_KEY,
+    SESSION_REFRESH_RETRY_AT_KEY,
+    SESSION_REFRESH_TOKEN_KEY,
+    SESSION_USER_KEY,
+)
+from oidc.runtime import require_client
+from oidc.tokens import open_refresh_token, store_refresh_token
+
+_KEYS = SessionKeys(
+    SESSION_USER_KEY,
+    SESSION_REFRESH_TOKEN_KEY,
+    SESSION_REFRESH_RETRY_AT_KEY,
+    "oidc_refresh_attempted",
+    identity=SESSION_IDENTITY_KEY,
+)
+
+
+class SessionRenewal:
+    _forget_session = staticmethod(_KEYS.forget)
+
+    @property
+    def _configured_issuer(self) -> str:
+        s = self._settings
+        return s.discovery_url.replace("/.well-known/openid-configuration", "", 1) if s else ""
+
+    @property
+    def _session_authority(self) -> str:
+        s = self._settings
+        return authority_marker(self.name, self._configured_issuer, s.client_id if s else "")
+
+    def _accept_session(self, session) -> bool:
+        return accept_authority(
+            session,
+            self._session_authority,
+            (SESSION_IDENTITY_KEY,),
+            SESSION_USER_KEY,
+            legacy_ok=lambda: self._legacy_identity_matches(session),
+        )
+
+    def _legacy_identity_matches(self, session) -> bool:
+        identity = session.get(SESSION_IDENTITY_KEY)
+        if (
+            not isinstance(identity, list)
+            or len(identity) != 2
+            or not self.jwks_cache
+            or not self._settings
+        ):
+            return False
+        issuer = self.jwks_cache.issuer
+        configured = self._configured_issuer
+        # Discovery tolerates a trailing slash; token issuers must match exactly.
+        return issuer.rstrip("/") == configured.rstrip("/") and identity[0] == issuer
+
+    async def _refresh_session(self, request):
+        async def refresh(token):
+            return await (await require_client(request)).refresh_tokens(token)
+
+        async def validate(tokens):
+            return await self.jwks_cache.validate_jwt(
+                tokens.get("id_token", ""), audience=self._settings.client_id
+            )
+
+        async def matches(claims, old_ctx):
+            try:
+                return list(self._identity(claims)) == request.session.get(SESSION_IDENTITY_KEY)
+            except ValueError:
+                return False
+
+        return await refresh_session(
+            request,
+            keys=_KEYS,
+            cache=self.jwks_cache,
+            open_token=open_refresh_token,
+            store_token=store_refresh_token,
+            refresh=refresh,
+            validate=validate,
+            matches_identity=matches,
+            to_context=self._claims_to_user_context,
+        )

oidc/runtime.py

@@ -0,0 +1,74 @@
+"""Initialize one coherent discovery/client/JWKS configuration per process."""
+
+import logging
+
+from fastapi import HTTPException, Request
+
+from oidc.client import OIDCClient
+from oidc.constants import SESSION_USER_KEY
+from oidc.discovery import fetch_metadata
+from oidc.jwks import JWKSCache
+
+logger = logging.getLogger(__name__)
+_DISCOVERY_SUFFIX = "/.well-known/openid-configuration"
+
+
+async def initialize(app) -> bool:
+    state = app.state.oidc
+    development = app.state.sm.settings.environment == "development"
+    async with state.initialization_lock:
+        if state.client is not None:
+            return True
+        s = state.settings
+        try:
+            if not s.discovery_url or not s.client_id:
+                raise ValueError("OIDC discovery URL and client ID are required")
+            if _DISCOVERY_SUFFIX not in s.discovery_url:
+                raise ValueError("OIDC discovery URL must identify its issuer")
+            # OIDC discovery uses either issuer + suffix or suffix + issuer path.
+            prefix, suffix = s.discovery_url.split(_DISCOVERY_SUFFIX, 1)
+            expected_issuer = prefix + suffix
+            metadata = await fetch_metadata(
+                s.discovery_url, expected_issuer=expected_issuer, development=development
+            )
+            cache = JWKSCache(
+                metadata.jwks_uri,
+                ttl_seconds=s.jwks_cache_ttl_seconds,
+                issuer=metadata.issuer,
+                audience=s.client_id,
+            )
+            client = OIDCClient(
+                authorization_endpoint=metadata.authorization_endpoint,
+                token_endpoint=metadata.token_endpoint,
+                end_session_endpoint=metadata.end_session_endpoint,
+                revocation_endpoint=metadata.revocation_endpoint,
+                token_endpoint_auth_methods_supported=metadata.token_endpoint_auth_methods_supported,
+                revocation_endpoint_auth_methods_supported=(
+                    metadata.revocation_endpoint_auth_methods_supported
+                ),
+                client_id=s.client_id,
+                client_secret=s.client_secret,
+            )
+        except Exception as exc:
+            if not development:
+                raise RuntimeError("OIDC discovery failed; authentication unavailable") from exc
+            logger.warning("OIDC discovery unavailable; login will retry")
+            return False
+        state.metadata, state.jwks_cache, state.client = metadata, cache, client
+        app.state.auth.auth_provider.jwks_cache = cache
+        return True
+
+
+async def require_client(request: Request) -> OIDCClient:
+    """The configured client, initialising lazily; 503 when the provider is unavailable."""
+    if request.app.state.oidc.client is None:
+        await initialize(request.app)
+    client = request.app.state.oidc.client
+    if client is None:
+        raise HTTPException(status_code=503, detail="OIDC provider not configured")
+    return client
+
+
+def is_signed_in(session) -> bool:
+    """Whether the browser session already holds an OIDC sign-in."""
+    return isinstance(session.get(SESSION_USER_KEY), dict)

oidc/settings.py

@@ -0,0 +1,131 @@
+"""OIDC module settings -- DB-backed via ``register_module_settings``.
+
+Configuration is preset-driven: pick a ``provider`` preset (e.g. ``entra``) and
+supply the few required secrets; the preset fills claim defaults and derives the
+discovery URL. ``generic`` works with any OIDC provider given a ``discovery_url``.
+"""
+
+from __future__ import annotations
+
+import os
+
+from pydantic import Field, field_validator, model_validator
+from pydantic_settings import SettingsConfigDict
+from simple_module_core.dotenv import env_str
+from simple_module_core.environments import NON_PROD_ENVIRONMENTS
+from simple_module_core.redirect_safety import non_empty_redirect
+from simple_module_core.settings_base import DbBackedSettings
+from simple_module_core.stored_settings import field_error
+
+from oidc.constants import DEFAULT_LOGIN_REDIRECT_URL
+from oidc.presets import get_preset
+
+# Sentinel for "unset by the user" so the preset can supply a default while still
+# letting an explicit empty/other value win.
+_UNSET = "__unset__"
+
+
+class OidcSettings(DbBackedSettings):
+    """Generic OIDC configuration with per-provider presets."""
+
+    model_config = SettingsConfigDict(extra="ignore")
+
+    provider: str = Field(
+        default=env_str("SM_OIDC_PROVIDER", "generic"), json_schema_extra={"requires_restart": True}
+    )
+
+    # Endpoint discovery. ``discovery_url`` wins; otherwise the preset derives it
+    # from ``tenant_id`` (Entra). The well-known doc supplies all endpoints + issuer.
+    discovery_url: str = Field(
+        default=env_str("SM_OIDC_DISCOVERY_URL", ""), json_schema_extra={"requires_restart": True}
+    )
+    tenant_id: str = Field(
+        default=env_str("SM_OIDC_TENANT_ID", ""), json_schema_extra={"requires_restart": True}
+    )
+
+    client_id: str = Field(
+        default=env_str("SM_OIDC_CLIENT_ID", ""), json_schema_extra={"requires_restart": True}
+    )
+    client_secret: str = Field(
+        default=env_str("SM_OIDC_CLIENT_SECRET", ""), json_schema_extra={"requires_restart": True}
+    )
+
+    # Bearer authentication is opt-in; browser ID tokens always use client_id.
+    api_audience: str = ""
+    # Clients (``azp``, or ``appid`` on Entra v1 tokens) allowed to call the API
+    # with a bearer token, besides ``client_id``. An API token is minted for our
+    # audience but by any client the IdP lets ask for it, so name each one.
+    api_allowed_client_ids: list[str] = Field(
+        default_factory=list,
+        description=(
+            "Client IDs (token azp, or appid on Entra v1) besides client_id allowed to call "
+            "the API with a bearer token. Empty: only this app's own client."
+        ),
+    )
+    trust_tenant_claim: bool = False
+
+    # Claim mapping. ``_UNSET`` defaults are replaced by the preset's value.
+    scope: str = _UNSET
+    uid_claim: str = _UNSET
+    username_claim: str = _UNSET
+    email_claim: str = _UNSET
+    name_claim: str = _UNSET
+    # Env-seedable: the first admin can only sign in once roles are mapped, and
+    # the Settings UI that edits this needs an admin. A stored value still wins.
+    roles_claim_path: str = env_str("SM_OIDC_ROLES_CLAIM_PATH", _UNSET)
+
+    login_redirect_url: str = DEFAULT_LOGIN_REDIRECT_URL
+    jwks_cache_ttl_seconds: int = Field(
+        default=3600, ge=0, json_schema_extra={"requires_restart": True}
+    )
+
+    role_mapping: dict[str, str] = Field(
+        default_factory=lambda: {"admin": "admin", "user": "user"},
+    )
+
+    @field_validator("login_redirect_url")
+    @classmethod
+    def _non_empty_redirect(cls, value: str) -> str:
+        return non_empty_redirect(value, default=DEFAULT_LOGIN_REDIRECT_URL)
+
+    @model_validator(mode="after")
+    def _apply_preset(self) -> OidcSettings:
+        preset = get_preset(self.provider)
+        if self.provider == "entra":
+            from urllib.parse import urlsplit
+
+            forbidden = {"common", "organizations", "consumers"}
+            segments = urlsplit(self.discovery_url).path.lower().split("/")
+            if self.tenant_id.strip().lower() in forbidden or forbidden.intersection(segments):
+                raise ValueError("Entra supports single-tenant configuration only")
+        for name in (
+            "uid_claim",
+            "username_claim",
+            "email_claim",
+            "name_claim",
+            "roles_claim_path",
+            "scope",
+        ):
+            if getattr(self, name) == _UNSET:
+                setattr(self, name, getattr(preset, name))
+        if not self.discovery_url and self.tenant_id:
+            self.discovery_url = preset.discovery_url(self.tenant_id)
+        return self
+
+    @model_validator(mode="after")
+    def _check_required_in_production(self) -> OidcSettings:
+        env = os.environ.get("SM_ENVIRONMENT", "development")
+        if env in NON_PROD_ENVIRONMENTS:
+            return self
+        required = ("discovery_url", "client_id", "client_secret")
+        missing = [field for field in required if not getattr(self, field)]
+        if missing:
+            raise field_error(
+                type(self),
+                missing[0],
+                "oidc_settings_required",
+                f"OIDC settings required in production: {', '.join(missing)}",
+                value="",
+                related=list(required),
+            )
+        return self

oidc/state.py

@@ -0,0 +1,25 @@
+"""Module-scoped state container for the oidc module."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from oidc.client import OIDCClient
+    from oidc.discovery import OidcMetadata
+    from oidc.jwks import JWKSCache
+    from oidc.settings import OidcSettings
+
+
+@dataclass
+class OidcState:
+    """OIDC-module singletons. Single slot at ``app.state.oidc``."""
+
+    settings: OidcSettings
+    metadata: OidcMetadata | None = None
+    jwks_cache: JWKSCache | None = None
+    client: OIDCClient | None = None
+
+    initialization_lock: asyncio.Lock = field(default_factory=asyncio.Lock)

oidc/tokens.py

@@ -0,0 +1,10 @@
+"""Provider-scoped refresh-token encryption; preserves existing session ciphertext."""
+
+from auth.oidc_common.tokens import provider_tokens
+
+from oidc.constants import SESSION_REFRESH_TOKEN_KEY
+
+_TOKENS = provider_tokens(info=b"oidc-refresh-token", session_key=SESSION_REFRESH_TOKEN_KEY)
+seal_refresh_token = _TOKENS.seal_refresh_token
+open_refresh_token = _TOKENS.open_refresh_token
+store_refresh_token = _TOKENS.store_refresh_token