frontend: Handle token expiry and add session expiry warning fixes #5112

prabindersinghh · prabindersinghh · commit 6ae57b701662 · 2026-05-04T23:12:33.000+05:30
Add a token-expiry notification banner so users are warned before their
session ends and automatically logged out when the token expires.

Root cause
----------
When a cluster uses a short-lived bearer token (e.g. a Kubernetes
TokenRequest token with expirationSeconds=600), neither the frontend nor
the backend provided any user-facing indication that the session was about
to end.  The only existing mechanism (OIDCTokenRefreshMiddleware) silently
refreshes tokens within 10 seconds of expiry for OIDC clusters, but gives
no signal to the client and does nothing for non-OIDC bearer tokens.

Changes
-------
backend/pkg/auth/auth.go
  - writeMeResponse now accepts a tokenExpiry time.Time and serialises it
    as a Unix timestamp under "tokenExpiry" in the 200 OK JSON body so the
    frontend can calculate time-to-expiry without reading httpOnly cookies.
  - HandleMe extracts the expiry value before the expired-token check so
    it can be forwarded to writeMeResponse.

backend/pkg/auth/auth_test.go
  - TestHandleMe_IncludesTokenExpiry: verifies that the tokenExpiry field
    in the 200 response equals the exp claim in the JWT.

frontend/src/lib/auth.ts
  - ClusterMeResponse interface documents the tokenExpiry field.
  - ClusterMeResult discriminated union cleanly separates "token expired"
    from "network error" from "success".
  - fetchClusterMe fetches /clusters/:cluster/me, maps 401 to
    tokenExpired:true, and wraps other errors as null data.

frontend/src/components/App/TokenExpiryNotification.tsx (new)
  - PureTokenExpiryNotification polls fetchClusterMeFn every 60 s
    (injectable for testing).
  - Shows a warning banner with a countdown when &lt;2 min remain.
  - Shows an error banner and calls logout() when the token has expired.
  - Suppressed on login/token/settings routes (same pattern as
    AlertNotification).

frontend/src/components/App/Layout.tsx
  - Mounts &lt;TokenExpiryNotification /&gt; alongside &lt;AlertNotification /&gt;.
diff --git a/backend/pkg/auth/auth.go b/backend/pkg/auth/auth.go
@@ -327,7 +327,8 @@ func HandleMe(opts MeHandlerOptions) http.HandlerFunc {
 			return
 		}
 
-		if expiry, err := GetExpiryUnixTimeUTC(claims); err != nil || time.Now().After(expiry) {
+		expiry, err := GetExpiryUnixTimeUTC(claims)
+		if err != nil || time.Now().After(expiry) {
 			writeMeJSON(w, http.StatusUnauthorized, map[string]interface{}{"message": "token expired"})
 			return
 		}
@@ -336,7 +337,7 @@ func HandleMe(opts MeHandlerOptions) http.HandlerFunc {
 		email := stringValueFromJMESPaths(claims, compiledEmailPaths)
 		groups := stringSliceFromJMESPaths(claims, compiledGroupsPaths)
 
-		writeMeResponse(w, username, email, groups, userInfoURL)
+		writeMeResponse(w, username, email, groups, userInfoURL, expiry)
 	}
 }
 
@@ -356,13 +357,21 @@ func parseClaimsFromToken(token string) (map[string]interface{}, int, string) {
 }
 
 // writeMeResponse serializes the identity payload with the standard cache-busting headers.
