Add Keycloak authentication to smartem app

[vredchenko]

Summary

End-to-end Keycloak authentication for the smartem app:

• keycloak-js-based AuthProvider, useAuth() hook, automatic token-refresh scheduling
• Shared Axios interceptor in @smartem/api attaches Authorization: Bearer <token> to every API call when authenticated
• AuthGate hard-blocks the dashboard until Keycloak has confirmed authentication — unauthenticated visitors only see a sign-in screen, never the app contents
• Header swaps the prototyping RoleSwitcher for real auth controls (sign-in icon / account menu with sign-out)
• Disabled by default in dev/mock mode (VITE_AUTH_ENABLED=false or VITE_ENABLE_MOCKS=true), enabled in production builds

Closes #64. Supersedes #70.

Configuration

Defaults to the DLS test realm; apps/smartem/.env.example:

VITE_KEYCLOAK_URL=https://identity-test.diamond.ac.uk
VITE_KEYCLOAK_REALM=dls
VITE_KEYCLOAK_CLIENT_ID=SmartEM
VITE_AUTH_ENABLED=false

The in-code fallback in config.ts points at production (identity.diamond.ac.uk) so a build without env vars set doesn't silently point at the test realm. Helpdesk UASHD-4189 registered the SmartEM client against the dls realm on both identity.diamond.ac.uk and identity-test.diamond.ac.uk.

For local development without DLS identity access, see DiamondLightSource/smartem-devtools#198 — a self-contained Keycloak mock with the same realm/client/PKCE config.

Fixes that landed during E2E shakeout

While exercising the flow end-to-end against the local mock from #198, three issues surfaced and got fixed on this branch:

1. Silent SSO via hidden iframe (557edf6) — added silentCheckSsoRedirectUri + a public silent-check-sso.html that posts the parsed URL back to the parent. Without it, check-sso did a top-level redirect on every load.
2. Init-failure path no-op login (557edf6) — the catch handler was building Auth from defaultAuth, so auth.login() did nothing if init failed. Now built from the live keycloak instance.
3. 5-second redirect loop (6b02a4a) — keycloak-js defaults checkLoginIframe: true, polling Keycloak every 5s via a hidden iframe. Modern browsers block third-party cookies, so the iframe can never read Keycloak's session cookie; it reports "session changed" each tick, and keycloak-js translates that into a top-level redirect. The companion option silentCheckSsoFallback (default true) caused the initial check to fall back to a top-level redirect when the iframe couldn't see the session. Both disabled.
4. Hard auth gate (2ee26bd) — AuthGate previously rendered children regardless of auth state, so unauthenticated users saw the dashboard with a sign-in button in the corner. Now wraps children in an AuthBoundary that renders nothing while init is in flight, a centred sign-in screen when unauthenticated, and the app when authenticated. No-op when VITE_AUTH_ENABLED=false.

Scope

Frontend auth ceremony only. The SPA authenticates with Keycloak directly and attaches tokens to API requests. Backend validation is a separate change in DiamondLightSource/smartem-decisions (the JWT-validation PR is in flight).

Route-level RBAC and per-feature permission gating are deferred to a follow-up.

Test plan

• npm run dev:smartem:mock — app loads normally, no auth UI, mock data visible
• VITE_AUTH_ENABLED=true npm run dev:smartem against the local Keycloak mock — sign-in screen renders pre-login, full app renders after login
• Header shows sign-in icon pre-auth, account menu (with user identity) post-auth, sign-out returns to the sign-in screen
• No #error=login_required redirect loop on idle pages
• Bearer token is attached to outgoing API requests once authenticated
• npm run typecheck passes (CI green on every push)
• npm run build:smartem succeeds (CI green on every push)

[vredchenko]

https://jira.diamond.ac.uk/servicedesk/customer/portal/5/UASHD-4189

[vredchenko]

Review notes — local dev exercise of the auth flow

I took the branch for a spin against the DLS identity-test realm and then against a locally-run Keycloak. Three things came up that are worth addressing before this merges.

1. Bug: init failure permanently bricks the login button

In apps/smartem/src/auth/AuthProvider.tsx, the init error path spreads defaultAuth, whose login and logout are no-ops:

