- OIDC-owned accounts can never authenticate locally: the password
login rejects auth_provider='oidc' rows outright (generic 401), and
the super-admin password reset refuses them with a clear message —
previously a reset would have minted a local password bypassing the
IdP's MFA/access policies
- /auth/session now returns a full adminUser payload (role join) and
AdminAuthContext hydrates user state from it: an SSO redirect
establishes the session without any login JSON, which left the header
identity blank and current-admin form defaults empty
- the /sso/login error path redirects absolute to the frontend base
(same split-origin reasoning as the callback)
- docker-compose.yml passes API_URL through to the backend (production
compose uses env_file and needs nothing; dev compose is gitignored)
- authSession.symmetry test mock taught the joined admin lookup
(leftJoin, prefixed columns, aliases) — the route change made the old
mock throw, which read as "table missing, trust token"
Tests: new case pins that a known-good password on an OIDC-owned row
still gets 401. 14/14 OIDC, 13/13 symmetry.
Round 1:
- bind SSO identities to (external_issuer, external_subject): OIDC only
guarantees sub uniqueness within an issuer, so a sub-only lookup let a
newly configured IdP's user inherit an old IdP's admin account on
subject collision; migration 162 gains external_issuer + composite
unique index (unmerged migration, edited in place)
- fetch UserInfo (with sub cross-check) when the ID token carries no
email — spec-compliant providers may serve email/profile claims only
there; ID-token claims win on merge
- allowlist /admin/sso/login + /callback in maintenance mode, or
SSO-only (JIT) admins are locked out exactly when they need in
- strip reserved keys (oidc_client_secret, setup_token) from BOTH
generic settings reads (GET / and GET /:type)
Round 2:
- redirect_uri prefers API_URL (the API's public origin — where the
state cookie lives); final redirects absolute to the frontend base;
login button builds its URL via buildResourceUrl — split-origin
deployments (absolute VITE_API_URL) work end to end
- PUT /sso validates the MERGED resulting state (partial update cannot
blank issuer/client while enabled=true survives; enabling requires a
derivable redirect URI)
- openid scope forced into oidc_scopes on save
- discovery-cache key includes a secret fingerprint (multi-worker
secret rotation)
- email→admin linking claims the row atomically (conditional update on
external_subject IS NULL) — concurrent first-time callbacks with the
same verified email but different subjects can't both authenticate
Tests: mock IdP gains userinfo endpoint + email-via-userinfo-only mode;
new cases pin the userinfo merge and issuer-collision non-inheritance;
redirect assertions updated for absolute URLs. 13/13.
CI exposed that getFrontendBaseUrl() returns '' without FRONTEND_URL or
the general_site_url setting (local runs were masked by backend/.env):
the flow then sent a RELATIVE redirect_uri to the IdP, which surfaced
as an opaque IdP-side error. getRedirectUri now throws OIDC_BAD_CONFIG
with an actionable message (login route maps it to sso_error=config);
the settings GET degrades to an empty redirect_uri instead of 500ing.
The test pins FRONTEND_URL explicitly so it runs identically with and
without a local .env.
Authorization-code + PKCE against a single configurable IdP via
openid-client v5, with JIT provisioning. Verified end-to-end against a
real Keycloak 26 (realm + confidential client + verified-email user):
settings → discovery test → login button → Keycloak → dashboard.
Backend:
- migration 162: admin_users.auth_provider ('local' default) +
external_subject, composite unique index
- oidcService: settings-driven config (client secret AES-256-GCM at
rest, mfaService pattern, OIDC_ENCRYPTION_KEY fallback JWT_SECRET),
cached discovery, sub-based identity binding — email linking of
existing admins only with email_verified=true; JIT behind
oidc_autoprovision with configurable default role and an unusable
random password hash
- GET /api/auth/admin/sso/login + /callback: state/nonce/PKCE verifier
cross the redirect in a 10-min signed httpOnly SameSite=Lax cookie;
the callback reuses the local login's session establishment
(completeAdminLogin split into establishAdminSession + JSON wrapper)
so SSO sessions are identical downstream; every failure lands on
/admin/login?sso_error=<key> as a translated toast
- dedicated /admin/settings/sso GET/PUT/test endpoints (secret
write-only, redacted to a set-flag; registered ABOVE the generic
/:type matcher which would shadow them); oidc_client_secret added to
the reserved keys stripped from generic settings upserts
- public settings expose only oidc_enabled + oidc_button_label for the
login page
Frontend:
- Settings → Single Sign-On (OIDC) tab: issuer/client/secret, scopes,
autoprovision + default role, button label, enable toggle, redirect
URI copy box, server-side discovery test
- login page: SSO button (custom label) when enabled; sso_error query
param surfaced as translated toasts; EN+DE i18n
Tests: 11 integration cases against an in-process mock IdP (real
discovery/JWKS/PKCE/ID-token validation) — JIT on/off, sub-vs-email
binding, unverified-email rejection, deactivated admin, missing/forged
state cookie, nonce tamper, secret encryption round-trip, disabled 404.
MFA is delegated to the IdP on the SSO path; local login stays
available as break-glass. Role-claim mapping and logout-to-IdP follow
in phase 2/3.
Paul Nothaft