feat: OpenID Connect (OIDC) SSO + per-bucket access management (#21)

* feat: OpenID Connect SSO + per-bucket access management (#9)

Generic OIDC client for any compliant provider (Keycloak, Authentik, Okta,
Auth0, Entra ID, Google, Dex). Auto-discovers endpoints, fully validates the
ID token (JWKS signature, iss/aud/exp/azp, nonce), and protects the flow with
state + nonce + PKCE (S256); works as a confidential or public client. Per
issue #9, only the username is synced — new users are viewers with no access
until an admin grants it.

- Optional group->role mapping (OIDC_ADMIN_GROUP / OIDC_GROUPS_CLAIM),
  verified-email and email-domain restrictions, and RP-initiated single
  logout — all opt-in, off by default.
- Per-bucket access UI: auth-source badges (Local / SSO / LDAP / OAuth), a
  bucket-grant count, and a Manage-access editor (Read / Write / No Access,
  with search and bulk grant/revoke).
- Security: federated logins (OIDC/OAuth/LDAP) go through one hardened sync
  path. An auth_source is tracked per user (with a backfill migration),
  blocking account takeover — a federated login can no longer sign in as a
  username already owned by a different source (notably the local admin).
- Docs: .env.example, Helm values/deployment/secrets, README, CHANGELOG,
  docs/SSO.md, and website SSO / env-vars / user-management / changelog pages.

Validated: 62 backend tests (incl. takeover, azp, group-match, nonce); live
browser e2e across Keycloak, Dex, and Authentik plus the full user-management
UI (18 Playwright checks); Google validated against real discovery + JWKS.

* chore: release 3.6.0

Bump app version to 3.6.0 (Helm chart 1.4.0) and finalize the OIDC SSO +
per-bucket access management changelog entry.

Author: ashwathstephen

.env.example

@@ -28,14 +28,37 @@ DB_DIR=/data                 # Directory for SQLite databases
 # LDAP_ADMIN_GROUP=CN=Admins,OU=Groups,DC=example,DC=com
 # LDAP_DEFAULT_ROLE=viewer
 
-# OAuth / OIDC (optional)
+# OAuth — built-in Google / GitHub (optional)
 # OAUTH_GOOGLE_CLIENT_ID=
 # OAUTH_GOOGLE_CLIENT_SECRET=
 # OAUTH_GITHUB_CLIENT_ID=
 # OAUTH_GITHUB_CLIENT_SECRET=
 # OAUTH_DEFAULT_ROLE=viewer
 # OAUTH_ALLOWED_DOMAINS=example.com
 
+# OIDC — generic OpenID Connect SSO (Keycloak, Okta, Auth0, Entra ID, Authentik, …)
+# Enabled when OIDC_ISSUER and OIDC_CLIENT_ID are both set. Endpoints are
+# auto-discovered from <issuer>/.well-known/openid-configuration; the ID token is
+# validated (JWKS signature + iss/aud/exp) before any claim is trusted.
+# Only the username is synced — a new user lands as OIDC_DEFAULT_ROLE (viewer)
+# with no bucket access, and an admin assigns permissions.
+# Register this redirect URI with your provider: https://<your-host>/api/auth/oidc/callback
+# OIDC_ISSUER=https://login.example.com/realms/main
+# OIDC_CLIENT_ID=
+# OIDC_CLIENT_SECRET=
+# OIDC_PROVIDER_NAME=SSO                  # label on the login button
+# OIDC_USERNAME_CLAIM=preferred_username  # claim used as the local username
+# OIDC_SCOPES=openid profile email
+# OIDC_DEFAULT_ROLE=viewer
+# OIDC_ALLOWED_DOMAINS=example.com        # optional email-domain allowlist
+# Optional group→role mapping (off by default = username-only; admins assign access).
+# When OIDC_ADMIN_GROUP is set, membership maps to admin and re-syncs each login.
+# OIDC_ADMIN_GROUP=sairo-admins           # group whose members become admins
+# OIDC_GROUPS_CLAIM=groups                # claim containing the user's groups
+# Optional hardening:
+# OIDC_REQUIRE_VERIFIED_EMAIL=false       # reject logins whose email isn't verified
+# OIDC_RP_LOGOUT=false                    # also end the IdP session on logout (single logout)
+
 # White-labeling (optional)
 # APP_NAME=Sairo
 # PRIMARY_COLOR=#3b82f6

.gitignore

@@ -5,6 +5,7 @@ node_modules/
 frontend/dist/
 website/dist/
 website/.astro/
+backend/static/
 
 # Python
 __pycache__/

CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to Sairo are documented here. This project uses [Semantic Versioning](https://semver.org/).
 
+## [3.6.0] - 2026-06-29
+
+Generic OpenID Connect SSO + a real per-bucket access UI (issue #9).
+
+### Added
+
+- **OpenID Connect (OIDC) SSO** — a standards-compliant client for any provider (Keycloak, Authentik, Okta, Auth0, Entra ID, Google, Dex, …). Endpoints are auto-discovered from `<issuer>/.well-known/openid-configuration`; every ID token is fully validated (JWKS signature, `iss`/`aud`/`exp`/`azp`, nonce) and the flow is protected with **state + nonce + PKCE (S256)**. Per issue #9, **only the username is synced** — new users are viewers with no access until an admin grants it. Configured entirely via `OIDC_*` env vars; works with a confidential **or** public (secretless) client. Tested end-to-end against Keycloak, Authentik, and Dex. See [docs/SSO.md](docs/SSO.md).
+- **Optional OIDC group→role mapping** (`OIDC_ADMIN_GROUP` / `OIDC_GROUPS_CLAIM`) — off by default; when enabled, admin-group membership maps to the admin role and re-syncs each login. Matching is exact / path-segment / DN — never a loose substring.
+- **Optional hardening toggles** — `OIDC_REQUIRE_VERIFIED_EMAIL`, `OIDC_ALLOWED_DOMAINS`, and RP-initiated single logout (`OIDC_RP_LOGOUT`).
+- **Per-bucket access management UI** — Users now shows an auth-source badge (Local / SSO / LDAP / OAuth) and a bucket-grant count; "Manage access" opens a Read / Write / No-Access editor with search and bulk grant/revoke. (The backend permission API already existed; this makes it usable.)
+- Friendly login-page error messages for SSO failures.
+
+### Changed
+
+- **`auth_source` is now tracked per user** (with a backfill migration). All federated logins — OIDC, OAuth, and LDAP — go through one hardened sync path.
+
+### Security
+
+- Closed an **account-takeover** vector: a federated (OIDC/OAuth/LDAP) login can no longer sign in as a username already owned by a different auth source — notably the local admin.
+
 ## [3.5.0] - 2026-06-27
 
 Anonymous telemetry schema v2 — richer, still privacy-first.

README.md

@@ -42,7 +42,7 @@ Works with **AWS S3**, **MinIO**, **Ceph**, **Wasabi**, **Cloudflare R2**, **Bac
 - **User Management** — Role-based access control (admin / viewer) with per-bucket permissions
 - **S3-Key Auth** — Optional `AUTH_MODE=s3`: users log in with their own S3 keys and see only the buckets their provider IAM allows — access is delegated entirely to the provider
 - **Two-Factor Auth** — TOTP-based 2FA with QR setup and recovery codes
-- **OAuth & LDAP** — Google, GitHub OAuth and LDAP authentication
+- **SSO — OAuth, OIDC & LDAP** — Google/GitHub OAuth, generic OpenID Connect (Keycloak, Okta, Auth0, Entra ID, Google, Authentik, Dex, …) with auto-discovery + full ID-token validation (PKCE, nonce, JWKS), and LDAP. OIDC syncs the username only; admins assign per-bucket access. **Setup guide: [docs/SSO.md](docs/SSO.md)**
 - **AI-Powered Analysis (MCP)** — Connect Claude, Cursor, or any MCP client to ask natural language questions about your storage. 26 tools for analytics, cost optimization, pipeline health, and more
 - **Petabyte-Scale Performance** — Proven on a live 269 TB / 15.5M-object deployment. Constant-time folder listing at any scale via pre-computed prefix hierarchies, 64MB SQLite page cache, 256MB memory-mapped I/O, async FTS rebuilds
 - **Anonymous Telemetry (opt-out)** — A privacy-first heartbeat reports aggregate counts, instance health, and activation timestamps only (never names, keys, paths, or content). Disable with `TELEMETRY=false`
@@ -122,7 +122,7 @@ Validated read-only against a live production deployment (Leaseweb S3-compatible
 | Upload | Direct browser→S3 multipart, up to 5 TB/object, **flat server memory** |
 | Crawl throughput | 16 parallel prefix workers, 10K batch inserts, adaptive delta crawl |
 
-**Scaling:** Folder navigation is a constant-time index lookup, so it stays instant at any dataset size. See [Benchmarks](https://docs.sairo.dev/reference/benchmarks/) for the full methodology and server-compute microbenchmarks.
+**Scaling:** Folder navigation is a constant-time index lookup, so it stays instant at any dataset size. See [benchmark results](benchmark/results/LATEST-RESULTS.md) for the full methodology and server-compute microbenchmarks.
 
 ## Environment Variables
 
@@ -145,7 +145,7 @@ Validated read-only against a live production deployment (Leaseweb S3-compatible
 | `TELEMETRY` | `true` | Anonymous usage heartbeat (aggregate counts + health only). Set `false` to disable |
 | `TELEMETRY_INTERVAL` | `3600` | Seconds between telemetry heartbeats |
 
-> This is a summary. See the [full environment-variable reference](https://docs.sairo.dev/reference/environment-variables/) for delta-crawl tuning, uploads, LDAP/OAuth, branding, and rate limiting.
+> This is a summary; see **[.env.example](.env.example)** for the full annotated environment-variable reference (delta-crawl tuning, uploads, LDAP/OAuth, branding, rate limiting). For single sign-on (OIDC / OAuth / LDAP) setup with per-provider examples, see **[docs/SSO.md](docs/SSO.md)**.
 
 ## Tech Stack