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
A 32-byte, hex-encoded secret used for encrypting cookies.
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.
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).
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).
A custom session store implementation used to persist sessions to a data store.
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.
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.
The path attribute of the session cookie.
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.
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>
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>
iat property on the session will be used to compute the maxAge cookie value.
reqCookies
RequestCookies | ReadonlyRequestCookies
required
The request cookies object.
The response cookies object.
The session data to save.
Whether this is a new session.
delete
abstract delete(
reqCookies: RequestCookies | ReadonlyRequestCookies,
resCookies: ResponseCookies
): Promise<void>
reqCookies
RequestCookies | ReadonlyRequestCookies
required
The request cookies object.
The response cookies object.
Protected Methods
These methods are available to subclasses.
epoch
Returns the time since unix epoch in seconds.
The current time in seconds since epoch.
calculateMaxAge
calculateMaxAge(createdAt: number): number
The time the session was created (seconds since epoch).
The maximum age of the session in seconds.
Public Properties
The secret used for encrypting cookies.
The name of the session cookie.
store
SessionDataStore | undefined
The custom session store implementation (if provided).
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>
session
Promise<SessionData | null>
Returns the session data or null if no session exists.
set
set(id: string, session: SessionData): Promise<void>
The session data to save.
delete
delete(id: string): Promise<void>
deleteByLogoutToken
deleteByLogoutToken?(logoutToken: LogoutToken): Promise<void>
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
-
Session Expiration: Implement proper TTL/expiration in your custom store to prevent stale sessions from accumulating.
-
Error Handling: Implement proper error handling in your store methods. The SDK will catch errors and treat them as missing sessions.
-
Performance: Consider implementing caching strategies for frequently accessed sessions.
-
Security: Ensure your session store is properly secured and access is restricted.
-
Backchannel Logout: Implement
deleteByLogoutToken to support Auth0’s backchannel logout feature.
-
Cleanup: Implement a background job to clean up expired sessions from your store.