const defaultAuth: Auth = {
  initialised: false,
  authenticated: false,
  login: () => {},      // no-op
  logout: () => {},     // no-op
  getToken: () => '',
}

// …

keycloak
  .init({ onLoad: 'check-sso' })
  .then(() => setAuth(buildAuth(keycloak)))
  .catch((err) => {
    console.error('Keycloak init failed:', err)
    setAuth({ ...defaultAuth, initialised: true, error: 'Failed to connect to Keycloak' })
  })

The keycloak instance is alive in the closure with working .login() / .logout() methods, but the context never receives them. Any transient init failure — iframe blocked by CORS, network blip, Keycloak slow to respond, misconfigured Web Origins — leaves the user with a Sign in button that does nothing until they reload (and reload doesn't help if the failure is persistent).

I hit this against identity-test: the silent-SSO iframe returned 403 because http://localhost:5173 isn't in the SmartEM client's Web Origins. The catch ran, the button rendered, clicking it called the no-op login().

Suggested fix — use the live keycloak instance so login can still redirect:

.catch((err) => {
  console.error('Keycloak init failed:', err)
  setAuth({
    ...buildAuth(keycloak),
    initialised: true,
    error: 'Failed to connect to Keycloak',
  })
})

keycloak.login() does a full-page redirect and doesn't depend on the silent-SSO iframe, so it works even when the init handshake failed.

2. Design issue: onLoad: 'check-sso' without a silent-SSO HTML page

keycloak.init({ onLoad: 'check-sso' }) is called with no silentCheckSsoRedirectUri. Per the keycloak-js docs, this means the silent-SSO check falls back to a top-level redirect to Keycloak when the iframe approach isn't viable.

Combined with React.StrictMode (which double-mounts effects in dev), the result is a redirect storm: page → Keycloak /auth?… → page (with #error=login_required) → effect re-runs → page → Keycloak → page → … The app never gets a chance to render the header, so the user can't reach the Sign in button at all.

I observed this against the local Keycloak in this exercise — three full reload cycles in 5s, header never appears.

Suggested fix — add a static apps/smartem/public/silent-check-sso.html:

<!doctype html>
<html><body><script>
  parent.postMessage(location.href, location.origin)
</script></body></html>

and pass its URL in init:

keycloak.init({
  onLoad: 'check-sso',
  silentCheckSsoRedirectUri: `${window.location.origin}/silent-check-sso.html`,
  pkceMethod: 'S256',
})

This keeps the silent-SSO check inside an iframe (no top-level redirect), so the StrictMode double-mount is harmless. Worth also adding pkceMethod: 'S256' explicitly — the request currently uses it but only because the library defaults are kind.

3. Documentation gap: no local-dev setup

The README doesn't mention Keycloak. apps/smartem/.env.example points at identity-test.diamond.ac.uk, but the SmartEM client there doesn't have http://localhost:5173 in its Web Origins or Valid Redirect URIs, so out-of-the-box npm run dev:smartem fails immediately with a 403 on the silent-SSO iframe.

smartem-devtools/docs/architecture/keycloak-spa-authentication.md describes the design but predates this PR and refers to a smartem-frontend client; the implementation uses SmartEM. Worth aligning the names.

To unblock local dev I drafted a self-contained Keycloak mock in smartem-devtools/keycloak-mock/:

• docker-compose.yml — Keycloak 26 in start-dev --import-realm mode, port 8080
• realm/dls-realm.json — realm dls, public client SmartEM with PKCE, redirect URIs and Web Origins for localhost:5173 and :5174, a custom fedId claim mapper, two seeded users

Devs point VITE_KEYCLOAK_URL=http://localhost:8080 in .env.local, docker compose up -d, done.

This pairs with a one-line README section. Happy to fold it into this PR or land it as a follow-up.

Verifying the fixes

I patched issues 1 and 2 locally (reverted in current state) and ran the full flow against the local Keycloak mock: app loads → Sign in → redirect to localhost:8080/realms/dls/... → submit credentials → redirect back with auth code → tokens exchanged → header shows account menu with the logged-in user. End-to-end works once both fixes are applied.