simple-module-oidc 0.0.43__tar.gz

simple_module_oidc-0.0.43/.gitignore

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

simple_module_oidc-0.0.43/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.5
+Name: simple_module_oidc
+Version: 0.0.43
+Summary: Generic OIDC authentication provider for simple_module — native Microsoft Entra ID, Auth0, Okta, Keycloak, and any OpenID Connect identity provider
+Project-URL: Homepage, https://github.com/antosubash/simple_module_python
+Project-URL: Repository, https://github.com/antosubash/simple_module_python
+Author-email: Anto Subash <antosubash@live.com>
+License-Expression: MIT
+Keywords: authentication,azure-ad,entra,fastapi,oidc,simple-module
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: cryptography>=42
+Requires-Dist: httpx<0.29,>=0.27
+Requires-Dist: pyjwt[crypto]<3,>=2.8
+Requires-Dist: simple-module-auth==0.0.43
+Requires-Dist: simple-module-core==0.0.43
+Requires-Dist: simple-module-db==0.0.43
+Requires-Dist: simple-module-hosting==0.0.43
+Description-Content-Type: text/markdown
+
+# simple_module_oidc
+
+Generic **OpenID Connect** authentication provider for simple_module — with
+**native Microsoft Entra ID (Azure AD)** support, plus Auth0, Okta, Zitadel,
+Authentik, Keycloak, and any OIDC-compliant identity provider.
+
+The module is configured from a provider's OIDC **discovery document**
+(`.well-known/openid-configuration`), so endpoints (authorize / token / JWKS /
+logout) and the issuer are resolved automatically — no per-provider URL
+templating. Provider differences (claim names, scopes) are config; **presets**
+fill those in for you.
+
+It auto-registers as the application's auth provider. Browser users are
+redirected to the IdP's hosted login; mobile/API clients send a bearer token
+which is validated against the provider's JWKS when `api_audience` is configured.
+
+## Install
+
+Add to your app's `pyproject.toml` dependencies instead of another auth provider
+(e.g. `simple_module_users` / `simple_module_keycloak` — only one auth provider
+can be active):
+
+```toml
+dependencies = [
+    "simple_module_oidc",
+]
+```
+
+Run `uv sync --all-packages` to install.
+
+## Usage
+
+Select `SM_AUTH_PROVIDER=oidc` explicitly. Keep `Auth` enabled; `Settings` UI
+is optional. Exclude Users-dependent modules when selecting this provider.
+
+## Keycloak through the generic preset
+
+This is the primary worked example. The dedicated `keycloak` module is an
+alternative; this configuration uses `oidc` throughout.
+
+Create an OpenID Connect client in the Keycloak realm:
+
+- Enable client authentication (a confidential client) and the standard flow.
+- Set the valid redirect URI to `<app>/api/oidc/auth/callback`.
+- Set the valid post-logout redirect URI to `<app>/oidc/logged-out`.
+- Require PKCE with code challenge method **S256**.
+- Add realm roles to the **ID token**. Keycloak 26 puts `realm_access.roles`
+  only in the access token by default, and this module reads roles from the ID
+  token. Under Client scopes -> `roles` -> Mappers -> `realm roles`, turn on
+  **Add to ID token** (token claim name `realm_access.roles`, multivalued), or
+  add a **User Realm Role** mapper with those settings to the client's
+  dedicated scope. Then assign the intended realm roles (for example `admin`)
+  to users.
+- Keep the default `profile` and `email` client scopes: they supply
+  `preferred_username`, `name`, `email` and `email_verified` in the ID token.
+
+Use the realm's discovery document and the client's credentials:
+
+```dotenv
+SM_AUTH_PROVIDER=oidc
+SM_OIDC_PROVIDER=generic
+SM_OIDC_DISCOVERY_URL=https://<server>/realms/<realm>/.well-known/openid-configuration
+SM_OIDC_CLIENT_ID=<confidential-client-id>
+SM_OIDC_CLIENT_SECRET=<client-secret>
+SM_OIDC_ROLES_CLAIM_PATH=realm_access.roles
+```
+
+`SM_OIDC_ROLES_CLAIM_PATH` seeds the roles path so the first Keycloak admin is
+mapped to `admin` on first sign-in (the Settings UI that edits it needs an
+admin). A value saved in the UI later wins.
+
+Here `<app>` includes the application's scheme and host, and `<server>` is the
+Keycloak server (including any deployment prefix). Discovery is exactly
+`<server>/realms/<realm>/.well-known/openid-configuration` when `<server>` already
+includes the scheme. Use HTTPS outside development.
+
+Set these **DB settings** under the `oidc` namespace, using Settings → OIDC when
+the Settings UI is enabled:
+
+```json
+{
+  "role_mapping": {"admin": "admin", "user": "user"}
+}
+```
+
+Choose external roles and app roles appropriate for your host. `role_mapping`
+produces application roles; permission grants still come from the framework's
+permission registry. No mapping grants `tenant:*` roles. Visit `/oidc/login` to
+start sign-in. Cached identity is `(issuer, sub)` with a stable framework UUID.
+
+## Native Microsoft Entra ID
+
+Set the `entra` preset and your single-tenant registration details:
+
+```bash
+SM_AUTH_PROVIDER=oidc
+SM_OIDC_PROVIDER=entra
+SM_OIDC_TENANT_ID=<your-tenant-guid>
+SM_OIDC_CLIENT_ID=<app-registration-client-id>
+SM_OIDC_CLIENT_SECRET=<client-secret>
+```
+
+In the Entra app registration, add the redirect URI:
+
+```
+https://<your-host>/api/oidc/auth/callback
+```
+
+The `entra` preset derives the discovery URL
+(`https://login.microsoftonline.com/{tenant_id}/v2.0/.well-known/openid-configuration`),
+validates the **id_token**, keys the user cache on **(issuer, `oid`)**, and
+maps Entra **app roles** (the `roles` claim) to application roles via
+`role_mapping` (default: `admin` and `user` map 1:1). Assign app roles in
+*Entra → App registrations → App roles* and *Enterprise applications → Users and groups*.
+
+## Any other OIDC provider
+
+Use the `generic` preset with an explicit discovery URL:
+
+```bash
+SM_AUTH_PROVIDER=oidc
+SM_OIDC_PROVIDER=generic
+SM_OIDC_DISCOVERY_URL=https://<issuer>/.well-known/openid-configuration
+SM_OIDC_CLIENT_ID=<client-id>
+SM_OIDC_CLIENT_SECRET=<client-secret>
+```
+
+## Configuration reference
+
+| Env var | Default | Notes |
+|---|---|---|
+| `SM_OIDC_PROVIDER` | `generic` | Preset name (`entra`, `generic`). |
+| `SM_OIDC_DISCOVERY_URL` | — | Explicit discovery URL; wins over the preset. |
+| `SM_OIDC_TENANT_ID` | — | Used by templated presets (Entra) to derive the discovery URL. |
+| `SM_OIDC_CLIENT_ID` | — | OAuth client id. |
+| `SM_OIDC_CLIENT_SECRET` | — | OAuth client secret. |
+| `SM_OIDC_ROLES_CLAIM_PATH` | preset | Seeds `roles_claim_path`, so the first admin can sign in before the Settings UI is reachable. |
+
+Only the six environment variables above bootstrap process wiring, secrets and the first admin's roles path.
+These variables seed defaults; explicit DB values can override them.
+All other settings are DB-backed; bare environment names and the old claim
+mapping environment variables are ignored. Provider, discovery, tenant, client
+credentials and JWKS cache TTL changes require a restart. Claim and role mapping
+and tenant-claim trust read the live settings state.
+
+| DB setting | Default | Behaviour |
+|---|---|---|
+| `api_audience` | empty | Bearer authentication disabled until configured; ID tokens always use `client_id`. |
+| `api_allowed_client_ids` | empty | Clients besides `client_id` whose API tokens (`azp`, or `appid` on Entra v1) are accepted; a token naming no client is refused. |
+| `trust_tenant_claim` | false | Opt in only to a trusted, validated `tenant_id` claim. Entra `tid` never selects an application tenant. Membership resolution stays authoritative. |
+| `scope` | preset | Entra requests `openid email profile offline_access`. |
+| `uid_claim` | `oid` for Entra, otherwise `sub` | Required identity claim; there is no fallback. Identities use unique (issuer, subject) UUID mappings. |
+| `username_claim` / `name_claim` | `preferred_username` / `name` | Display name with fallback. |
+| `email_claim` | `email` | Display email; only generic OIDC literal `email_verified=true` attests ownership. Entra never attests it. |
+| `roles_claim_path` | `roles` for Entra, otherwise empty | Dotted claim path to role list. |
+| `role_mapping` | admin/user map to themselves | External roles to application roles; `tenant:*` roles are filtered on login and restored sessions. |
+| `login_redirect_url` | `/dashboard/` | Blank values normalize to the default. Saved deep links must be local paths. |
+| `jwks_cache_ttl_seconds` | 3600 | Last-good signing keys retained on outage; unknown keys share a 30-second fetch cooldown. |
+
+## Login, sessions and logout
+
+Entra supports a single tenant GUID. `common`, `organizations` and `consumers`
+are rejected. Unknown presets are validation errors. Discovery requires an issuer
+matching the configured discovery URL and HTTPS outside development; different
+endpoint hosts are supported. Discovery failure refuses boot outside development;
+development retries lazily on login.
+
+Authorization uses code flow with S256 PKCE, state and constant-time nonce
+validation. JWTs require `iss`, `sub`, `aud`, `exp` and `iat`, RS256 and the
+expected audience. Additional audiences are rejected, and a supplied `azp` on a browser ID token must name this client (required with multiple
+audiences); an API access token's `azp` is the calling client, checked against `api_allowed_client_ids` instead. The returned access token is unused, so `at_hash` is intentionally
+not checked.
+
+Sign-in replaces user-bound session state and rotates CSRF. The cookie never
+stores the ID token; it stores the ID-token expiry and an encrypted refresh token
+when supplied. Expired or unbounded sessions renew using a fresh ID token, with
+the same issuer and configured subject required. Definitive refresh rejection
+clears authentication. Providers that do not return an `id_token` on refresh
+sign the user out at expiry. Transport failures, 5xx and retryable 4xx preserve the
+expired session for another attempt, while this request stays unauthenticated;
+the token endpoint is not called again for 30 seconds, so a flapping IdP does not
+stall every request. A refresh token too large for the 4 KB session cookie (Entra
+can issue such tokens) is not stored, and that session ends at ID-token expiry.
+
+Logout best-effort revokes the refresh token when discovery advertises a
+`revocation_endpoint`, then always clears local state. The optional discovered logout endpoint gets
+`client_id` and `post_logout_redirect_uri`, without `id_token_hint`. Register
+`https://<your-host>/oidc/logged-out` as the post-logout URI. Providers requiring
+an ID-token hint may show a confirmation prompt or leave their SSO session active;
+the local signed-out page never automatically signs in.
+
+The host migration `c9d2e4f6a810` (`oidc@head`, #192) creates the identity cache.
+Apply host migrations with `upgrade heads` before deployment.
+
+## Activation
+
+Add `simple_module_oidc` to the host's `pyproject.toml` dependencies and
+`[tool.uv.sources]`, remove the competing provider, then `uv sync --all-packages`.
+Alternatively scope active modules with `SM_MODULES_ENABLED`.
+
+See [the full configuration reference](../../docs/modules/oidc.md)
+for every setting, its environment support, tenancy policy and deployment limits.

simple_module_oidc-0.0.43/README.md

@@ -0,0 +1,202 @@
+# simple_module_oidc
+
+Generic **OpenID Connect** authentication provider for simple_module — with
+**native Microsoft Entra ID (Azure AD)** support, plus Auth0, Okta, Zitadel,
+Authentik, Keycloak, and any OIDC-compliant identity provider.
+
+The module is configured from a provider's OIDC **discovery document**
+(`.well-known/openid-configuration`), so endpoints (authorize / token / JWKS /
+logout) and the issuer are resolved automatically — no per-provider URL
+templating. Provider differences (claim names, scopes) are config; **presets**
+fill those in for you.
+
+It auto-registers as the application's auth provider. Browser users are
+redirected to the IdP's hosted login; mobile/API clients send a bearer token
+which is validated against the provider's JWKS when `api_audience` is configured.
+
+## Install
+
+Add to your app's `pyproject.toml` dependencies instead of another auth provider
+(e.g. `simple_module_users` / `simple_module_keycloak` — only one auth provider
+can be active):
+
+```toml
+dependencies = [
+    "simple_module_oidc",
+]
+```
+
+Run `uv sync --all-packages` to install.
+
+## Usage
+
+Select `SM_AUTH_PROVIDER=oidc` explicitly. Keep `Auth` enabled; `Settings` UI
+is optional. Exclude Users-dependent modules when selecting this provider.
+
+## Keycloak through the generic preset
+
+This is the primary worked example. The dedicated `keycloak` module is an
+alternative; this configuration uses `oidc` throughout.
+
+Create an OpenID Connect client in the Keycloak realm:
+
+- Enable client authentication (a confidential client) and the standard flow.
+- Set the valid redirect URI to `<app>/api/oidc/auth/callback`.
+- Set the valid post-logout redirect URI to `<app>/oidc/logged-out`.
+- Require PKCE with code challenge method **S256**.
+- Add realm roles to the **ID token**. Keycloak 26 puts `realm_access.roles`
+  only in the access token by default, and this module reads roles from the ID
+  token. Under Client scopes -> `roles` -> Mappers -> `realm roles`, turn on
+  **Add to ID token** (token claim name `realm_access.roles`, multivalued), or
+  add a **User Realm Role** mapper with those settings to the client's
+  dedicated scope. Then assign the intended realm roles (for example `admin`)
+  to users.
+- Keep the default `profile` and `email` client scopes: they supply
+  `preferred_username`, `name`, `email` and `email_verified` in the ID token.
+
+Use the realm's discovery document and the client's credentials:
+
+```dotenv
+SM_AUTH_PROVIDER=oidc
+SM_OIDC_PROVIDER=generic
+SM_OIDC_DISCOVERY_URL=https://<server>/realms/<realm>/.well-known/openid-configuration
+SM_OIDC_CLIENT_ID=<confidential-client-id>
+SM_OIDC_CLIENT_SECRET=<client-secret>
+SM_OIDC_ROLES_CLAIM_PATH=realm_access.roles
+```
+
+`SM_OIDC_ROLES_CLAIM_PATH` seeds the roles path so the first Keycloak admin is
+mapped to `admin` on first sign-in (the Settings UI that edits it needs an
+admin). A value saved in the UI later wins.
+
+Here `<app>` includes the application's scheme and host, and `<server>` is the
+Keycloak server (including any deployment prefix). Discovery is exactly
+`<server>/realms/<realm>/.well-known/openid-configuration` when `<server>` already
+includes the scheme. Use HTTPS outside development.
+
+Set these **DB settings** under the `oidc` namespace, using Settings → OIDC when
+the Settings UI is enabled:
+
+```json
+{
+  "role_mapping": {"admin": "admin", "user": "user"}
+}
+```
+
+Choose external roles and app roles appropriate for your host. `role_mapping`
+produces application roles; permission grants still come from the framework's
+permission registry. No mapping grants `tenant:*` roles. Visit `/oidc/login` to
+start sign-in. Cached identity is `(issuer, sub)` with a stable framework UUID.
+
+## Native Microsoft Entra ID
+
+Set the `entra` preset and your single-tenant registration details:
+
+```bash
+SM_AUTH_PROVIDER=oidc
+SM_OIDC_PROVIDER=entra
+SM_OIDC_TENANT_ID=<your-tenant-guid>
+SM_OIDC_CLIENT_ID=<app-registration-client-id>
+SM_OIDC_CLIENT_SECRET=<client-secret>
+```
+
+In the Entra app registration, add the redirect URI:
+
+```
+https://<your-host>/api/oidc/auth/callback
+```
+
+The `entra` preset derives the discovery URL
+(`https://login.microsoftonline.com/{tenant_id}/v2.0/.well-known/openid-configuration`),
+validates the **id_token**, keys the user cache on **(issuer, `oid`)**, and
+maps Entra **app roles** (the `roles` claim) to application roles via
+`role_mapping` (default: `admin` and `user` map 1:1). Assign app roles in
+*Entra → App registrations → App roles* and *Enterprise applications → Users and groups*.
+
+## Any other OIDC provider
+
+Use the `generic` preset with an explicit discovery URL:
+
+```bash
+SM_AUTH_PROVIDER=oidc
+SM_OIDC_PROVIDER=generic
+SM_OIDC_DISCOVERY_URL=https://<issuer>/.well-known/openid-configuration
+SM_OIDC_CLIENT_ID=<client-id>
+SM_OIDC_CLIENT_SECRET=<client-secret>
+```
+
+## Configuration reference
+
+| Env var | Default | Notes |
+|---|---|---|
+| `SM_OIDC_PROVIDER` | `generic` | Preset name (`entra`, `generic`). |
+| `SM_OIDC_DISCOVERY_URL` | — | Explicit discovery URL; wins over the preset. |
+| `SM_OIDC_TENANT_ID` | — | Used by templated presets (Entra) to derive the discovery URL. |
+| `SM_OIDC_CLIENT_ID` | — | OAuth client id. |
+| `SM_OIDC_CLIENT_SECRET` | — | OAuth client secret. |
+| `SM_OIDC_ROLES_CLAIM_PATH` | preset | Seeds `roles_claim_path`, so the first admin can sign in before the Settings UI is reachable. |
+
+Only the six environment variables above bootstrap process wiring, secrets and the first admin's roles path.
+These variables seed defaults; explicit DB values can override them.
+All other settings are DB-backed; bare environment names and the old claim
+mapping environment variables are ignored. Provider, discovery, tenant, client
+credentials and JWKS cache TTL changes require a restart. Claim and role mapping
+and tenant-claim trust read the live settings state.
+
+| DB setting | Default | Behaviour |
+|---|---|---|
+| `api_audience` | empty | Bearer authentication disabled until configured; ID tokens always use `client_id`. |
+| `api_allowed_client_ids` | empty | Clients besides `client_id` whose API tokens (`azp`, or `appid` on Entra v1) are accepted; a token naming no client is refused. |
+| `trust_tenant_claim` | false | Opt in only to a trusted, validated `tenant_id` claim. Entra `tid` never selects an application tenant. Membership resolution stays authoritative. |
+| `scope` | preset | Entra requests `openid email profile offline_access`. |
+| `uid_claim` | `oid` for Entra, otherwise `sub` | Required identity claim; there is no fallback. Identities use unique (issuer, subject) UUID mappings. |
+| `username_claim` / `name_claim` | `preferred_username` / `name` | Display name with fallback. |
+| `email_claim` | `email` | Display email; only generic OIDC literal `email_verified=true` attests ownership. Entra never attests it. |
+| `roles_claim_path` | `roles` for Entra, otherwise empty | Dotted claim path to role list. |
+| `role_mapping` | admin/user map to themselves | External roles to application roles; `tenant:*` roles are filtered on login and restored sessions. |
+| `login_redirect_url` | `/dashboard/` | Blank values normalize to the default. Saved deep links must be local paths. |
+| `jwks_cache_ttl_seconds` | 3600 | Last-good signing keys retained on outage; unknown keys share a 30-second fetch cooldown. |
+
+## Login, sessions and logout
+
+Entra supports a single tenant GUID. `common`, `organizations` and `consumers`
+are rejected. Unknown presets are validation errors. Discovery requires an issuer
+matching the configured discovery URL and HTTPS outside development; different
+endpoint hosts are supported. Discovery failure refuses boot outside development;
+development retries lazily on login.
+
+Authorization uses code flow with S256 PKCE, state and constant-time nonce
+validation. JWTs require `iss`, `sub`, `aud`, `exp` and `iat`, RS256 and the
+expected audience. Additional audiences are rejected, and a supplied `azp` on a browser ID token must name this client (required with multiple
+audiences); an API access token's `azp` is the calling client, checked against `api_allowed_client_ids` instead. The returned access token is unused, so `at_hash` is intentionally
+not checked.
+
+Sign-in replaces user-bound session state and rotates CSRF. The cookie never
+stores the ID token; it stores the ID-token expiry and an encrypted refresh token
+when supplied. Expired or unbounded sessions renew using a fresh ID token, with
+the same issuer and configured subject required. Definitive refresh rejection
+clears authentication. Providers that do not return an `id_token` on refresh
+sign the user out at expiry. Transport failures, 5xx and retryable 4xx preserve the
+expired session for another attempt, while this request stays unauthenticated;
+the token endpoint is not called again for 30 seconds, so a flapping IdP does not
+stall every request. A refresh token too large for the 4 KB session cookie (Entra
+can issue such tokens) is not stored, and that session ends at ID-token expiry.
+
+Logout best-effort revokes the refresh token when discovery advertises a
+`revocation_endpoint`, then always clears local state. The optional discovered logout endpoint gets
+`client_id` and `post_logout_redirect_uri`, without `id_token_hint`. Register
+`https://<your-host>/oidc/logged-out` as the post-logout URI. Providers requiring
+an ID-token hint may show a confirmation prompt or leave their SSO session active;
+the local signed-out page never automatically signs in.
+
+The host migration `c9d2e4f6a810` (`oidc@head`, #192) creates the identity cache.
+Apply host migrations with `upgrade heads` before deployment.
+
+## Activation
+
+Add `simple_module_oidc` to the host's `pyproject.toml` dependencies and
+`[tool.uv.sources]`, remove the competing provider, then `uv sync --all-packages`.
+Alternatively scope active modules with `SM_MODULES_ENABLED`.
+
+See [the full configuration reference](../../docs/modules/oidc.md)
+for every setting, its environment support, tenancy policy and deployment limits.

simple_module_oidc-0.0.43/oidc/__init__.py

@@ -0,0 +1 @@
+"""Generic OIDC authentication provider for simple_module (Entra, Auth0, Okta, ...)."""

simple_module_oidc-0.0.43/oidc/client.py

@@ -0,0 +1,138 @@
+"""OIDC client -- authorization URL, code exchange, and logout.
+
+Endpoint-driven: the authorize/token/end-session URLs come from the discovery
+document, so this client is provider-agnostic.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import secrets
+from typing import Any
+from urllib.parse import quote_plus, urlencode
+
+import httpx
+from auth.oidc_common.session import pkce_challenge
+
+# Revocation runs inside the logout request: a hung IdP must not hold it long.
+_REVOKE_TIMEOUT_SECONDS = 3
+
+
+class OIDCClient:
+    """Thin wrapper around a provider's discovered OIDC endpoints."""
+
+    def __init__(
+        self,
+        *,
+        authorization_endpoint: str,
+        token_endpoint: str,
+        end_session_endpoint: str,
+        client_id: str,
+        client_secret: str,
+        revocation_endpoint: str = "",
+        token_endpoint_auth_methods_supported: list[str] | None = None,
+        revocation_endpoint_auth_methods_supported: list[str] | None = None,
+    ) -> None:
+        self._authorization_endpoint = authorization_endpoint
+        self._token_endpoint = token_endpoint
+        self._end_session_endpoint = end_session_endpoint
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._revocation_endpoint = revocation_endpoint
+        self._token_endpoint_auth_methods_supported = token_endpoint_auth_methods_supported
+        # The revocation endpoint advertises its own methods; fall back to the token endpoint's.
+        self._revocation_endpoint_auth_methods_supported = (
+            revocation_endpoint_auth_methods_supported
+            if revocation_endpoint_auth_methods_supported is not None
+            else token_endpoint_auth_methods_supported
+        )
+
+    def build_authorization_url(
+        self,
+        redirect_uri: str,
+        nonce: str,
+        scope: str = "openid email profile",
+        *,
+        code_verifier: str,
+    ) -> tuple[str, str]:
+        state = secrets.token_urlsafe(32)
+        params = {
+            "client_id": self._client_id,
+            "redirect_uri": redirect_uri,
+            "response_type": "code",
+            "scope": scope,
+            "state": state,
+            "nonce": nonce,
+            "code_challenge_method": "S256",
+            "code_challenge": pkce_challenge(code_verifier),
+        }
+        separator = "&" if "?" in self._authorization_endpoint else "?"
+        url = f"{self._authorization_endpoint}{separator}{urlencode(params)}"
+        return url, state
+
+    async def exchange_code(
+        self, code: str, redirect_uri: str, *, code_verifier: str
+    ) -> dict[str, Any]:
+        return await self._token_request(
+            grant_type="authorization_code",
+            code=code,
+            code_verifier=code_verifier,
+            redirect_uri=redirect_uri,
+        )
+
+    def build_logout_url(
+        self,
+        post_logout_redirect_uri: str,
+    ) -> str:
+        """End-session URL. Falls back to the local redirect if the provider
+        does not advertise an ``end_session_endpoint``."""
+        if not self._end_session_endpoint:
+            return post_logout_redirect_uri
+        params = {
+            "post_logout_redirect_uri": post_logout_redirect_uri,
+            "client_id": self._client_id,
+        }
+        separator = "&" if "?" in self._end_session_endpoint else "?"
+        return f"{self._end_session_endpoint}{separator}{urlencode(params)}"
+
+    async def refresh_tokens(self, refresh_token: str) -> dict[str, Any]:
+        return await self._token_request(grant_type="refresh_token", refresh_token=refresh_token)
+
+    async def revoke_refresh_token(self, refresh_token: str) -> None:
+        if self._revocation_endpoint:
+            # httpx timeouts are per phase; bound the whole exchange too.
+            async with asyncio.timeout(_REVOKE_TIMEOUT_SECONDS):
+                await self._post(
+                    self._revocation_endpoint,
+                    self._revocation_endpoint_auth_methods_supported,
+                    {"token": refresh_token, "token_type_hint": "refresh_token"},
+                    timeout=_REVOKE_TIMEOUT_SECONDS,
+                )
+
+    async def _token_request(self, **grant: str) -> dict[str, Any]:
+        resp = await self._post(
+            self._token_endpoint, self._token_endpoint_auth_methods_supported, dict(grant)
+        )
+        return resp.json()
+
+    async def _post(
+        self,
+        endpoint: str,
+        methods: list[str] | None,
+        fields: dict[str, str],
+        *,
+        timeout: float = 10,
+    ) -> httpx.Response:
+        data = dict(fields)
+        extra: dict[str, Any] = {}
+        if methods is None or "client_secret_post" in methods:
+            data.update(client_id=self._client_id, client_secret=self._client_secret)
+        else:
+            # RFC 6749 requires form-encoding each credential before HTTP Basic encoding.
+            extra["auth"] = httpx.BasicAuth(
+                quote_plus(self._client_id), quote_plus(self._client_secret)
+            )
+        async with httpx.AsyncClient() as client:
+            resp = await client.post(endpoint, data=data, timeout=timeout, **extra)
+            resp.raise_for_status()
+            return resp

simple_module_oidc-0.0.43/oidc/constants.py

@@ -0,0 +1,19 @@
+"""OIDC routes, page names and session keys."""
+
+_MODULE_AUTH = "Auth"
+_MODULE_SETTINGS = "Settings"
+_PAGE_LOGIN = "Oidc/Login"
+_PAGE_LOGGED_OUT = "Oidc/LoggedOut"
+LOGIN_PATH = "/oidc/login"
+LOGOUT_PATH = "/oidc/logout"
+LOGGED_OUT_PATH = "/oidc/logged-out"
+AUTH_LOGIN_PATH = "/api/oidc/auth/login"
+AUTH_CALLBACK_PATH = "/api/oidc/auth/callback"
+SESSION_STATE_KEY = "oidc_state"
+SESSION_NONCE_KEY = "oidc_nonce"
+SESSION_VERIFIER_KEY = "oidc_pkce_verifier"
+SESSION_USER_KEY = "user_ctx"
+SESSION_IDENTITY_KEY = "oidc_identity"
+SESSION_REFRESH_TOKEN_KEY = "oidc_refresh_token"
+SESSION_REFRESH_RETRY_AT_KEY = "oidc_refresh_retry_at"
+DEFAULT_LOGIN_REDIRECT_URL = "/dashboard/"

simple_module_oidc-0.0.43/oidc/contracts/__init__.py

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

simple_module_oidc-0.0.43/oidc/directory.py

@@ -0,0 +1,10 @@
+"""User directory over the provider's unchanged cache table."""
+
+from auth.oidc_common.directory import CacheDirectory
+
+from oidc.models import OidcUserCache
+
+
+class OidcDirectory(CacheDirectory):
+    def __init__(self) -> None:
+        super().__init__(OidcUserCache)