Add Session Middleware
Configure session middleware within your application to handle authenticated user sessions.
To track authentication states, add Wristband's session middleware to your application. This middleware attaches an encrypted req.session cookie to each incoming request to store authenticated user data, automatically decrypting it on subsequent requests to restore the session state.
Configure Session Middleware
To activate session management, register a session configuration factory inside your Wristband configuration file. The secrets field requires a secure string of at least 32 characters. If you need to create one, you can generate a random, high-entropy key at securepassword.dev.
Disabling Secure Session Cookies in Local DevelopmentSession cookies are configured with the secure flag enabled by default, restricting their transmission strictly to HTTPS connections. While most modern browsers grant an exception for
http://localhost, platforms like Safari enforce stricter security policies and completely block secure cookies over unencrypted local HTTP connections.
To prevent authentication failures during local development, togglesecure: falsewithin your session configuration options. Always ensure this flag is reverted tosecure: truebefore deploying your application to a production environment to keep session tokens protected.
// src/config/wristband.config.ts
import { registerAs } from '@nestjs/config';
import type { AuthConfig, SessionOptions } from '@wristband/nestjs-auth';
export const authConfig = registerAs('wristbandAuth', (): AuthConfig => ({
clientId: '<WRISTBAND_CLIENT_ID>',
clientSecret: '<WRISTBAND_CLIENT_SECRET>',
wristbandApplicationVanityDomain: '<WRISTBAND_APPLICATION_VANITY_DOMAIN>',
}));
// ADD: Session options to use in both Session Middleware and Auth Guards.
const sessionOptions: SessionOptions = {
secrets: '<your-generated-secret>',
};
// ADD: Session configuration for the session middleware.
export const sessionConfig = registerAs(
'wristbandSession',
(): SessionOptions => sessionOptions,
);// src/config/wristband.config.ts
import { registerAs } from '@nestjs/config';
import type { AuthConfig, SessionOptions } from '@wristband/nestjs-auth';
export const authConfig = registerAs('wristbandAuth', (): AuthConfig => ({
clientId: '<WRISTBAND_CLIENT_ID>',
clientSecret: '<WRISTBAND_CLIENT_SECRET>',
wristbandApplicationVanityDomain: '<WRISTBAND_APPLICATION_VANITY_DOMAIN>',
dangerouslyDisableSecureCookies: true,
}));
// ADD: Session options to use in both Session Middleware and Auth Guards.
const sessionOptions: SessionOptions = {
secrets: '<your-generated-secret>',
secure: false,
};
// ADD: Session configuration for the session middleware.
export const sessionConfig = registerAs(
'wristbandSession',
(): SessionOptions => sessionOptions,
);Register The Session Module and Middleware
Next, do the following:
- Import the
WristbandExpressSessionModuleand add it to yourAppModuleimports. Configure it withforRootAsync()using NestJS's async provider pattern. - Import the
WristbandExpressSessionMiddlewareand apply it globally to all routes using NestJS's middleware consumer.
NestJS Version 10.x NoteIf you're using NestJS 10.x, use
.forRoutes('*')instead of.forRoutes('{*splat}')for the middleware consumer.
// src/app.module.ts
import { ConfigModule, ConfigService } from '@nestjs/config';
import { Module, NestModule, MiddlewareConsumer } from '@nestjs/common';
import { env } from 'node:process';
import { WristbandExpressAuthModule } from '@wristband/nestjs-auth';
import {
WristbandExpressSessionMiddleware,
WristbandExpressSessionModule
} from '@wristband/nestjs-auth/session';
// Import the session configuration.
import { authConfig, sessionConfig } from './config/wristband.config';
@Module({
imports: [
ConfigModule.forRoot({
isGlobal: true,
load: [authConfig, sessionConfig], // <-- Register the session configuration.
envFilePath: env.NODE_ENV === 'production' ? '' : '.env',
ignoreEnvFile: env.NODE_ENV === 'production',
}),
WristbandExpressAuthModule.forRootAsync({
imports: [ConfigModule],
useFactory: (configService: ConfigService) => configService.get('wristbandAuth'),
inject: [ConfigService],
}),
// Inject the Wristband configurations for Session Middleware.
WristbandExpressSessionModule.forRootAsync({
imports: [ConfigModule],
useFactory: (configService: ConfigService) => configService.get('wristbandSession'),
inject: [ConfigService],
}),
// ...any project-specific modules...
],
})
export class AppModule implements NestModule {
configure(consumer: MiddlewareConsumer) {
// ADD: Configure the middleware for your app on all routes.
consumer.apply(WristbandExpressSessionMiddleware).forRoutes('{*splat}');
}
}Updated 13 days ago
What’s Next
Next, you'll use the Wristband SDK to create the auth guard needed to secure your application.