AbstractSessionStore

Base class for custom session store implementations

The AbstractSessionStore is an abstract base class for implementing custom session stores. It provides the foundation for both stateless (cookie-based) and stateful (external store) session management.

Overview

The SDK provides two built-in implementations:

• StatelessSessionStore: Stores the entire session in an encrypted cookie (default)
• StatefulSessionStore: Stores a session ID in a cookie and the session data in an external store

You can extend AbstractSessionStore to create custom session storage implementations.

Constructor

constructor(options: SessionStoreOptions)

Options

secret · string · required

A 32-byte, hex-encoded secret used for encrypting cookies.

rolling · boolean · default: true

A boolean indicating whether rolling sessions should be used or not.

When enabled, the session will continue to be extended as long as it is used within the inactivity duration. Once the upper bound, set via the absoluteDuration, has been reached, the session will no longer be extended.

absoluteDuration · number · default: 259200

The absolute duration after which the session will expire (in seconds).

Once the absolute duration has been reached, the session will no longer be extended.

Default: 3 days (259200 seconds).

inactivityDuration · number · default: 86400

The duration of inactivity after which the session will expire (in seconds).

The session will be extended as long as it was active before the inactivity duration has been reached.

Default: 1 day (86400 seconds).

store · SessionDataStore

A custom session store implementation used to persist sessions to a data store.

cookieOptions · SessionCookieOptions

The options for the session cookie.

cookieOptions.name · string · default: "__session"

The name of the session cookie.

cookieOptions.sameSite · 'strict' | 'lax' | 'none' · default: "lax"

The sameSite attribute of the session cookie.

cookieOptions.secure · boolean

The secure attribute of the session cookie.

Default: depends on the protocol of the application’s base URL. If the protocol is https, then true, otherwise false.

cookieOptions.path · string · default: "/"

The path attribute of the session cookie.

cookieOptions.domain · string

Specifies the value for the Domain Set-Cookie attribute. By default, no domain is set, and most clients will consider the cookie to apply to only the current domain.

cookieOptions.transient · boolean

The transient attribute of the session cookie. When true, the cookie will not persist beyond the current session.

Abstract Methods

These methods must be implemented by subclasses.

get

abstract get(
  reqCookies: RequestCookies | ReadonlyRequestCookies
): Promise<SessionData | null>

Retrieves the session data from the store.

reqCookies · RequestCookies | ReadonlyRequestCookies · required

The request cookies object.

session · Promise<SessionData | null>

Returns the session data or null if no session exists.

set

abstract set(
  reqCookies: RequestCookies | ReadonlyRequestCookies,
  resCookies: ResponseCookies,
  session: SessionData,
  isNew?: boolean
): Promise<void>

Saves the session data to the store and sets the session cookie.

The iat property on the session will be used to compute the maxAge cookie value.

reqCookies · RequestCookies | ReadonlyRequestCookies · required

The request cookies object.

resCookies · ResponseCookies · required

The response cookies object.

session · SessionData · required

The session data to save.

isNew · boolean

Whether this is a new session.

delete

abstract delete(
  reqCookies: RequestCookies | ReadonlyRequestCookies,
  resCookies: ResponseCookies
): Promise<void>

Deletes the session from the store and clears the session cookie.

reqCookies · RequestCookies | ReadonlyRequestCookies · required

The request cookies object.

resCookies · ResponseCookies · required

The response cookies object.

Protected Methods

These methods are available to subclasses.

epoch

epoch(): number

Returns the time since unix epoch in seconds.

timestamp · number

The current time in seconds since epoch.

calculateMaxAge

calculateMaxAge(createdAt: number): number

Calculates the max age of the session based on createdAt and the rolling and absolute durations.

createdAt · number · required

The time the session was created (seconds since epoch).

maxAge · number

The maximum age of the session in seconds.

Public Properties

secret · string

The secret used for encrypting cookies.

sessionCookieName · string

The name of the session cookie.

store · SessionDataStore | undefined

The custom session store implementation (if provided).

cookieConfig · CookieOptions

The cookie configuration options.

SessionDataStore Interface

When implementing a custom session store, you must provide an object that implements the SessionDataStore interface:

interface SessionDataStore {
  /**
   * Gets the session from the store given a session ID.
   */
  get(id: string): Promise<SessionData | null>;

  /**
   * Upsert a session in the store given a session ID and SessionData.
   */
  set(id: string, session: SessionData): Promise<void>;

