fix(nextjs): keep the organization claims when the essential ID token claims overflow the cookie

Adds a narrower fallback tier between "essential claims" and "no claims" so
that `getCurrentOrganization()` keeps working on every server instance unless
the cookie is within a hundred bytes or so of the browser limit. The session
stays cookie-only by design; there is no server-side store to fall back to.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Author: DonOmalVindula

.changeset/nextjs-cookie-backed-session.md

@@ -2,4 +2,4 @@
 '@asgardeo/nextjs': patch
 ---
 
-Organization switching, the current organization and the ID-token fallback of the user profile no longer depend on the in-memory session of the underlying Node client, which is empty after a server restart, on another serverless instance, or after the middleware refreshed the tokens in the Edge runtime. The claims of the ID token are now kept in the session cookie (single-use protocol claims such as `at_hash` and `nonce` are dropped), `getDecodedIdToken()` reads them from there, and the `organization_switch` exchange uses the access token from the cookie. When the claims would push the session cookie over the 4 KB browser limit, only the organization and basic identity claims are kept (or none, if even those do not fit) and a warning is logged.
+Organization switching, the current organization and the ID-token fallback of the user profile no longer depend on the in-memory session of the underlying Node client, which is empty after a server restart, on another serverless instance, or after the middleware refreshed the tokens in the Edge runtime. The claims of the ID token are now kept in the session cookie (single-use protocol claims such as `at_hash` and `nonce` are dropped), `getDecodedIdToken()` reads them from there, and the `organization_switch` exchange uses the access token from the cookie. When the claims would push the session cookie over the 4 KB browser limit, they are narrowed step by step (essential identity and organization claims, then the organization claims alone, then none) and a warning is logged.

packages/nextjs/src/utils/SessionManager.ts

@@ -204,16 +204,41 @@ class SessionManager {
     return this.MAX_COOKIE_BYTES - this.getSessionCookieName().length - this.COOKIE_ATTRIBUTES_HEADROOM_BYTES;
   }
 
+  /**
+   * The organization claims behind `getCurrentOrganization()`: the smallest claim set worth keeping
+   * when not even the essential claims fit into the session cookie.
+   */
+  private static readonly ORGANIZATION_ID_TOKEN_CLAIMS: string[] = [
+    'org_handle',
+    'org_id',
+    'org_name',
+    'sub',
+    'user_org',
+  ];
+
+  private static pickIdTokenClaims(
+    idTokenClaims: Record<string, unknown>,
+    claimNames: string[],
+  ): Record<string, unknown> {
+    return Object.fromEntries(
+      Object.entries(idTokenClaims).filter(([claim]: [string, unknown]) => claimNames.includes(claim)),
+    );
+  }
+
   /**
    * Reduces persisted ID token claims to the ones the SDK itself reads
    * (see {@link SessionManager.ESSENTIAL_ID_TOKEN_CLAIMS}).
    */
   static toEssentialIdTokenClaims(idTokenClaims: Record<string, unknown>): Record<string, unknown> {
-    return Object.fromEntries(
-      Object.entries(idTokenClaims).filter(([claim]: [string, unknown]) =>
-        this.ESSENTIAL_ID_TOKEN_CLAIMS.includes(claim),
-      ),
-    );
+    return this.pickIdTokenClaims(idTokenClaims, this.ESSENTIAL_ID_TOKEN_CLAIMS);
+  }
+
+  /**
+   * Reduces persisted ID token claims to the organization claims only
+   * (see {@link SessionManager.ORGANIZATION_ID_TOKEN_CLAIMS}).
+   */
+  static toOrganizationIdTokenClaims(idTokenClaims: Record<string, unknown>): Record<string, unknown> {
+    return this.pickIdTokenClaims(idTokenClaims, this.ORGANIZATION_ID_TOKEN_CLAIMS);
   }
 
   /**
@@ -222,8 +247,9 @@ class SessionManager {
    * A cookie above the browser limit is dropped silently, which would leave the user without a
    * session right after signing in or refreshing. The ID token claims are the only part of the
    * payload whose size the SDK controls, so when the token exceeds the cookie budget they are
-   * reduced to the essential claims and, if that is still too large, left out entirely. Either
-   * reduction is logged at `warn` level.
+   * narrowed step by step: to the essential identity and organization claims, then to the
+   * organization claims alone, and finally left out entirely. Any reduction is logged at `warn`
+   * level. The session stays cookie-only on purpose; there is no server-side store to fall back to.
    */
   static async createSessionToken(
     accessToken: string,
@@ -259,18 +285,22 @@ class SessionManager {
     let jwt: string = await sign(idTokenClaims);
 
     if (idTokenClaims && jwt.length > budget) {
+      let keptClaims: string = 'only the essential ID token claims';
       jwt = await sign(this.toEssentialIdTokenClaims(idTokenClaims));
 
-      const keptClaims: string =
-        jwt.length > budget ? 'none of the ID token claims are' : 'only the essential ID token claims are';
+      if (jwt.length > budget) {
+        keptClaims = 'only the organization claims of the ID token';
+        jwt = await sign(this.toOrganizationIdTokenClaims(idTokenClaims));
+      }
 
       if (jwt.length > budget) {
         // Without claims, the ID token fallbacks behave as they did before the claims were persisted.
+        keptClaims = 'none of the ID token claims';
         jwt = await sign(undefined);
       }
 
       logger.warn(
-        `[SessionManager] The ID token claims do not fit into the session cookie (budget: ${budget} bytes); ${keptClaims} kept in the session.`,
+        `[SessionManager] The ID token claims do not fit into the session cookie (budget: ${budget} bytes); ${keptClaims} are kept in the session.`,
       );
     }
 

packages/nextjs/src/utils/__tests__/SessionManager.test.ts

@@ -144,7 +144,41 @@ describe('SessionManager', () => {
       });
     });
 
