feat(auth): OIDC logout-to-IdP — phase 3 (#798) (#865)

* feat(auth): OIDC logout-to-IdP — phase 3 (#798)

RP-initiated logout behind a new oidc_logout_from_idp setting: logging
out of PicPeak also ends the IdP session. The SSO callback stores the
raw ID token in an HttpOnly cookie (also the marker that the session
came in via SSO — local-password sessions never bounce to the IdP);
/logout builds the end_session URL from discovery metadata with
id_token_hint + post_logout_redirect_uri + client_id and returns it as
ssoLogoutUrl for the frontend to navigate to. Any failure (no
end_session_endpoint, IdP unreachable, feature off) degrades to the
plain local logout.

Settings surface exposes the toggle plus the computed post-logout
redirect URI to register at the IdP. Session timeouts deliberately stay
local-only.

6 integration tests over the mock IdP; live-verified against
Keycloak 26 (logout ends the Keycloak session, no confirmation prompt).

* fix(auth): harden the SSO logout marker cookie (#798 phase 3)

Codex review round 1:
- Derive the oidc_id_token cookie options from the shared cookie policy
  (COOKIE_SAMESITE / COOKIE_DOMAIN / secure resolution) — hardcoded Lax
  meant split-origin deployments running on SameSite=None never sent the
  marker to the cross-site /logout XHR, silently disabling logout-to-IdP.
- Oversized ID tokens (>3.9KB) now store a bare 'sso' marker instead of
  no cookie, so the claimed client_id-only end-session fallback actually
  happens; /logout only passes the value as id_token_hint when it is a
  real JWT.
- establishAdminSession clears any stale marker on every fresh login —
  sessions can die without /logout (deactivation, expiry, restore), and
  a surviving marker would bounce a later local-password session to the
  IdP. The SSO callback re-sets the marker for its own session.

Tests: oversized-token marker + hint-less end-session URL, stale-marker
cleared on local login; helper updated for the clear+set cookie pair.

* fix(auth): validate the logout hint against the current OIDC config (#798 phase 3)

Codex review round 2: an ID token stored at login can outlive an
issuer/client config change; sending it to the newly configured IdP as
id_token_hint strands the user on the IdP's error page (providers
validate iss/aud on the hint). buildEndSessionUrl now decodes the hint
(no verification — routing only): different issuer → skip the round-trip
entirely (the session belongs to another IdP); same issuer but changed
client → keep the round-trip, drop the unusable hint. Two tests pin both
paths.

---------

Co-authored-by: Paul Nothaft <[email protected]>

backend/src/routes/adminSettings.js

@@ -430,6 +430,7 @@ router.get('/sso', adminAuth, requirePermission('settings.view'), async (req, re
     // than failing the whole settings read; the login route refuses to start
     // the flow in that state anyway (OIDC_BAD_CONFIG).
     const redirectUri = await oidcService.getRedirectUri().catch(() => '');
+    const postLogoutRedirectUri = await oidcService.getPostLogoutRedirectUri().catch(() => '');
     res.json({
       oidc_enabled: cfg.enabled,
       oidc_issuer_url: cfg.issuerUrl || '',
@@ -444,7 +445,9 @@ router.get('/sso', adminAuth, requirePermission('settings.view'), async (req, re
       oidc_role_mappings: cfg.roleMappings,
       oidc_require_mapped_role: cfg.requireMappedRole,
       oidc_disable_local_login: cfg.disableLocalLogin,
+      oidc_logout_from_idp: cfg.logoutFromIdp,
       redirect_uri: redirectUri,
+      post_logout_redirect_uri: postLogoutRedirectUri,
     });
   } catch (error) {
     logger.error('Failed to read SSO settings', { error: error.message });
@@ -466,6 +469,7 @@ router.put('/sso', adminAuth, requirePermission('settings.edit'), [
   body('oidc_role_mappings').optional().isObject(),
   body('oidc_require_mapped_role').optional().isBoolean(),
   body('oidc_disable_local_login').optional().isBoolean(),
+  body('oidc_logout_from_idp').optional().isBoolean(),
 ], async (req, res) => {
   try {
     const errors = validationResult(req);

backend/src/routes/auth.js

@@ -25,6 +25,8 @@ const {
   clearGalleryAuthCookies,
   getAdminTokenFromRequest,
   getGalleryTokenFromRequest,
+  buildCookieOptionsWithExpiry,
+  buildClearCookieOptions,
 } = require('../utils/tokenUtils');
 const { getEventShareToken, resolveShareIdentifier } = require('../services/shareLinkService');
 const { getClientIp } = require('../utils/requestIp');
@@ -76,6 +78,13 @@ async function establishAdminSession(res, admin, ipAddress, userAgent, lockoutKe
 
   setAdminAuthCookie(res, token);
 
+  // A fresh login supersedes any SSO marker a previous session left behind
+  // (#798 phase 3): sessions can die without /logout (deactivation, expiry,
+  // restore), and a stale marker would bounce a subsequent local-password
+  // session to the IdP on logout. The SSO callback re-sets the marker for
+  // its own session right after this returns.
+  res.clearCookie(OIDC_ID_TOKEN_COOKIE, oidcIdTokenClearOptions());
+
   return {
     id: admin.id,
     username: admin.username,
@@ -335,7 +344,22 @@ router.post('/logout', async (req, res) => {
       clearGalleryAuthCookies(res);
     }
 
-    res.json({ message: 'Logged out successfully' });
+    // RP-initiated logout (#798 phase 3): when this browser session came in
+    // via SSO (marked by the oidc_id_token cookie set by the callback) and
+    // the feature is enabled, hand the frontend the IdP's end-session URL to
+    // navigate to after the local logout. Never blocks the local logout —
+    // buildEndSessionUrl returns null on any failure.
+    let ssoLogoutUrl = null;
+    const oidcIdToken = req.cookies?.[OIDC_ID_TOKEN_COOKIE];
+    if (oidcIdToken) {
+      res.clearCookie(OIDC_ID_TOKEN_COOKIE, oidcIdTokenClearOptions());
+      // The bare 'sso' marker (oversized ID token at login) still triggers
+      // the round-trip, just without an id_token_hint.
+      const hint = oidcIdToken.split('.').length === 3 ? oidcIdToken : undefined;
+      ssoLogoutUrl = await require('../services/oidcService').buildEndSessionUrl(hint);
+    }
+
+    res.json({ message: 'Logged out successfully', ...(ssoLogoutUrl ? { ssoLogoutUrl } : {}) });
   } catch (error) {
     errorResponse(res, error, 500, 'Logout failed');
   }
@@ -945,6 +969,27 @@ function oidcStateCookieOptions(req) {
   };
 }
 
+// Raw ID token of the SSO session, kept for RP-initiated logout (#798
+// phase 3): /logout sends it to the IdP as id_token_hint so the IdP ends
+// its session without a confirmation prompt. Its presence is also the
+// marker that THIS browser session came in via SSO — local-password
+// sessions must never be bounced to the IdP on logout. Path covers both
+// the callback (which sets it) and /api/auth/logout (which consumes it).
+// Options derive from the shared cookie policy (COOKIE_SAMESITE /
+// COOKIE_DOMAIN / secure resolution) — in split-origin deployments the
+// admin session runs on SameSite=None, and a hardcoded Lax here would
+// mean the cookie never reaches the cross-site /logout XHR, silently
+// disabling logout-to-IdP. The default maxAge matches the 24h admin JWT.
+const OIDC_ID_TOKEN_COOKIE = 'oidc_id_token';
+
+function oidcIdTokenCookieOptions(res) {
+  return { ...buildCookieOptionsWithExpiry(res), path: '/api/auth' };
+}
+
+function oidcIdTokenClearOptions() {
+  return { ...buildClearCookieOptions(), path: '/api/auth' };
+}
+
 // Kick off the IdP round-trip. 404 when SSO is off so the endpoint is
 // invisible on non-SSO installs.
 router.get('/admin/sso/login', async (req, res) => {
@@ -999,7 +1044,7 @@ router.get('/admin/sso/callback', async (req, res) => {
     const callbackUrl = new URL(await oidcService.getRedirectUri());
     callbackUrl.search = req.originalUrl.split('?')[1] || '';
 
-    const claims = await oidcService.handleCallback(callbackUrl.href, {
+    const { claims, idToken } = await oidcService.handleCallback(callbackUrl.href, {
       state: stash.s,
       nonce: stash.n,
       codeVerifier: stash.cv,
@@ -1018,6 +1063,16 @@ router.get('/admin/sso/callback', async (req, res) => {
     const userAgent = req.headers['user-agent'] || '';
     await establishAdminSession(res, admin, ipAddress, userAgent, admin.username);
 
+    // Cookie limit is 4KB — an oversized ID token (huge group lists) can't
+    // be stored, but the SSO-session marker must survive or logout-to-IdP
+    // silently turns off for exactly those users. Store the bare marker
+    // 'sso' instead; logout then sends the end-session request without an
+    // id_token_hint (costs one IdP confirmation click).
+    if (idToken) {
+      const cookieValue = idToken.length <= 3900 ? idToken : 'sso';
+      res.cookie(OIDC_ID_TOKEN_COOKIE, cookieValue, oidcIdTokenCookieOptions(res));
+    }
+
     await logActivity('admin_sso_login', { provider: 'oidc' }, null, {
       type: 'admin', id: admin.id, name: admin.username,
     });