  /**
   * Destroys the session with the given session ID.
   */
  delete(id: string): Promise<void>;

  /**
   * Deletes the session with the given logout token which may contain
   * a session ID or a user ID, or both.
   */
  deleteByLogoutToken?(logoutToken: LogoutToken): Promise<void>;
}

get

get(id: string): Promise<SessionData | null>

Gets the session from the store given a session ID.

id · string · required

The session ID.

session · Promise<SessionData | null>

Returns the session data or null if no session exists.

set

set(id: string, session: SessionData): Promise<void>

Upserts a session in the store given a session ID and SessionData.

id · string · required

The session ID.

session · SessionData · required

The session data to save.

delete

delete(id: string): Promise<void>

Destroys the session with the given session ID.

id · string · required

The session ID.

deleteByLogoutToken

deleteByLogoutToken?(logoutToken: LogoutToken): Promise<void>

Deletes the session with the given logout token which may contain a session ID or a user ID, or both.

logoutToken · LogoutToken · required

The logout token containing sub (user ID) and/or sid (session ID).

Example: Custom Database Session Store

import { SessionDataStore, SessionData, LogoutToken } from '@auth0/nextjs-auth0/types';
import { Auth0Client } from '@auth0/nextjs-auth0/server';
import { sql } from './db';

class DatabaseSessionStore implements SessionDataStore {
  async get(id: string): Promise<SessionData | null> {
    const result = await sql`
      SELECT session_data FROM sessions WHERE id = ${id}
    `;
    
    if (result.length === 0) {
      return null;
    }
    
    return JSON.parse(result[0].session_data);
  }

  async set(id: string, session: SessionData): Promise<void> {
    await sql`
      INSERT INTO sessions (id, session_data, updated_at)
      VALUES (${id}, ${JSON.stringify(session)}, NOW())
      ON CONFLICT (id)
      DO UPDATE SET
        session_data = ${JSON.stringify(session)},
        updated_at = NOW()
    `;
  }

  async delete(id: string): Promise<void> {
    await sql`DELETE FROM sessions WHERE id = ${id}`;
  }

  async deleteByLogoutToken(logoutToken: LogoutToken): Promise<void> {
    if (logoutToken.sid) {
      await this.delete(logoutToken.sid);
    } else if (logoutToken.sub) {
      await sql`
        DELETE FROM sessions
        WHERE session_data::json->>'user'->>'sub' = ${logoutToken.sub}
      `;
    }
  }
}

// Use the custom session store
export const auth0 = new Auth0Client({
  sessionStore: new DatabaseSessionStore()
});

Example: Redis Session Store

import { SessionDataStore, SessionData } from '@auth0/nextjs-auth0/types';
import { Auth0Client } from '@auth0/nextjs-auth0/server';
import { createClient } from 'redis';

const redisClient = createClient({
  url: process.env.REDIS_URL
});
await redisClient.connect();

class RedisSessionStore implements SessionDataStore {
  async get(id: string): Promise<SessionData | null> {
    const data = await redisClient.get(`session:${id}`);
    
    if (!data) {
      return null;
    }
    
    return JSON.parse(data);
  }

  async set(id: string, session: SessionData): Promise<void> {
    // Store with 7 day TTL
    await redisClient.setEx(
      `session:${id}`,
      60 * 60 * 24 * 7,
      JSON.stringify(session)
    );
  }

  async delete(id: string): Promise<void> {
    await redisClient.del(`session:${id}`);
  }
}

export const auth0 = new Auth0Client({
  sessionStore: new RedisSessionStore()
});

SessionData Type

interface SessionData {
  user: User;
  tokenSet: TokenSet;
  accessTokens?: AccessTokenSet[];
  internal: {
    sid: string;         // Session ID from authorization server
    createdAt: number;   // Time session was created (seconds since epoch)
  };
  connectionTokenSets?: ConnectionTokenSet[];
  [key: string]: unknown;
}

Best Practices

1. Session Expiration: Implement proper TTL/expiration in your custom store to prevent stale sessions from accumulating.

2. Error Handling: Implement proper error handling in your store methods. The SDK will catch errors and treat them as missing sessions.

3. Performance: Consider implementing caching strategies for frequently accessed sessions.

4. Security: Ensure your session store is properly secured and access is restricted.

5. Backchannel Logout: Implement deleteByLogoutToken to support Auth0’s backchannel logout feature.

6. Cleanup: Implement a background job to clean up expired sessions from your store.