fastapi-identity-model 0.1.0__py3-none-any.whl

fastapi_identity_model/__init__.py

@@ -0,0 +1,49 @@
+"""fastapi-identity-model: OIDC/OAuth2 integration for FastAPI.
+
+Built on `py-identity-model`. Provides:
+
+- ``TokenValidationMiddleware`` — validate incoming Bearer tokens (resource server).
+- ``build_oidc_router`` — a mountable authorization-code + PKCE login flow (RP).
+- ``Depends``-based helpers — ``get_current_user``, ``require_scope``, ``require_claim`` …
+- ``TokenManager`` — access-token refresh lifecycle.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .config import OIDCSettings
+from .dependencies import (
+    Claims,
+    CurrentUser,
+    get_claim_value,
+    get_claim_values,
+    get_claims,
+    get_current_user,
+    get_token,
+    require_claim,
+    require_scope,
+)
+from .middleware import TokenValidationMiddleware
+from .rp import build_oidc_router
+from .token_manager import TokenManager
+
+
+try:
+    __version__ = version("fastapi-identity-model")
+except PackageNotFoundError:  # pragma: no cover - only during local, uninstalled use
+    __version__ = "0.0.0"
+
+__all__ = [
+    "Claims",
+    "CurrentUser",
+    "OIDCSettings",
+    "TokenManager",
+    "TokenValidationMiddleware",
+    "build_oidc_router",
+    "get_claim_value",
+    "get_claim_values",
+    "get_claims",
+    "get_current_user",
+    "get_token",
+    "require_claim",
+    "require_scope",
+]

fastapi_identity_model/config.py

@@ -0,0 +1,83 @@
+"""Typed configuration for the FastAPI OIDC integration."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import os
+
+
+def _default_excluded_paths() -> list[str]:
+    return ["/docs", "/openapi.json", "/health"]
+
+
+@dataclass
+class OIDCSettings:
+    """Configuration shared by the RP login router and the resource-server middleware.
+
+    Attributes:
+        discovery_url: OpenID Connect discovery document URL of the provider.
+        client_id: OAuth2 client identifier.
+        redirect_uri: Absolute callback URL registered with the provider
+            (must match the router's ``/callback`` route). Only required for the
+            login router; a resource-server-only deployment may leave it empty.
+        client_secret: Client secret; omit for public/PKCE clients.
+        scope: Space-delimited scopes requested at authorization.
+        audience: Expected ``aud`` for the resource-server middleware. Defaults
+            to ``client_id`` when not set.
+        post_login_redirect: Where ``/callback`` redirects after a successful login.
+        post_logout_redirect: Where ``/logout`` redirects after clearing the session.
+        excluded_paths: Paths the resource-server middleware skips (health/docs).
+    """
+
+    discovery_url: str
+    client_id: str
+    redirect_uri: str = ""
+    client_secret: str | None = None
+    scope: str = "openid profile email"
+    audience: str | None = None
+    post_login_redirect: str = "/"
+    post_logout_redirect: str = "/"
+    excluded_paths: list[str] = field(default_factory=_default_excluded_paths)
+
+    def __post_init__(self) -> None:
+        # Validate required fields are non-empty even on direct construction
+        # (from_env guards its own inputs, but OIDCSettings(...) did not).
+        for name in ("discovery_url", "client_id"):
+            if not getattr(self, name):
+                raise ValueError(f"OIDCSettings requires a non-empty {name}")
+        # The middleware validates the ID/access token audience; default it to
+        # the client_id, which is the audience Descope and most OPs mint.
+        if self.audience is None:
+            self.audience = self.client_id
+
+    @classmethod
+    def from_env(cls, prefix: str = "OIDC_") -> OIDCSettings:
+        """Build settings from environment variables (e.g. ``OIDC_DISCOVERY_URL``).
+
+        Required: ``{prefix}DISCOVERY_URL``, ``{prefix}CLIENT_ID``. ``REDIRECT_URI``
+        is required only for the login router; a resource-server-only deployment
+        may omit it. Others fall back to the dataclass defaults.
+        """
+
+        def _req(name: str) -> str:
+            value = os.environ.get(f"{prefix}{name}")
+            if not value:
+                raise ValueError(f"Missing required env var {prefix}{name}")
+            return value
+
+        excluded = os.environ.get(f"{prefix}EXCLUDED_PATHS")
+        return cls(
+            discovery_url=_req("DISCOVERY_URL"),
+            client_id=_req("CLIENT_ID"),
+            redirect_uri=os.environ.get(f"{prefix}REDIRECT_URI", ""),
+            client_secret=os.environ.get(f"{prefix}CLIENT_SECRET"),
+            scope=os.environ.get(f"{prefix}SCOPE", "openid profile email"),
+            audience=os.environ.get(f"{prefix}AUDIENCE"),
+            post_login_redirect=os.environ.get(f"{prefix}POST_LOGIN_REDIRECT", "/"),
+            post_logout_redirect=os.environ.get(f"{prefix}POST_LOGOUT_REDIRECT", "/"),
+            excluded_paths=(
+                [p.strip() for p in excluded.split(",") if p.strip()]
+                if excluded
+                else _default_excluded_paths()
+            ),
+        )

fastapi_identity_model/dependencies.py