-func writeMeResponse(w http.ResponseWriter, username, email string, groups []string, userInfoURL string) {
-	writeMeJSON(w, http.StatusOK, map[string]interface{}{
+// tokenExpiry is the token's expiry time; if non-zero it is included so the frontend
+// can warn users before their session ends.
+func writeMeResponse(w http.ResponseWriter, username, email string, groups []string, userInfoURL string, tokenExpiry time.Time) {
+	payload := map[string]interface{}{
 		"username":    username,
 		"email":       email,
 		"groups":      groups,
 		"userInfoURL": userInfoURL,
-	})
+	}
+
+	if !tokenExpiry.IsZero() {
+		payload["tokenExpiry"] = tokenExpiry.Unix()
+	}
+
+	writeMeJSON(w, http.StatusOK, payload)
 }
 
 // writeMeJSON sets the standard cache-control headers used by /me responses and writes the JSON payload.
diff --git a/backend/pkg/auth/auth_test.go b/backend/pkg/auth/auth_test.go
@@ -1027,3 +1027,38 @@ func TestHandleMe_MissingCookie(t *testing.T) {
 	assert.Equal(t, "no-store, no-cache, must-revalidate, private", rr.Header().Get("Cache-Control"))
 	assert.Equal(t, "Cookie", rr.Header().Get("Vary"))
 }
+
+func TestHandleMe_IncludesTokenExpiry(t *testing.T) {
+	t.Parallel()
+
+	futureExpiry := time.Now().Add(time.Hour).Unix()
+	claims := map[string]interface{}{
+		"preferred_username": "alice",
+		"exp":                float64(futureExpiry),
+	}
+
+	token := makeTestToken(t, claims)
+
+	req := httptest.NewRequestWithContext(context.Background(), http.MethodGet, "/clusters/test/me", nil)
+	req = mux.SetURLVars(req, map[string]string{"clusterName": "test"})
+	req.Header.Set("Authorization", "Bearer "+token)
+
+	rr := httptest.NewRecorder()
+
+	handler := auth.HandleMe(auth.MeHandlerOptions{
+		UsernamePaths: "preferred_username",
+	})
+
+	handler(rr, req)
+
+	require.Equal(t, http.StatusOK, rr.Code)
+
+	var got struct {
+		Username    string `json:"username"`
+		TokenExpiry int64  `json:"tokenExpiry"`
+	}
+
+	require.NoError(t, json.Unmarshal(rr.Body.Bytes(), &got))
+	assert.Equal(t, "alice", got.Username)
+	assert.Equal(t, futureExpiry, got.TokenExpiry, "tokenExpiry should match the JWT exp claim as a Unix timestamp")
+}
diff --git a/frontend/src/components/App/Layout.tsx b/frontend/src/components/App/Layout.tsx
@@ -47,6 +47,7 @@ import DetailsDrawer from '../common/Resource/DetailsDrawer';
 import Sidebar, { NavigationTabs } from '../Sidebar';
 import RouteSwitcher from './RouteSwitcher';
 import ShortcutsSettings from './Settings/ShortcutsSettings';
+import TokenExpiryNotification from './TokenExpiryNotification';
 import TopBar from './TopBar';
 import VersionDialog from './VersionDialog';
 
@@ -334,6 +335,7 @@ export default function Layout({}: LayoutProps) {
                 <ClusterNotFoundPopup key={clusterName} cluster={clusterName} />
               ))}
               <AlertNotification />
+              <TokenExpiryNotification />
               <Box sx={{ height: '100%' }}>
                 <Div />
                 <Container {...containerProps} sx={{ height: '100%' }}>
