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 Development

Session 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, toggle secure: false within your session configuration options. Always ensure this flag is reverted to secure: true before 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:

  1. Import the WristbandExpressSessionModule and add it to your AppModule imports. Configure it with forRootAsync() using NestJS's async provider pattern.
  2. Import the WristbandExpressSessionMiddleware and apply it globally to all routes using NestJS's middleware consumer.

NestJS Version 10.x Note

If 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}');
  }
}
























What’s Next

Next, you'll use the Wristband SDK to create the auth guard needed to secure your application.

Did this page help you?