@@ -0,0 +1,287 @@
+"""
+FastAPI dependency injection functions for accessing user claims and identity.
+
+These dependencies can be used in FastAPI route handlers to access
+validated token information and user claims.
+"""
+
+from collections.abc import Callable
+from typing import Annotated
+
+from fastapi import (  # type: ignore[attr-defined]
+    Depends,
+    HTTPException,
+    Request,
+    status,
+)
+
+from py_identity_model.identity import ClaimsPrincipal
+
+
+# Error message constants
+_NOT_AUTHENTICATED_MSG = "Not authenticated"
+
+
+def get_current_user(request: Request) -> ClaimsPrincipal:
+    """
+    Dependency to get the current authenticated user as a ClaimsPrincipal.
+
+    This dependency should be used after the TokenValidationMiddleware has
+    validated the token and attached the user to the request state.
+
+    Args:
+        request: The FastAPI request object
+
+    Returns:
+        ClaimsPrincipal: The authenticated user principal
+
+    Raises:
+        HTTPException: If no authenticated user is found
+
+    Example:
+        ```python
+        @app.get("/profile")
+        async def get_profile(
+            user: ClaimsPrincipal = Depends(get_current_user),
+        ):
+            return {"user_id": user.identity.name}
+        ```
+    """
+    if not hasattr(request.state, "user"):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=_NOT_AUTHENTICATED_MSG,
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    return request.state.user
+
+
+def get_claims(request: Request) -> dict:
+    """
+    Dependency to get all claims from the validated token.
+
+    Args:
+        request: The FastAPI request object
+
+    Returns:
+        dict: Dictionary of all claims from the token
+
+    Raises:
+        HTTPException: If no claims are found
+
+    Example:
+        ```python
+        @app.get("/claims")
+        async def get_all_claims(claims: dict = Depends(get_claims)):
+            return {"claims": claims}
+        ```
+    """
+    if not hasattr(request.state, "claims"):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=_NOT_AUTHENTICATED_MSG,
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    return request.state.claims
+
+
+def get_token(request: Request) -> str:
+    """
+    Dependency to get the raw JWT token.
+
+    Args:
+        request: The FastAPI request object
+
+    Returns:
+        str: The raw JWT token
+
+    Raises:
+        HTTPException: If no token is found
+
+    Example:
+        ```python
+        @app.get("/token-info")
+        async def get_token_info(token: str = Depends(get_token)):
+            return {"token_length": len(token)}
+        ```
+    """
+    if not hasattr(request.state, "token"):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=_NOT_AUTHENTICATED_MSG,
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    return request.state.token
+
+
+# Annotated type aliases for FastAPI dependency injection (avoids B008)
+CurrentUser = Annotated[ClaimsPrincipal, Depends(get_current_user)]
+Claims = Annotated[dict, Depends(get_claims)]
+
+
+def get_claim_value(claim_type: str) -> Callable[..., str | None]:
+    """
+    Factory function to create a dependency that extracts a specific claim value.
+
+    Args:
+        claim_type: The claim type to extract
+
+    Returns:
+        callable: A dependency function that extracts the claim value
+
+    Example:
+        ```python
+        # Create a dependency for the 'sub' claim
+        get_user_id = get_claim_value("sub")
+
+
+        @app.get("/user-data")
+        async def get_user_data(user_id: str = Depends(get_user_id)):
+            return {"user_id": user_id}
+        ```
+    """
+
+    def _get_claim(
+        user: CurrentUser,
+    ) -> str | None:
+        if user.identity is None:
+            return None
+        claim = user.identity.find_first(claim_type)
+        if claim:
+            return claim.value
+        return None
+
+    return _get_claim
+
+
+def get_claim_values(claim_type: str) -> Callable[..., list[str]]:
+    """
+    Factory function to create a dependency that extracts all values for a specific claim type.
+
+    Useful for claims that can have multiple values (like roles).
+
+    Args:
+        claim_type: The claim type to extract
+
+    Returns:
+        callable: A dependency function that extracts all claim values
+
+    Example:
+        ```python
+        # Create a dependency for the 'role' claim
+        get_user_roles = get_claim_values("role")
+
+
+        @app.get("/roles")
+        async def get_roles(roles: List[str] = Depends(get_user_roles)):
+            return {"roles": roles}
+        ```
+    """
+
+    def _get_claims(
+        user: CurrentUser,
+    ) -> list[str]:
+        if user.identity is None:
+            return []
+        claims = user.identity.find_all(claim_type)
+        return [claim.value for claim in claims]
+
+    return _get_claims
+
+
+def require_claim(
+    claim_type: str,
+    claim_value: str | None = None,
+) -> Callable[..., None]:
+    """
+    Factory function to create a dependency that requires a specific claim.
+
+    This can be used to enforce authorization based on claims.
+
+    Args:
+        claim_type: The required claim type
+        claim_value: Optional specific value the claim must have
+
+    Returns:
+        callable: A dependency function that validates the claim
+
+    Raises:
+        HTTPException: If the required claim is not present or doesn't match the value
+
+    Example:
+        ```python
+        # Require that the user has a 'role' claim with value 'admin'
+        require_admin = require_claim("role", "admin")
+
+
+        @app.delete("/users/{user_id}")
+        async def delete_user(user_id: str, _: None = Depends(require_admin)):
+            # Only users with admin role can access this
+            return {"message": f"User {user_id} deleted"}
+        ```
+    """
+
+    def _check_claim(
+        user: CurrentUser,
+    ) -> None:
+        if not user.has_claim(claim_type, claim_value):
+            if claim_value is None:
+                raise HTTPException(
+                    status_code=status.HTTP_403_FORBIDDEN,
+                    detail=f"Required claim '{claim_type}' not found",
+                )
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"Required claim '{claim_type}' with value '{claim_value}' not found",
+            )
+
+    return _check_claim
+
+
+def require_scope(scope: str) -> Callable[..., None]:
+    """
+    Factory function to create a dependency that requires a specific OAuth scope.
+
+    Args:
+        scope: The required scope
+
+    Returns:
+        callable: A dependency function that validates the scope
+
+    Raises:
+        HTTPException: If the required scope is not present
+
+    Example:
+        ```python
+        require_read_scope = require_scope("api.read")
+
+
+        @app.get("/data")
+        async def get_data(_: None = Depends(require_read_scope)):
+            return {"data": "sensitive information"}
+        ```
+    """
+
+    def _check_scope(claims: Claims) -> None:
+        # Scopes live in 'scope' (space-separated string) or 'scp' (array).
+        raw = claims.get("scope") or claims.get("scp")
+        if isinstance(raw, str):
+            scopes: list = raw.split()
+        elif isinstance(raw, (list, tuple)):
+            scopes = [s for s in raw if isinstance(s, str)]
+        else:
+            # A dict/number/None or any unexpected type is not a usable scope
+            # claim — fail closed rather than letting `in` match dict keys or
+            # raise a TypeError.
+            scopes = []
+
+        if scope not in scopes:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"Required scope '{scope}' not found",
+            )
+
+    return _check_scope