diff --git a/frontend/src/components/App/TokenExpiryNotification.tsx b/frontend/src/components/App/TokenExpiryNotification.tsx
@@ -0,0 +1,228 @@
+/*
+ * Copyright 2025 The Kubernetes Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import Alert from '@mui/material/Alert';
+import Button from '@mui/material/Button';
+import Typography from '@mui/material/Typography';
+import React from 'react';
+import { useTranslation } from 'react-i18next';
+import { matchPath, useLocation } from 'react-router-dom';
+import { fetchClusterMe, logout } from '../../lib/auth';
+import type { ClusterMeResult } from '../../lib/auth';
+import { getCluster } from '../../lib/cluster';
+import { getRoute } from '../../lib/router/getRoute';
+import { getRoutePath } from '../../lib/router/getRoutePath';
+
+/** How often to poll the /clusters/:cluster/me endpoint (ms). */
+const POLL_INTERVAL_MS = 60 * 1000;
+
+/** Show a warning banner when fewer than this many seconds remain before expiry. */
+const WARNING_BEFORE_EXPIRY_SECONDS = 2 * 60;
+
+/** Routes where the banner is suppressed — these pages handle auth state themselves. */
+const ROUTES_WITHOUT_EXPIRY_CHECK = ['login', 'token', 'settingsCluster'];
+
+export interface PureTokenExpiryNotificationProps {
+  /** Injected fetch function so tests can control responses without hitting the network. */
+  fetchClusterMeFn: (cluster: string) => Promise<ClusterMeResult>;
+}
+
+/**
+ * Polls the Headlamp /clusters/:cluster/me endpoint and shows a banner when the
+ * session token is about to expire or has already expired.
+ *
+ * Exported as `PureTokenExpiryNotification` so it can be unit-tested with a
+ * mocked fetch function.
+ */
+export function PureTokenExpiryNotification({
+  fetchClusterMeFn,
+}: PureTokenExpiryNotificationProps) {
+  const { t } = useTranslation();
+  const { pathname } = useLocation();
+
+  const [tokenExpiry, setTokenExpiry] = React.useState<number | null>(null);
+  const [tokenExpired, setTokenExpired] = React.useState(false);
+
+  // Restart the poller whenever the route changes (covers cluster switches too).
+  React.useEffect(() => {
+    setTokenExpiry(null);
+    setTokenExpired(false);
+
+    const cluster = getCluster();
+    if (!cluster) {
+      return;
+    }
+
+    let mounted = true;
+
+    const check = async () => {
+      if (!mounted) return;
+      const result = await fetchClusterMeFn(cluster);
+      if (!mounted) return;
+
+      if (result.tokenExpired) {
+        setTokenExpired(true);
+      } else if (result.data?.tokenExpiry != null) {
+        setTokenExpiry(result.data.tokenExpiry);
+      }
+    };
+
+    // Run once immediately, then on the regular interval.
+    check();
+    const id = setInterval(check, POLL_INTERVAL_MS);
+
+    return () => {
+      mounted = false;
+      clearInterval(id);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [pathname]);
+
+  // Auto-logout as soon as the backend confirms the token is expired.
+  React.useEffect(() => {
+    if (!tokenExpired) return;
+    const cluster = getCluster();
+    if (cluster) {
+      logout(cluster);
+    }
+  }, [tokenExpired]);
+
+  const showOnRoute = React.useMemo(() => {
+    for (const routeName of ROUTES_WITHOUT_EXPIRY_CHECK) {
+      const maybeRoute = getRoute(routeName);
+      if (!maybeRoute) continue;
+      if (matchPath(pathname, getRoutePath(maybeRoute))?.isExact) return false;
+    }
+    return true;
+  }, [pathname]);
+
+  if (!showOnRoute || !getCluster()) {
+    return null;
+  }
+
+  if (tokenExpired) {
+    return (
+      <Alert
+        variant="filled"
+        severity="error"
+        sx={theme => ({
+          color: theme.palette.common.white,
+          background: theme.palette.error.main,
+          textAlign: 'center',
+          display: 'flex',
+          paddingTop: theme.spacing(0.5),
+          paddingBottom: theme.spacing(1),
+          paddingRight: theme.spacing(3),
+          justifyContent: 'center',
+          position: 'fixed',
+          zIndex: theme.zIndex.snackbar + 1,
+          top: '0',
+          alignItems: 'center',
+          left: '50%',
+          width: 'auto',
+          transform: 'translateX(-50%)',
+        })}
+      >
+        <Typography
+          variant="body2"
+          sx={theme => ({
+            paddingTop: theme.spacing(0.5),
+            fontWeight: 'bold',
+            fontSize: '16px',
+          })}
+        >
+          {t('translation|Session expired. Logging out…')}
+        </Typography>
+      </Alert>
+    );
+  }
+
+  const now = Math.floor(Date.now() / 1000);
+  const secondsLeft = tokenExpiry !== null ? tokenExpiry - now : null;
+  const isExpiring =
+    secondsLeft !== null && secondsLeft > 0 && secondsLeft <= WARNING_BEFORE_EXPIRY_SECONDS;
+
+  if (!isExpiring) {
+    return null;
+  }
+
+  const minutes = Math.floor(secondsLeft! / 60);
+  const seconds = secondsLeft! % 60;
+  const timeStr = `${minutes}:${String(seconds).padStart(2, '0')}`;
+
+  return (
+    <Alert
+      variant="filled"
+      severity="warning"
+      sx={theme => ({
+        color: theme.palette.common.white,
+        background: theme.palette.warning.main,
+        textAlign: 'center',
+        display: 'flex',
+        paddingTop: theme.spacing(0.5),
+        paddingBottom: theme.spacing(1),
+        paddingRight: theme.spacing(3),
+        justifyContent: 'center',
+        position: 'fixed',
+        zIndex: theme.zIndex.snackbar + 1,
+        top: '0',
+        alignItems: 'center',
+        left: '50%',
+        width: 'auto',
+        transform: 'translateX(-50%)',
+      })}
+      action={
+        <Button
+          size="small"
+          sx={theme => ({
+            color: theme.palette.warning.main,
+            borderColor: theme.palette.warning.main,
+            background: theme.palette.common.white,
+            lineHeight: theme.typography.body2.lineHeight,
+            '&:hover': {
+              color: theme.palette.common.white,
+              borderColor: theme.palette.common.white,
+              background: theme.palette.warning.dark,
+            },
+          })}
+          onClick={() => {
+            const cluster = getCluster();
+            if (cluster) {
+              logout(cluster);
+            }
+          }}
+        >
+          {t('translation|Log out')}
+        </Button>
+      }
+    >
+      <Typography
+        variant="body2"
+        sx={theme => ({
+          paddingTop: theme.spacing(0.5),
+          fontWeight: 'bold',
+          fontSize: '16px',
+        })}
+      >
+        {t('translation|Session expires in {{time}}', { time: timeStr })}
+      </Typography>
+    </Alert>
+  );
+}
+
+export default function TokenExpiryNotification() {
+  return <PureTokenExpiryNotification fetchClusterMeFn={fetchClusterMe} />;
+}
diff --git a/frontend/src/lib/auth.ts b/frontend/src/lib/auth.ts
@@ -21,6 +21,7 @@
 import { Base64 } from 'js-base64';
 import { getHeadlampAPIHeaders } from '../helpers/getHeadlampAPIHeaders';
 import store from '../redux/stores/store';
+import { ApiError } from './k8s/api/v2/ApiError';
 import { backendFetch } from './k8s/api/v2/fetch';
 import { queryClient } from './queryClient';
 
@@ -153,3 +154,50 @@ export function deleteTokens() {
   const clusters = Object.keys(store.getState().config.allClusters ?? {});
   return Promise.all(clusters.map(cluster => logout(cluster)));
 }
+
+/**
+ * Response from the /clusters/:cluster/me endpoint.
+ */
+export interface ClusterMeResponse {
+  username?: string;
+  email?: string;
+  groups?: string[];
+  userInfoURL?: string;
+  /** Unix timestamp (seconds) when the token expires. Present only when the backend
+   *  can parse an `exp` claim from the token (JWT-based auth). */
+  tokenExpiry?: number;
+}
+
+/**
+ * Result of a call to fetchClusterMe.
+ * `tokenExpired` is true when the backend returned 401 (token missing or expired).
+ * `data` is null when the request failed for any reason other than a 401.
+ */
+export type ClusterMeResult =
+  | { tokenExpired: false; data: ClusterMeResponse }
+  | { tokenExpired: true; data: null }
+  | { tokenExpired: false; data: null };
+
+/**
+ * Fetches identity and token-expiry information for the given cluster from the
+ * Headlamp backend's /clusters/:cluster/me endpoint.
+ *
+ * The backend validates the per-cluster cookie and returns 401 when the token
+ * is missing or has already expired — callers should treat that as a signal to
+ * log the user out.
+ *
+ * @param cluster - Name of the cluster.
+ * @returns A ClusterMeResult object.
+ */
+export async function fetchClusterMe(cluster: string): Promise<ClusterMeResult> {
+  try {
+    const response = await backendFetch(`/clusters/${cluster}/me`);
+    const data: ClusterMeResponse = await response.json();
+    return { tokenExpired: false, data };
+  } catch (e) {
+    if (e instanceof ApiError && e.status === 401) {
+      return { tokenExpired: true, data: null };
+    }
+    return { tokenExpired: false, data: null };
+  }
+}
