feat: enforce IPSIE session_expiry ceiling on local session lifetime

Author: yogeshchoudhary147

EXAMPLES.md

@@ -18,6 +18,7 @@
 - [Native to Web SSO](#native-to-web-sso)
 - [Passkeys](#passkeys)
 - [MyAccount API](#myaccount-api)
+- [Session Expiry from Upstream IdP (IPSIE)](#session-expiry-from-upstream-idp-ipsie)
 
 ## Use with a Class Component
 
@@ -1616,3 +1617,81 @@ try {
   }
 }
 ```
+
+## Session Expiry from Upstream IdP (IPSIE)
+
+When using an Okta or OIDC enterprise connection configured with `id_token_session_expiry_supported: true`, Auth0 includes a `session_expiry` claim in the ID token. This is an absolute Unix timestamp (seconds) that acts as a hard ceiling on the local session — the SDK will not return tokens or a user once this point in time is reached.
+
+You can also emit the claim from a Post-Login Action:
+
+```js
+exports.onExecutePostLogin = async (event, api) => {
+  // Value must be Unix seconds, not milliseconds.
+  api.idToken.setCustomClaim('session_expiry', Math.floor(Date.now() / 1000) + 7200); // 2-hour ceiling
+};
+```
+
+### Behavior
+
+Enforcement is transparent — no code changes are required. When the ceiling is reached, `useAuth0()` reflects the expired state on the next render:
+
+- `isAuthenticated` becomes `false`
+- `user` becomes `undefined`
+- `getAccessTokenSilently()` returns `undefined` (no error thrown)
+
+Because this is identical to "no session", any route guard or `withAuthenticationRequired` wrapper already in your app will trigger re-authentication automatically.
+
+```jsx
+// This component already handles the session_expiry ceiling with no changes.
+// When the ceiling passes, isAuthenticated becomes false and the HOC redirects to login.
+export default withAuthenticationRequired(Dashboard);
+```
+
+### Reading the claim
+
+`session_expiry` is a standard ID token claim and is available via `getIdTokenClaims()`:
+
+```jsx
+import { useAuth0 } from '@auth0/auth0-react';
+
+function SessionInfo() {
+  const { getIdTokenClaims } = useAuth0();
+
+  useEffect(() => {
+    getIdTokenClaims().then((claims) => {
+      if (claims?.session_expiry) {
+        const ceiling = new Date(claims.session_expiry * 1000);
+        console.log('Session ceiling:', ceiling.toISOString());
+      }
+    });
+  }, [getIdTokenClaims]);
+
+  return null;
+}
+```
+
+### Upgrading existing apps
+
+Once the feature is enabled, `user` and `getAccessTokenSilently()` can return `undefined` for a previously authenticated user when the ceiling is reached. Apps that assume these are always set after login should add null checks:
+
+```jsx
+function CallApi() {
+  const { getAccessTokenSilently, loginWithRedirect } = useAuth0();
+
+  async function fetchData() {
+    const token = await getAccessTokenSilently();
+
+    if (!token) {
+      // Ceiling was reached — redirect to login.
+      await loginWithRedirect();
+      return;
+    }
+
+    await fetch('/api/data', { headers: { Authorization: `Bearer ${token}` } });
+  }
+
+  return <button onClick={fetchData}>Fetch</button>;
+}
+```
+
+Using `withAuthenticationRequired` on protected routes is the simpler alternative — the redirect happens automatically without the null check.

__tests__/auth-provider.test.tsx

@@ -1506,4 +1506,49 @@ describe('Auth0Provider', () => {
       });
     });
   });
+
+  describe('session_expiry ceiling (IPSIE SL1)', () => {
+    it('should be unauthenticated on init when session ceiling was breached', async () => {
+      // When the session_expiry ceiling is reached, auth0-spa-js tears down the local
+      // session inside checkSession and getUser returns undefined. The React layer
+      // should surface this as isAuthenticated: false with no error, so the existing
+      // redirect-to-login path fires transparently (Req 5).
+      clientMock.getUser.mockResolvedValue(undefined);
+      const wrapper = createWrapper();
+      const { result } = renderHook(() => useAuth0(), { wrapper });
+
+      await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+      expect(result.current.isAuthenticated).toBe(false);
+      expect(result.current.user).toBeUndefined();
+      expect(result.current.error).toBeUndefined();
+    });
+
+    it('should return undefined and clear auth state when session ceiling is breached during getAccessTokenSilently', async () => {
+      // Start with an authenticated session.
+      clientMock.getUser.mockResolvedValue({ sub: '__test_user__', name: 'Test User' });
+      const wrapper = createWrapper();
+      const { result } = renderHook(() => useAuth0(), { wrapper });
+
+      await waitFor(() => expect(result.current.isAuthenticated).toBe(true));
+
+      // auth0-spa-js signals a ceiling breach by returning undefined from
+      // getTokenSilently (no throw) and undefined from getUser (session cleared).
+      // The React layer must propagate this as a silent state transition to
+      // unauthenticated — not an error — so withAuthenticationRequired / route
+      // guards fire on their own without developer try/catch (Req 5).
+      (clientMock.getTokenSilently as jest.Mock).mockResolvedValue(undefined);
+      clientMock.getUser.mockResolvedValue(undefined);
+
+      let token: string | undefined;
+      await act(async () => {
+        token = await result.current.getAccessTokenSilently();
+      });
+
+      expect(token).toBeUndefined();
+      expect(result.current.isAuthenticated).toBe(false);
+      expect(result.current.user).toBeUndefined();
+      expect(result.current.error).toBeUndefined();
+    });
+  });
 });

package.json

@@ -93,6 +93,6 @@
     "react-dom": "^16.11.0 || ^17 || ^18 || ~19.0.1 || ~19.1.2 || ^19.2.1"
   },
   "dependencies": {
-    "@auth0/auth0-spa-js": "^2.21.2"
+    "@auth0/auth0-spa-js": "^2.22.0"
   }
 }