fastapi_identity_model/middleware.py

@@ -0,0 +1,180 @@
+"""
+FastAPI middleware for OAuth2/OIDC token validation.
+
+This module provides middleware components for validating Bearer tokens
+in FastAPI applications using py-identity-model.
+"""
+
+from collections.abc import Callable
+import logging
+
+from fastapi import Request, status  # type: ignore[attr-defined]
+from jwt import InvalidTokenError
+from starlette.middleware.base import (
+    BaseHTTPMiddleware,  # type: ignore[attr-defined]
+)
+from starlette.responses import (  # type: ignore[attr-defined]
+    JSONResponse,
+    Response,
+)
+
+from py_identity_model import (
+    NetworkException,
+    PyIdentityModelException,
+    TokenValidationConfig,
+    to_principal,
+)
+from py_identity_model.aio import validate_token
+
+
+logger = logging.getLogger("fastapi_identity_model")
+
+# Expected number of parts in "Bearer <token>" authorization header
+_BEARER_HEADER_PART_COUNT = 2
+
+# Claims that only ever appear in an ID token (OIDC Core 1.0 §2, §3.1.3.6).
+# Their presence means an ID token was presented where an access token is
+# expected — reject it to prevent token-substitution at the resource server.
+_ID_TOKEN_ONLY_CLAIMS = ("nonce", "at_hash", "c_hash")
+
+
+class TokenValidationMiddleware(BaseHTTPMiddleware):
+    """
+    Middleware for validating Bearer tokens on incoming requests.
+
+    This middleware automatically validates JWT tokens from the Authorization header
+    and attaches the validated claims to the request state.
+
+    Args:
+        app: The FastAPI application
+        discovery_url: The OpenID Connect discovery document URL
+        audience: Expected audience claim in the token. Required — a ``None``
+            audience does not enforce ``aud`` for tokens that omit the claim,
+            which on a shared multi-tenant issuer accepts tokens minted for
+            other clients.
+        excluded_paths: Paths that skip token validation. A path matches if it
+            equals an entry or is a subpath of one (``/docs`` also covers
+            ``/docs/oauth2-redirect``). Pass ``[]`` to exclude nothing. When
+            omitted, defaults to ``/docs``, ``/openapi.json``, ``/health``.
+        custom_claims_validator: Optional custom function to validate additional claims
+    """
+
+    def __init__(
+        self,
+        app,
+        discovery_url: str,
+        audience: str | None = None,
+        excluded_paths: list[str] | None = None,
+        custom_claims_validator: Callable | None = None,
+    ):
+        super().__init__(app)
+        if not audience:
+            raise ValueError(
+                "TokenValidationMiddleware requires a non-empty 'audience'; a "
+                "None/empty audience skips aud enforcement for aud-less tokens."
+            )
+        self.discovery_url = discovery_url
+        self.audience = audience
+        # ``is not None`` (not truthiness) so an explicit [] means "exclude
+        # nothing" instead of silently re-enabling the defaults.
+        self.excluded_paths = (
+            excluded_paths
+            if excluded_paths is not None
+            else ["/docs", "/openapi.json", "/health"]
+        )
+        self.custom_claims_validator = custom_claims_validator
+
+    def _is_excluded(self, path: str) -> bool:
+        """Whether *path* equals or is a subpath of an excluded entry.
+
+        A bare ``/`` entry matches only the root, never as a subpath prefix
+        (otherwise it would exclude every path).
+        """
+        for entry in self.excluded_paths:
+            if path == entry:
+                return True
+            prefix = entry.rstrip("/")
+            if prefix and path.startswith(prefix + "/"):
+                return True
+        return False
+
+    @staticmethod
+    def _unauthorized(detail: str) -> JSONResponse:
+        return JSONResponse(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            content={"detail": detail},
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    def _extract_bearer_token(self, request: Request) -> str | JSONResponse:
+        """Return the bearer token, or an error ``JSONResponse`` if absent/malformed."""
+        authorization = request.headers.get("Authorization")
+        if not authorization:
+            return self._unauthorized("Missing Authorization header")
+        parts = authorization.split()
+        if len(parts) != _BEARER_HEADER_PART_COUNT or parts[0].lower() != "bearer":
+            return self._unauthorized(
+                "Invalid Authorization header format. Expected: Bearer <token>"
+            )
+        return parts[1]
+
+    async def _authenticate(self, request: Request, token: str) -> JSONResponse | None:
+        """Validate *token* and attach claims; return an error response or None."""
+        try:
+            claims = await validate_token(
+                jwt=token,
+                token_validation_config=TokenValidationConfig(
+                    perform_disco=True,
+                    audience=self.audience,
+                    claims_validator=self.custom_claims_validator,
+                ),
+                disco_doc_address=self.discovery_url,
+            )
+            # Reject an ID token presented as an access token. With audience
+            # defaulted to client_id, an ID token's aud matches, so type must
+            # be discriminated on ID-token-only claims.
+            if any(c in claims for c in _ID_TOKEN_ONLY_CLAIMS):
+                return self._unauthorized("ID token cannot be used as an access token")
+            request.state.user = to_principal(claims)
+            request.state.claims = claims
+            request.state.token = token
+            return None
+        except NetworkException:
+            # Discovery/JWKS/network fetch failure is a transient server fault,
+            # not an authentication decision — surface 5xx so callers retry
+            # instead of treating a provider outage as a bad token.
+            logger.exception("Network error during token validation")
+            return JSONResponse(
+                status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+                content={"detail": "Authentication temporarily unavailable"},
+            )
+        except PyIdentityModelException as e:
+            return self._unauthorized(f"Token validation failed: {e!s}")
+        except InvalidTokenError as e:
+            # A malformed/undecodable token (e.g. raw pyjwt DecodeError from
+            # header parsing during key lookup) is a client error, not a 500.
+            return self._unauthorized(f"Invalid token: {e!s}")
+        except Exception:
+            # A genuinely unexpected (non-library) failure is a server fault,
+            # not an auth decision. Surface a 500 without leaking internals.
+            logger.exception("Unexpected error during token validation")
+            return JSONResponse(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                content={"detail": "Internal server error during authentication"},
+            )
+
+    async def dispatch(self, request: Request, call_next) -> Response:
+        """Process the request and validate the token if required."""
+        # CORS preflight carries no Authorization; excluded paths skip auth.
+        if request.method == "OPTIONS" or self._is_excluded(request.url.path):
+            return await call_next(request)
+
+        token = self._extract_bearer_token(request)
+        if isinstance(token, JSONResponse):
+            return token
+
+        auth_error = await self._authenticate(request, token)
+        if auth_error is not None:
+            return auth_error
+
+        return await call_next(request)

fastapi_identity_model/rp.py

@@ -0,0 +1,416 @@
+"""Relying-Party (OIDC login) router for FastAPI.
+
+``build_oidc_router`` returns a mountable :class:`fastapi.APIRouter` implementing
+the authorization-code + PKCE login flow against any OpenID Connect provider,
+using the async ``py_identity_model.aio`` API for all protocol work:
+
+    from fastapi import FastAPI
+    from starlette.middleware.sessions import SessionMiddleware
+    from fastapi_identity_model import OIDCSettings, build_oidc_router
+
+    app = FastAPI()
+    app.add_middleware(SessionMiddleware, secret_key="...")   # required
+    app.include_router(build_oidc_router(settings), prefix="/auth")
+
+Routes: ``GET /login`` → provider, ``GET/POST /callback`` (exchange + validate
++ nonce + UserInfo; the POST route accepts the OAuth 2.0 ``form_post`` response
+mode), ``POST /logout``. The transient PKCE/state/nonce are kept
+under a separate ``<session_key>.flow`` entry and popped on callback (single
+use); the resulting identity is written to ``session[session_key]`` only after
+a verified ID token, so reading ``session[session_key]`` never observes an
+in-flight login. Logout is POST-only so a cross-site GET cannot force it.
+
+Security note: browsers only send the session cookie on the cross-site POST a
+``form_post`` provider issues if it was set with ``same_site="none"`` (which
+requires ``https_only=True``); with the default ``lax`` the POST callback
+arrives without the flow cookie and fails with "No active login flow".
+``SessionMiddleware`` signs but does **not** encrypt the cookie.
+Identity claims stored there are tamper-proof but readable by the client. Raw
+tokens are stored only when ``store_tokens=True`` — enable that only with an
+encrypted or server-side session store. Logout clears the local session only;
+it does not call the provider's ``end_session_endpoint``.
+"""
+
+from __future__ import annotations
+
+import logging
+import secrets
+from typing import TYPE_CHECKING
+from urllib.parse import parse_qsl, urlencode
+
+from fastapi import APIRouter, HTTPException, Request, status
+from starlette.responses import RedirectResponse
+
+from py_identity_model import PyIdentityModelException
+from py_identity_model.aio import (
+    AuthorizationCodeTokenRequest,
+    DiscoveryDocumentRequest,
+    DiscoveryDocumentResponse,
+    TokenValidationConfig,
+    UserInfoRequest,
+    build_authorization_url,
+    generate_pkce_pair,
+    get_discovery_document,
+    get_userinfo,
+    parse_authorize_callback_response,
+    request_authorization_code_token,
+    validate_authorize_callback_state,
+    validate_token,
+)
+
+
+if TYPE_CHECKING:
+    from .config import OIDCSettings
+
+
+logger = logging.getLogger("fastapi_identity_model")
+
+_STATE_TOKEN_BYTES = 32
+
+
+def _flow_key(session_key: str) -> str:
+    """Session key holding transient login-flow state (state/nonce/verifier).
+
+    Kept separate from *session_key* (which holds the final identity) so a
+    consumer reading ``session[session_key]`` never observes an in-flight
+    login as an authenticated identity, and never sees the ``code_verifier``.
+    """
+    return f"{session_key}.flow"
+
+
+def _require_session(request: Request) -> None:
+    """Fail with a clear error when ``SessionMiddleware`` is not installed."""
+    if "session" not in request.scope:
+        raise RuntimeError(
+            "SessionMiddleware is required by the OIDC router but is not "
+            "installed. Add: app.add_middleware(SessionMiddleware, secret_key=...)"
+        )
+
+
+_WELL_KNOWN_SUFFIX = "/.well-known/openid-configuration"
+
+
+def _expected_issuer(discovery_url: str) -> str:
+    """Issuer implied by the discovery URL (OIDC Discovery 1.0 §4.1)."""
+    base = discovery_url.rstrip("/")
+    if base.endswith(_WELL_KNOWN_SUFFIX):
+        base = base[: -len(_WELL_KNOWN_SUFFIX)]
+    return base.rstrip("/")
+
+
+async def _discover(settings: OIDCSettings) -> DiscoveryDocumentResponse:
+    disco = await get_discovery_document(
+        DiscoveryDocumentRequest(address=settings.discovery_url),
+    )
+    if not disco.is_successful:
+        raise HTTPException(
+            status_code=status.HTTP_502_BAD_GATEWAY,
+            detail=f"OIDC discovery failed: {disco.error}",
+        )
+    # OIDC Discovery 1.0 §4.3: the document's issuer MUST match the URL the
+    # document was retrieved from (issuer mix-up defense). The library only
+    # validates the issuer's *format*; the equality check is the RP's job.
+    # Trailing slashes are normalized — issuer "https://op/" serves its
+    # document at "https://op/.well-known/openid-configuration".
+    expected = _expected_issuer(settings.discovery_url)
+    if (disco.issuer or "").rstrip("/") != expected:
+        raise HTTPException(
+            status_code=status.HTTP_502_BAD_GATEWAY,
+            detail=(
+                f"Discovery document issuer mismatch: expected '{expected}', "
+                f"got '{disco.issuer}'"
+            ),
+        )
+    return disco
+
+
+def _require_endpoint(value: str | None, name: str) -> str:
+    if not value:
+        raise HTTPException(
+            status_code=status.HTTP_502_BAD_GATEWAY,
+            detail=f"Provider discovery is missing '{name}'",
+        )
+    return value
+
+
+async def _login(
+    request: Request, settings: OIDCSettings, session_key: str
+) -> RedirectResponse:
+    _require_session(request)
+    disco = await _discover(settings)
+    authorization_endpoint = _require_endpoint(
+        disco.authorization_endpoint, "authorization_endpoint"
+    )
+    code_verifier, code_challenge = generate_pkce_pair()
+    state = secrets.token_urlsafe(_STATE_TOKEN_BYTES)
+    nonce = secrets.token_urlsafe(_STATE_TOKEN_BYTES)
+    request.session[_flow_key(session_key)] = {
+        "state": state,
+        "nonce": nonce,
+        "code_verifier": code_verifier,
+    }
+    url = build_authorization_url(
+        authorization_endpoint=authorization_endpoint,
+        client_id=settings.client_id,
+        redirect_uri=settings.redirect_uri,
+        scope=settings.scope,
+        state=state,
+        nonce=nonce,
+        code_challenge=code_challenge,
+        code_challenge_method="S256",
+    )
+    return RedirectResponse(url, status_code=status.HTTP_302_FOUND)
+
+
+async def _exchange_code(
+    settings: OIDCSettings,
+    disco: DiscoveryDocumentResponse,
+    code: str,
+    code_verifier: str,
+) -> dict:
+    """Exchange the authorization code and return the token dict."""
+    token_endpoint = _require_endpoint(disco.token_endpoint, "token_endpoint")
+    tok = await request_authorization_code_token(
+        AuthorizationCodeTokenRequest(
+            address=token_endpoint,
+            client_id=settings.client_id,
+            code=code,
+            redirect_uri=settings.redirect_uri,
+            code_verifier=code_verifier,
+            client_secret=settings.client_secret or None,
+        ),
+    )
+    if not tok.is_successful or not tok.token:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Token exchange failed: {tok.error}",
+        )
+    return tok.token
+
+
+async def _validate_id_token(
+    settings: OIDCSettings,
+    disco: DiscoveryDocumentResponse,
+    id_token: str,
+    expected_nonce: str,
+) -> dict:
+    """Validate the ID token (signature/iss/aud/exp/required claims) and bind the nonce."""
+    # Guard the issuer explicitly: a discovery doc missing ``issuer`` would
+    # otherwise pass ``issuer=None`` and silently disable issuer verification.
+    issuer = _require_endpoint(disco.issuer, "issuer")
+    try:
+        claims = await validate_token(
+            jwt=id_token,
+            token_validation_config=TokenValidationConfig(
+                perform_disco=True,
+                audience=settings.client_id,
+                issuer=issuer,
+                options={"verify_exp": True, "require": ["sub", "iat", "exp"]},
+            ),
+            disco_doc_address=settings.discovery_url,
+        )
+    except PyIdentityModelException as exc:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=f"ID token validation failed: {exc}",
+        ) from exc
+
+    # Nonce binding is the RP's responsibility — the library does not check it.
+    if claims.get("nonce") != expected_nonce:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Nonce mismatch",
+        )
+    return claims
+
+
+async def _fetch_userinfo(
+    disco: DiscoveryDocumentResponse,
+    access_token: str | None,
+    expected_sub: str | None,
+) -> dict:
+    """Fetch UserInfo, enforcing the OIDC Core 5.3.2 ``sub`` match as a hard gate.
+
+    An unavailable UserInfo endpoint (no endpoint, or a transient fetch
+    failure) is tolerated — identity is anchored on the validated ID token.
+    But a *successful* fetch whose ``sub`` disagrees with the ID token is a
+    token-substitution signal and must abort the login, not be swallowed.
+    """
+    userinfo_endpoint = disco.userinfo_endpoint
+    if not access_token or not userinfo_endpoint:
+        return {}
+    # Fetch without expected_sub so is_successful reflects only the fetch;
+    # the sub comparison is enforced here so a mismatch fails the login.
+    ui = await get_userinfo(
+        UserInfoRequest(address=userinfo_endpoint, token=access_token),
+    )
+    if not ui.is_successful:
+        logger.warning("UserInfo fetch failed, continuing on ID token: %s", ui.error)
+        return {}
+    claims = ui.claims or {}
+    if expected_sub is not None and claims.get("sub") != expected_sub:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="UserInfo subject does not match ID token subject",
+        )
+    return claims
+
+
+async def _callback(  # noqa: PLR0913  # request-scoped args + the router's build-time options
+    request: Request,
+    settings: OIDCSettings,
+    session_key: str,
+    callback_url: str,
+    *,
+    store_tokens: bool,
+    fetch_userinfo: bool,
+) -> RedirectResponse:
+    _require_session(request)
+    # Pop the flow state so it is single-use: a failed or replayed callback
+    # cannot reuse the same state/verifier for another attempt.
+    flow = request.session.pop(_flow_key(session_key), None)
+    if not flow or not {"state", "nonce", "code_verifier"} <= flow.keys():
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="No active login flow in session",
+        )
+
+    try:
+        cb = parse_authorize_callback_response(callback_url)
+    except PyIdentityModelException as exc:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Malformed authorization callback: {exc}",
+        ) from exc
+    if not cb.is_successful:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Authorization error: {cb.error}",
+        )
+    if not validate_authorize_callback_state(cb, flow["state"]).is_valid:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="State mismatch (possible CSRF)",
+        )
+    if cb.code is None:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Authorization response missing code",
+        )
+
+    disco = await _discover(settings)
+    token = await _exchange_code(settings, disco, cb.code, flow["code_verifier"])
+    id_token = token.get("id_token")
+    access_token = token.get("access_token")
+
+    # An OIDC login flow (openid scope, nonce sent) requires a verified ID
+    # token. Refuse to establish a session on a token response that omits it
+    # rather than degrading to an unauthenticated "logged-in" session.
+    if not id_token:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Provider did not return an ID token",
+        )
+    claims = await _validate_id_token(settings, disco, id_token, flow["nonce"])
+
+    userinfo: dict = {}
+    if fetch_userinfo:
+        userinfo = await _fetch_userinfo(disco, access_token, claims.get("sub"))
+
+    session_data: dict = {
+        "sub": claims.get("sub"),
+        "claims": claims,
+        "userinfo": userinfo,
+    }
+    if store_tokens:
+        session_data["tokens"] = {
+            "access_token": access_token,
+            "refresh_token": token.get("refresh_token"),
+            "id_token": id_token,
+        }
+    request.session[session_key] = session_data
+
+    return RedirectResponse(
+        settings.post_login_redirect,
+        status_code=status.HTTP_302_FOUND,
+    )
+
+
+def build_oidc_router(
+    settings: OIDCSettings,
+    *,
+    session_key: str = "oidc",
+    store_tokens: bool = False,
+    fetch_userinfo: bool = True,
+) -> APIRouter:
+    """Build an OIDC relying-party router.
+
+    Args:
+        settings: Provider/client configuration.
+        session_key: Key under which flow + identity state is kept in the session.
+        store_tokens: When True, also persist the access/refresh/id tokens in the
+            session (requires an encrypted or server-side session store).
+        fetch_userinfo: When False, skip the UserInfo request after ID-token
+            validation and anchor identity on the ID token claims alone —
+            for providers without a usable UserInfo endpoint, or to avoid
+            the extra round-trip per login.
+
+    Returns:
+        An ``APIRouter`` with ``/login``, ``/callback`` and ``/logout`` routes.
+    """
+    if not settings.redirect_uri:
+        raise ValueError(
+            "build_oidc_router requires settings.redirect_uri (the provider "
+            "callback URL); it is only optional for resource-server-only setups."
+        )
+    router = APIRouter()
+
+    @router.get("/login")
+    async def login(request: Request) -> RedirectResponse:
+        return await _login(request, settings, session_key)
+
+    @router.get("/callback")
+    async def callback(request: Request) -> RedirectResponse:
+        return await _callback(
+            request,
+            settings,
+            session_key,
+            str(request.url),
+            store_tokens=store_tokens,
+            fetch_userinfo=fetch_userinfo,
+        )
+
+    @router.post("/callback")
+    async def callback_form_post(request: Request) -> RedirectResponse:
+        # form_post response mode: the provider delivers the authorization
+        # response as an application/x-www-form-urlencoded POST body instead
+        # of query parameters. Rebuild a callback URL carrying the fields as
+        # a query string so GET and POST share the exact same validation path
+        # (parse → state → code → exchange). Parsed with stdlib parse_qsl —
+        # form_post is urlencoded by definition, so this avoids taking a
+        # python-multipart dependency for starlette's request.form().
+        body = (await request.body()).decode("utf-8", errors="replace")
+        params = urlencode(parse_qsl(body, keep_blank_values=True))
+        callback_url = str(request.url.replace(query=params))
+        return await _callback(
+            request,
+            settings,
+            session_key,
+            callback_url,
+            store_tokens=store_tokens,
+            fetch_userinfo=fetch_userinfo,
+        )
+
+    @router.post("/logout")
+    async def logout(request: Request) -> RedirectResponse:
+        # POST-only: a state-changing session mutation must not be triggerable
+        # by a cross-site GET (e.g. an <img> tag) under a Lax cookie.
+        _require_session(request)
+        request.session.pop(session_key, None)
+        request.session.pop(_flow_key(session_key), None)
+        return RedirectResponse(
+            settings.post_logout_redirect,
+            status_code=status.HTTP_303_SEE_OTHER,
+        )
+
+    return router

