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

simple_module_oidc-0.0.43.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,30 @@
+oidc/__init__.py,sha256=w6B07sNeXuaIBPzKZrEhOjyDI1jVkCo5GsUbX1EF-Qs,88
+oidc/client.py,sha256=wHuO4VYaoHLLKpnjImPQyVwub8nkjKZVtKkoy1_NRXg,5214
+oidc/constants.py,sha256=6zrwTZ-_3tkHRltvrHc1fSp5Gtx7NNkQ3seOxvOti7Y,671
+oidc/directory.py,sha256=2J3QNF_tfGkuxHUWbCggKw5_mRwhjIi8lGjCeHwssXw,269
+oidc/discovery.py,sha256=lMtbaRVT3-LBN81KWEcbLSUL9aPMCJLlxNDMhSysn1I,4253
+oidc/jwks.py,sha256=I70JweKu06N79PGm0pb-SwQ18RoOvn1fEU2sahR_F_w,128
+oidc/models.py,sha256=2xMsHJw1J4eAnjVVZZZES2af7vP62UaRQfvd56iaPjs,852
+oidc/module.py,sha256=T72xz0lJNLsHQj8AOjOPYHL2WQUqmuDRL9aSxzKiC1w,2710
+oidc/persistence.py,sha256=SFBOo099EJX4QrQhnARn5Ym430HSk0CwTqFYEUbOH6g,918
+oidc/presets.py,sha256=GIgBF94kNAD16h8l1CGzYnFwriKrXl4K7wGP1-M6J38,2220
+oidc/provider.py,sha256=JKZFS1Bg819QMgYP4N3wOdz6SDlvHXhLOAzykwiJFEU,7357
+oidc/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+oidc/renewal.py,sha256=zFjtGEi49IyMrkvO-fvpG61Io6KO6R7zNPj-IoJIvcI,2833
+oidc/runtime.py,sha256=omSdjYDeRMBCG8zLfl-SjJIyp-tFYmrI0uCwx7c3tIc,3136
+oidc/settings.py,sha256=vgvyiw9A6by4mym_cVy4ypYDeTiN5KSM35TWuYXZ_3k,5291
+oidc/state.py,sha256=-nAVX9TVbBBuq5vVwovAIL8ufl5s8_MvTPu28qW9cZU,686
+oidc/tokens.py,sha256=C6zHFtXpoyuCJzY5N0zUrUKN9k2Znslpa_9qHU7QCmQ,434
+oidc/contracts/__init__.py,sha256=1D6ZD67wkpLbG9lbdZUp-t8yinc0mvRMH4ITwh0g74A,29
+oidc/endpoints/__init__.py,sha256=ttqCgpzrvKYU5Mp3EyRmGbhbS17EHlVX4HTZ-8onKHM,29
+oidc/endpoints/api.py,sha256=_Org2zvY73RrkrzEtHJizLldqJ5mo7Z8-Pff7pP5D4k,4814
+oidc/endpoints/views.py,sha256=SvmT68dIiAjyrGZ_DheD_zjNQ9N22f71GdwuE78H82s,2300
+oidc/locales/de.json,sha256=nVJqlgY2-VmhlElK4ZYaRij2aosUZnKXaLcp4aqoCGk,334
+oidc/locales/en.json,sha256=HwSugraKfXwB5ZnHc3g1xSvw79GJkeDQWu3NkDLDc7c,311
+oidc/pages/LoggedOut.tsx,sha256=-f1uptDbo5Q5Vb3oronHcnSAEnaFyGY6Y4nuXNPEX2Y,545
+oidc/pages/Login.tsx,sha256=Hgba4KG3UZP2A3lYb990608FDOAEqFigFZMKoi869mo,579
+oidc/package.json,sha256=G9V3rxo23NdYnKUnDQwzWwZC1LYLx4OeulQlQNhTrdY,120
+simple_module_oidc-0.0.43.dist-info/METADATA,sha256=BdWNKHeavLqHuCV1NYl9jN9wHYgTcGTwkaedBdXEeXI,11314
+simple_module_oidc-0.0.43.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+simple_module_oidc-0.0.43.dist-info/entry_points.txt,sha256=eC-1TmZoIevuaaMN9SYIuXZiNMOvLPdU4Km-kh88jNA,46
+simple_module_oidc-0.0.43.dist-info/RECORD,,

simple_module_oidc-0.0.43.dist-info/WHEEL

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

simple_module_oidc-0.0.43.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[simple_module]
+oidc = oidc.module:OidcModule