Keycloak-backed auth + tenant scoping + UI reconciliation — summary of changes

[KDwevedi]

Tracking issue summarizing the authentication/authorization work and the UI reconciliation landed on main (PRs #13–#17). Recorded here for reviewers and future contributors.

Added

• Backend auth module (pipeline/auth/): Keycloak OIDC JWT validation (RS256 against realm JWKS, iss + audience docs-pipeline-api, exp required, clock-skew leeway). Realm/resource roles → a Permission enum; instances / envs token claims for multi-tenant scoping. FastAPI dependency aliases (RequireUpload/Review/Pipeline/Search/Admin/ManageUsers, CurrentUser).
• Role → permission model: master_admin/admin = all (instance-unrestricted); content_curator = upload/review/pipeline/search; viewer = search.
• Keycloak in the stack: keycloak + keycloak-db services in docker-compose.yml (:8082, relative path /auth), realm-import mount, and scripts/keycloak_bootstrap_docs_pipeline.py (idempotent role/client/mapper/user bootstrap).
• Frontend OIDC: keycloak-js Authorization-Code + PKCE login, AuthProvider/useAuth, silent SSO + token refresh, Bearer injection on all API calls, ?access_token= for element (PDF/embed) loads, and permission-gated nav/actions.
• .env.example auth block and a README "Authentication (Keycloak)" deployment section.

Changed / hardened

• Every route now gated — all previously-open read/introspection endpoints require auth; only GET /health is public. A guardrail test asserts every route is gated or on an explicit public allowlist.
• Tenant scoping: document-scoped reads/mutations enforce instance access and return 404 (not 403) on cross-tenant access to avoid leaking other tenants' IDs.
• Admins are instance-unrestricted even with a scoped instances claim.
• Marqo tenant-scoping is forward-ready and tolerant: stamps instance on ingest and filters searches when the field exists, but never recreates or errors on a legacy index (single-tenant deploys keep working unchanged).
• Backward compatible: AUTH_DISABLED=true (default) accepts a synthetic local admin, so existing/local deploys work with no login; auth is opt-in via config only.

Removed

• Rough UI lineage files replaced by the polished operator-console UI (PR Restore polished maintainer UI (keep box styling) + keep OIDC auth #17): dropped ui/src/styles/appStyles.js and ui/src/markdown.css in favor of the themed component set.
• Dead branches deleted after merge: feature/auth-backend-gates, feature/domain-tags-pr, bh-main.

Anonymization (public-repo hygiene)

• Generic placeholders throughout: realm/client names, *.example.com domains, generic storage paths, and neutral tenant sample values in tests/bootstrap/docs. No secrets are committed (public/bearer-only clients; credentials come from the environment at runtime).

PRs

• Add Keycloak-backed auth scaffolding with tenant scoping #13 auth scaffolding · Anonymise Keycloak auth for the public repo (stacked on #13) #14 anonymization · Complete backend auth: gate all read routes, tenant-scope, admin-unrestricted, Marqo scoping #15 full backend gating + admin-unrestricted + Marqo scoping + ?access_token= · Wire Keycloak OIDC (PKCE) login + Bearer auth into the maintainer UI #16 UI OIDC · Restore polished maintainer UI (keep box styling) + keep OIDC auth #17 restore polished UI + keep auth.

Follow-ups

• manage_users master-admin user-management APIs.
• Dev/prod per-document enablement matrix.
• Seed the bootstrap script with example role fixtures.
• Multi-tenant Marqo index migration (only needed when >1 tenant).

🤖 Generated with Claude Code

[nexus69420]

Tracking summary for auth PRs #13–#17, which are on main. Follow-ups listed here live elsewhere: query enablement #56/#145, fingerprint dedup #43/#143, Keycloak manage_users leftover on #50. Closing the summary ticket so it is not treated as open work.