fastapi_identity_model/token_manager.py

@@ -0,0 +1,162 @@
+"""Access-token lifecycle management for FastAPI applications.
+
+``TokenManager`` keeps an access/refresh token pair and transparently refreshes
+the access token (via the library's native async refresh grant) shortly before
+it expires. It is a thin convenience layer over
+:func:`py_identity_model.aio.refresh_token` — all protocol work lives in the
+core library.
+"""
+
+import asyncio
+from datetime import UTC, datetime, timedelta
+
+from py_identity_model import PyIdentityModelException
+from py_identity_model.aio import (
+    DiscoveryDocumentRequest,
+    RefreshTokenRequest,
+    get_discovery_document,
+    refresh_token,
+)
+
+
+class TokenManager:
+    """Manage an access token, refreshing it automatically before expiry.
+
+    Example:
+        ```python
+        manager = TokenManager(
+            discovery_url="https://auth.example.com/.well-known/openid-configuration",
+            client_id="my-client-id",
+            client_secret="my-client-secret",
+        )
+        manager.set_tokens(
+            access_token="initial_access_token",
+            refresh_token="initial_refresh_token",
+            expires_in=3600,
+        )
+        token = await manager.get_access_token()  # auto-refreshes if near expiry
+        ```
+    """
+
+    def __init__(
+        self,
+        discovery_url: str,
+        client_id: str,
+        client_secret: str | None = None,
+        refresh_before_seconds: int = 300,
+    ):
+        """Initialize the token manager.
+
+        Args:
+            discovery_url: The OpenID Connect discovery document URL.
+            client_id: The OAuth2 client ID.
+            client_secret: The OAuth2 client secret (omit for public clients).
+            refresh_before_seconds: Refresh this many seconds before expiry.
+        """
+        self.discovery_url = discovery_url
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.refresh_before_seconds = refresh_before_seconds
+
+        self._access_token: str | None = None
+        self._refresh_token: str | None = None
+        self._expires_at: datetime | None = None
+        # Serialize refreshes so concurrent callers don't each fire the grant
+        # (which, with refresh-token rotation, would invalidate the family).
+        self._refresh_lock = asyncio.Lock()
+
+    def set_tokens(
+        self,
+        access_token: str,
+        refresh_token: str | None = None,
+        expires_in: int | None = None,
+    ) -> None:
+        """Store the current token pair and (optionally) its expiry."""
+        self._access_token = access_token
+        self._refresh_token = refresh_token
+        # ``is not None`` (not truthiness) so expires_in=0 means "already
+        # expired" rather than "no expiry / never refresh".
+        self._expires_at = (
+            datetime.now(UTC) + timedelta(seconds=expires_in)
+            if expires_in is not None
+            else None
+        )
+
+    def is_token_expired(self) -> bool:
+        """Return True if the access token is expired or within the refresh window."""
+        if not self._expires_at:
+            return False
+        return datetime.now(UTC) >= (
+            self._expires_at - timedelta(seconds=self.refresh_before_seconds)
+        )
+
+    async def _resolve_token_endpoint(self) -> str:
+        """Resolve the token endpoint from discovery (per-process cached by the library)."""
+        disco = await get_discovery_document(
+            DiscoveryDocumentRequest(address=self.discovery_url),
+        )
+        if not disco.is_successful or not disco.token_endpoint:
+            raise PyIdentityModelException(
+                f"Discovery failed while refreshing token: {disco.error or 'no token endpoint'}",
+            )
+        return disco.token_endpoint
+
+    async def get_access_token(self) -> str | None:
+        """Return the current access token, refreshing it first if necessary.
+
+        Raises:
+            PyIdentityModelException: If a refresh is required but no refresh
+                token is available, or the refresh grant fails.
+        """
+        if self._access_token and not self.is_token_expired():
+            return self._access_token
+
+        async with self._refresh_lock:
+            # Re-check under the lock: a concurrent caller may have already
+            # refreshed while this one waited to acquire it.
+            if self._access_token and not self.is_token_expired():
+                return self._access_token
+
+            if not self._refresh_token:
+                raise PyIdentityModelException(
+                    "Token expired and no refresh token available",
+                )
+
+            token_endpoint = await self._resolve_token_endpoint()
+            response = await refresh_token(
+                RefreshTokenRequest(
+                    address=token_endpoint,
+                    client_id=self.client_id,
+                    refresh_token=self._refresh_token,
+                    client_secret=self.client_secret,
+                ),
+            )
+
+            if not response.is_successful or not response.token:
+                raise PyIdentityModelException(
+                    f"Token refresh failed: {response.error or 'no token in response'}",
+                )
+
+            new_access_token = response.token.get("access_token")
+            if not new_access_token:
+                raise PyIdentityModelException(
+                    "Token refresh succeeded but no access token returned",
+                )
+
+            self.set_tokens(
+                access_token=new_access_token,
+                refresh_token=response.token.get("refresh_token")
+                or self._refresh_token,
+                expires_in=response.token.get("expires_in"),
+            )
+            return self._access_token
+
+    @property
+    def access_token(self) -> str | None:
+        """The current access token, without triggering a refresh."""
+        return self._access_token
+
+    @property
+    def refresh_token(self) -> str | None:
+        """The current refresh token."""
+        return self._refresh_token

