Export filterDefaultIdTokenClaims and update beforeSessionSaved docs

Author: frederikprijck

EXAMPLES.md

@@ -621,19 +621,36 @@ The `beforeSessionSaved` hook is run right before the session is persisted. It p
 The hook recieves a `SessionData` object and an ID token. The function must return a Promise that resolves to a `SessionData` object: `(session: SessionData) => Promise<SessionData>`. For example:
 
 ```ts
+import { Auth0Client, filterDefaultIdTokenClaims } from "@auth0/nextjs-auth0/server"
+
 export const auth0 = new Auth0Client({
   async beforeSessionSaved(session, idToken) {
     return {
       ...session,
       user: {
-        ...session.user,
-        foo: "bar",
+        ...filterDefaultIdTokenClaims(session.user),
+        foo: session.user.foo, // keep the foo claim
       },
     }
   },
 })
 ```
 
+The `session.user` object passed to the `beforeSessionSaved` hook will contain every claim in the ID Token, including custom claims. You can use the `filterDefaultIdTokenClaims` utility to filter out the standard claims and only keep the custom claims you want to persist.
+
+Alternatively, you can use the entire `session.user` object if you would like to include every claim in the ID Token by just returning the `session` like so:
+
+```ts
+import { Auth0Client } from "@auth0/nextjs-auth0/server"
+
+export const auth0 = new Auth0Client({
+  async beforeSessionSaved(session, idToken) {
+    return session
+  },
+})
+```
+Do realize that this has an impact on the size of the cookie being issued, so it's best to limit the claims to only those that are necessary for your application.
+
 ### `onCallback`
 
 The `onCallback` hook is run once the user has been redirected back from Auth0 to your application with either an error or the authorization code which will be verified and exchanged.

src/server/auth-client.ts

@@ -34,7 +34,7 @@ import {
 import { toSafeRedirect } from "../utils/url-helpers";
 import { AbstractSessionStore } from "./session/abstract-session-store";
 import { TransactionState, TransactionStore } from "./transaction-store";
-import { filterClaims } from "./user";
+import { filterDefaultIdTokenClaims } from "./user";
 
 export type BeforeSessionSavedHook = (
   session: SessionData,
@@ -563,7 +563,7 @@ export class AuthClient {
         internal: session.internal
       };
     } else {
-      session.user = filterClaims(idTokenClaims);
+      session.user = filterDefaultIdTokenClaims(idTokenClaims);
     }
 
     await this.sessionStore.set(req.cookies, res.cookies, session, true);

src/server/index.ts

@@ -5,3 +5,5 @@ export { AuthClient } from "./auth-client";
 export { TransactionStore } from "./transaction-store";
 
 export { AbstractSessionStore } from "./session/abstract-session-store";
+
+export { filterDefaultIdTokenClaims } from "./user";

src/server/user.test.ts

@@ -1,8 +1,8 @@
 import { describe, expect, it } from "vitest";
 
-import { filterClaims } from "./user";
+import { filterDefaultIdTokenClaims } from "./user";
 
-describe("filterClaims", async () => {
+describe("filterDefaultIdTokenClaims", async () => {
   it("should return only the allowed claims", () => {
     const claims = {
       sub: "user_123",
@@ -20,7 +20,7 @@ describe("filterClaims", async () => {
       exp: 1234567890
     };
 
-    expect(filterClaims(claims)).toEqual({
+    expect(filterDefaultIdTokenClaims(claims)).toEqual({
       sub: "user_123",
       name: "John Doe",
       nickname: "johndoe",
@@ -34,6 +34,6 @@ describe("filterClaims", async () => {
   });
 
   it("should return an empty object if no claims are provided", () => {
-    expect(filterClaims({})).toEqual({});
+    expect(filterDefaultIdTokenClaims({})).toEqual({});
   });
 });

src/server/user.ts

@@ -12,7 +12,7 @@ const DEFAULT_ALLOWED_CLAIMS = [
   "org_id"
 ];
 
-export function filterClaims(claims: { [key: string]: any }) {
+export function filterDefaultIdTokenClaims(claims: { [key: string]: any }) {
   return Object.keys(claims).reduce((acc, key) => {
     if (DEFAULT_ALLOWED_CLAIMS.includes(key)) {
       acc[key] = claims[key];