fastapi-identity-model 0.1.0__tar.gz

fastapi_identity_model-0.1.0/.gitignore

@@ -0,0 +1,166 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# PyCharm
+.idea
+
+*.env*
+# Allow test fixture env files (no secrets — local Docker only)
+!.env.node-oidc
+*.crt
+*.key
+*.pfx
+.secrets.baseline
+
+# Claude Code runtime state
+.claude/mcp.json
+.claude/worktrees/
+.claude/task-state.md
+.claude/task-state*.md
+.claude/review-*.md
+.claude/review-*.patch
+.claude/pre-review-sha.txt
+
+# Conformance plan export zips + per-test RP logs (binary evidence artifacts;
+# preserved via CI upload-artifact, not committed)
+conformance/results/hosted/*.zip
+conformance/results/hosted/rp-logs/
+
+# Ralph orchestrator runtime state
+.ralph/
+PROMPT.md
+
+# Terraform
+infra/**/.terraform/
+infra/**/*.tfstate*
+infra/**/*.tfstate.backup
+infra/**/*.tfvars
+infra/**/access_key.json
+infra/**/expired_token.txt

fastapi_identity_model-0.1.0/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to `fastapi-identity-model` are documented here. This project
+adheres to [Semantic Versioning](https://semver.org/) and is released
+independently of the core `py-identity-model` library.
+
+## 0.1.0 (2026-07-08)
+
+Initial release. Extracted and hardened from the `py-identity-model` FastAPI
+example, then driven through the OIDF conformance suite: the RP router passes
+the same local Basic RP, Config RP, and Form Post RP plans the core library is
+certified against (13/13, 5/5, 13/13 — regression stage, see #437).
+
+### Added
+- `TokenValidationMiddleware` — resource-server Bearer-token validation that
+  attaches a `ClaimsPrincipal` to `request.state`.
+- `Depends` helpers: `get_current_user`, `get_claims`, `get_token`,
+  `get_claim_value`, `get_claim_values`, `require_claim`, `require_scope`.
+- `build_oidc_router` — mountable relying-party login flow (authorization code +
+  PKCE) with state/nonce, ID-token validation, and UserInfo `sub` verification.
+- `POST /callback` on the RP router — OAuth 2.0 `form_post` response mode,
+  sharing the exact GET validation path (parsed with stdlib `parse_qsl`; no
+  `python-multipart` dependency). Requires the session cookie to be issued
+  with `same_site="none"` in real browsers.
+- `build_oidc_router(fetch_userinfo=False)` — skip the UserInfo round-trip and
+  anchor identity on the validated ID token.
+- `OIDCSettings` — typed configuration with `from_env()`.
+- `TokenManager` — access-token refresh lifecycle over the native async refresh grant.
+
+### Changed vs. the former example
+- Middleware returns **503** for a discovery/JWKS/network fault and **500** for a
+  genuinely unexpected error, instead of masking either as a 401.
+- `TokenManager` uses the async discovery + native `aio.refresh_token` grant
+  (removes a blocking sync call in async context and a hand-rolled token POST).
+
+### Security
+- The RP router rejects a discovery document whose issuer does not match the
+  URL it was retrieved from (OIDC Discovery 1.0 §4.3 issuer mix-up defense).
+- The RP router refuses to establish a session when the token response has no
+  ID token, and enforces the UserInfo `sub` match as a hard gate (a mismatch
+  fails the login instead of being swallowed).
+- Transient login-flow state (state/nonce/PKCE verifier) is kept under a
+  separate session key from the identity and is single-use (popped on callback),
+  so an in-flight login is never read as an authenticated identity.
+- `TokenValidationMiddleware` rejects an ID token presented as an access token,
+  requires a non-empty `audience` (a `None` audience skips `aud` enforcement for
+  aud-less tokens), lets CORS preflight through, and matches excluded subpaths.
+- `POST /auth/logout` (was `GET`) so a cross-site request cannot force logout.
+- `TokenManager` refreshes under an `asyncio.Lock` (no concurrent-refresh
+  token-family invalidation) and treats `expires_in=0` as already expired.

fastapi_identity_model-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,109 @@
+# 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/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-0.1.0/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()
+            ),
+        )