fastapi_identity_model-0.1.0.dist-info/METADATA

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: fastapi-identity-model
+Version: 0.1.0
+Summary: FastAPI OIDC/OAuth2 middleware and relying-party router, built on py-identity-model
+Project-URL: Homepage, https://github.com/jamescrowley321/py-identity-model
+Project-URL: Repository, https://github.com/jamescrowley321/py-identity-model
+Project-URL: Issues, https://github.com/jamescrowley321/py-identity-model/issues
+Author-email: jamescrowley321 <jamescrowley151@gmail.com>
+License-Expression: Apache-2.0
+Keywords: authentication,fastapi,jwt,middleware,oauth2,oidc,openid-connect
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: itsdangerous>=2.0
+Requires-Dist: py-identity-model>=3.1.0
+Requires-Dist: starlette>=0.49.1
+Provides-Extra: server
+Requires-Dist: uvicorn[standard]>=0.23.0; extra == 'server'
+Description-Content-Type: text/markdown
+
+# fastapi-identity-model
+
+OIDC/OAuth2 integration for [FastAPI](https://fastapi.tiangolo.com/), built on
+[`py-identity-model`](https://pypi.org/project/py-identity-model/) — an OpenID
+Foundation–certified relying-party library.
+
+It gives you two composable pieces:
+
+| Piece | Use case |
+|-------|----------|
+| **`TokenValidationMiddleware`** + `Depends` helpers | Protect an **API / resource server** that receives `Authorization: Bearer <token>` |
+| **`build_oidc_router`** | Add a browser **login flow** (authorization code + PKCE) to your app (relying party) |
+
+## Install
+
+```bash
+pip install fastapi-identity-model
+# with a server for the demo:
+pip install "fastapi-identity-model[server]"
+```
+
+## Resource server — validate incoming Bearer tokens
+
+```python
+from fastapi import FastAPI, Depends
+from fastapi_identity_model import (
+    TokenValidationMiddleware, OIDCSettings, get_current_user, require_scope,
+)
+
+settings = OIDCSettings.from_env()  # OIDC_DISCOVERY_URL, OIDC_CLIENT_ID, OIDC_REDIRECT_URI, ...
+app = FastAPI()
+app.add_middleware(
+    TokenValidationMiddleware,
+    discovery_url=settings.discovery_url,
+    audience=settings.audience,
+    excluded_paths=settings.excluded_paths,
+)
+
+@app.get("/api/me")
+async def me(user = Depends(get_current_user)):
+    return {"sub": user.identity.name, "authenticated": user.identity.is_authenticated}
+
+@app.get("/api/data", dependencies=[Depends(require_scope("api.read"))])
+async def data():
+    return {"data": "protected"}
+```
+
+The middleware validates the token (signature, issuer, audience, expiry) via
+`py-identity-model` and attaches a `ClaimsPrincipal` to `request.state.user`.
+Invalid tokens → **401**; an unexpected server-side failure → **500** (never
+masked as a 401).
+
+## Relying party — browser login flow
+
+```python
+import os
+
+from fastapi import FastAPI, Request
+from starlette.middleware.sessions import SessionMiddleware
+from fastapi_identity_model import OIDCSettings, build_oidc_router
+
+settings = OIDCSettings(
+    discovery_url="https://api.descope.com/v1/apps/<project_id>/.well-known/openid-configuration",
+    client_id="<client_id>",
+    redirect_uri="http://localhost:8000/auth/callback",
+    scope="openid profile email",
+)
+
+app = FastAPI()
+# Use a strong secret from the environment — never a committed literal, or
+# anyone can forge a session cookie. same_site="lax" is required so the
+# provider's redirect back to /auth/callback carries the session cookie.
+app.add_middleware(
+    SessionMiddleware,
+    secret_key=os.environ["SESSION_SECRET"],
+    same_site="lax",
+    https_only=True,  # behind TLS
+)
+app.include_router(build_oidc_router(settings), prefix="/auth")
+
+@app.get("/me")
+async def me(request: Request):
+    return request.session.get("oidc", {})   # {"sub", "claims", "userinfo"} after login
+```
+
+Routes added: `GET /auth/login` → provider, `GET /auth/callback` (code exchange,
+ID-token validation, **nonce check**, UserInfo `sub` verification), `POST /auth/logout`.
+
+### Session & security
+
+The router uses Starlette's `SessionMiddleware`, which **signs but does not
+encrypt** the cookie. Stored identity claims are tamper-proof but readable by the
+client. Raw tokens are stored **only** when you pass `build_oidc_router(settings,
+store_tokens=True)` — enable that only with an encrypted or server-side session
+store. For production, back the session with a server-side store.
+
+## Token refresh
+
+```python
+from fastapi_identity_model import TokenManager
+
+tm = TokenManager(discovery_url=..., client_id=..., client_secret=...)
+tm.set_tokens(access_token=..., refresh_token=..., expires_in=3600)
+access = await tm.get_access_token()   # auto-refreshes shortly before expiry
+```
+
+## License
+
+Apache-2.0 — see the repository `LICENSE`.

fastapi_identity_model-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+fastapi_identity_model/__init__.py,sha256=bDj_xyo9OBF2pkQQlUtxQ8Zo9mvmfgW23-ei6Hg06Qo,1308
+fastapi_identity_model/config.py,sha256=fLiY1lBQ6DaFtpbJOz05kAd8UxQzox5M21ep8DTiAYA,3616
+fastapi_identity_model/dependencies.py,sha256=SevwWcCyxtO-IspmLJWykBuz6eiQncDMk435-sxbEmI,7854
+fastapi_identity_model/middleware.py,sha256=_hszDh2Cg6DcL4AAbvVwC8JkZSU6v9ss3BT3veutj8w,7558
+fastapi_identity_model/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fastapi_identity_model/rp.py,sha256=ETY2dbqW9WXoeG8zo1ZtcuCP6sClAYsyVUAlKhj3NGk,15703
+fastapi_identity_model/token_manager.py,sha256=IO12GNoZdNMScgV1J7B7ZIPxVOI7Riz1S5OTcDpV0do,6025
+fastapi_identity_model-0.1.0.dist-info/METADATA,sha256=eMBUjtBdC46b23SIFeaK4u4Zy_lI0sNHZb98salwsXc,5121
+fastapi_identity_model-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+fastapi_identity_model-0.1.0.dist-info/RECORD,,

fastapi_identity_model-0.1.0.dist-info/WHEEL

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