-    it('leaves the claims out when not even the essential claims fit into the cookie', async () => {
+    it('keeps only the organization claims when the essential claims do not fit into the cookie either', async () => {
+      const bulkyEssentialClaims: Record<string, unknown> = {
+        ...idTokenClaims,
+        email: 'jane@example.com',
+        given_name: 'g'.repeat(1200),
+        name: 'n'.repeat(1200),
+        org_handle: 'acme',
+        user_org: 'org-1',
+      };
+
+      const token: string = await SessionManager.createSessionToken(
+        'a'.repeat(2400),
+        'user-1',
+        'session-1',
+        'openid',
+        3600,
+        'refresh-token',
+        'org-1',
+        bulkyEssentialClaims,
+      );
+
+      expect(token.length).toBeLessThanOrEqual(SessionManager.getSessionCookieValueBudget());
+
+      const payload: SessionTokenPayload = await SessionManager.verifySessionToken(token);
+
+      expect(payload.idTokenClaims).toEqual({
+        org_handle: 'acme',
+        org_id: 'org-1',
+        org_name: 'Acme',
+        sub: 'user-1',
+        user_org: 'org-1',
+      });
+    });
+
+    it('leaves the claims out when not even the organization claims fit into the cookie', async () => {
       const token: string = await SessionManager.createSessionToken(
         'a'.repeat(SessionManager.getSessionCookieValueBudget()),
         'user-1',
@@ -163,6 +197,21 @@ describe('SessionManager', () => {
     });
   });
 
+  describe('toOrganizationIdTokenClaims', () => {
+    it('keeps the organization claims and the subject only', () => {
+      expect(
+        SessionManager.toOrganizationIdTokenClaims({
+          email: 'jane@example.com',
+          org_handle: 'acme',
+          org_id: 'org-1',
+          org_name: 'Acme',
+          sub: 'user-1',
+          user_org: 'org-1',
+        }),
+      ).toEqual({org_handle: 'acme', org_id: 'org-1', org_name: 'Acme', sub: 'user-1', user_org: 'org-1'});
+    });
+  });
+
   describe('toEssentialIdTokenClaims', () => {
     it('keeps the organization and basic identity claims only', () => {
       expect(