Forem: juanpeyrot

Building Secure Session-Based Authentication in NestJS - Part 3

juanpeyrot — Wed, 31 Dec 2025 02:59:09 +0000

PART 3 - Logout, CORS & CSRF

In this article, we complete our session-based authentication system by focusing on logout semantics, cross-origin configuration, and CSRF protection.

At this stage, we already have:

Redis-backed sessions
Passport-based authentication
Session rotation
Per-user session tracking

What remains is to secure the edges: how sessions are terminated, how browsers are allowed to send cookies, and how we prevent forged requests.

Logout

A robust authentication system must support two logout scenarios:

Revoking the current session only
Revoking all active sessions belonging to a user

Both are critical for real-world security.

⚠️ Note

These endpoints should be implemented as HTTP POST.

In this guide, GET is used only to simplify browser testing and avoid external client cookie setup.

Logout (current session)

File: auth/auth.controller.ts

This endpoint revokes only the current session, leaving other active sessions (other devices or browsers) untouched.

@Get('logout')
@UseGuards(SessionAuthenticationGuard)
async logout(
  @Req() req: AuthenticatedRequest,
  @Res({ passthrough: true }) res: Response,
) {
  const userId = req.user.id;
  const sessionId = req.sessionID;

  // 1️⃣ Revoke current session in Redis
  await this.sessionService.unregisterSession(userId, sessionId);

  // 2️⃣ Passport cleanup
  await new Promise<void>((resolve, reject) =>
    req.logout((err) => (err ? reject(err) : resolve())),
  );

  // 3️⃣ Destroy HTTP session
  await new Promise<void>((resolve, reject) =>
    req.session.destroy((err) => (err ? reject(err) : resolve())),
  );

  // 4️⃣ Clear session cookie
  res.clearCookie('sid', {
    httpOnly: true,
    secure: envs.NODE_ENV === 'production',
    sameSite: 'lax',
  });

  return { success: true };
}

Execution flow:

The session ID is removed from Redis and from the per-user session set
Passport clears the authentication state
The HTTP session is destroyed
The browser cookie is removed

At this point, the user is logged out only from the current device.

Logout all sessions

File: auth/auth.controller.ts

This endpoint revokes every active session belonging to the user, across all devices.

@Get('logout-all')
@UseGuards(SessionAuthenticationGuard)
async logoutAll(
  @Req() req: AuthenticatedRequest,
  @Res({ passthrough: true }) res: Response,
) {
  const userId = req.user.id;

  // 1️⃣ Revoke all sessions (including current one)
  await this.sessionService.revokeAllSessions(userId);

  // 2️⃣ Passport cleanup
  await new Promise<void>((resolve, reject) =>
    req.logout((err) => (err ? reject(err) : resolve())),
  );

  // 3️⃣ Destroy current session
  await new Promise<void>((resolve, reject) =>
    req.session.destroy((err) => (err ? reject(err) : resolve())),
  );

  // 4️⃣ Clear cookie
  res.clearCookie('sid', {
    httpOnly: true,
    secure: envs.NODE_ENV === 'production',
    sameSite: 'lax',
  });

  return { success: true };
}

This is typically used for security actions, such as:

Password changes
Account compromise recovery
Manual “log out from all devices”

Typed authenticated request

File: src/types/request.types.ts

import type { Request } from "express";

export type AuthenticatedRequest = Request & {
  user: { id: string };
};

Why is this important?

Passport dynamically injects req.user at runtime, but TypeScript has no knowledge of that by default.

This custom type:

Prevents unsafe any access
Makes authentication assumptions explicit
Improves DX and refactor safety
Ensures req.user.id is always available in protected routes

CORS Configuration

Browsers enforce strict rules around cross-origin requests.

If your frontend and backend live on different origins, your backend must explicitly allow credentials.

Otherwise:

Cookies will not be sent
Sessions will never load
Authentication will silently fail

CORS setup

File: main.ts

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  app.enableCors({
    origin: ["http://localhost:3000", "https://app.yourdomain.com"],
    credentials: true,
    methods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
    allowedHeaders: ["Content-Type", "X-CSRF-Token", "Authorization"],
    exposedHeaders: ["Set-Cookie"],
  });

  // ... remaining setup
}

Key points:

credentials: true is mandatory for cookies
Origins must be explicitly whitelisted
CSRF token headers must be allowed

CSRF Protection

CSRF is an attack where a malicious website tricks a user’s browser into making a request to your application while the user is already authenticated.

The key idea is:

Browsers automatically send cookies (including session cookies)
An attacker cannot read responses, but can force a request to be sent

So the server sees:

“Valid session cookie → must be a legitimate user”

…but the user never intended to perform that action.

More details: https://owasp.org/www-community/attacks/csrf

How CSRF is mitigated

CSRF attacks are prevented by requiring a secret, per-session token on every state-changing request.

Our approach:

Issue a CSRF token
- Only after authentication
- Bound to the current session
- Exposed via GET /auth/csrf-token
Store the secret server-side
- csurf stores it inside the session
- The client never sees the secret
Validate on every write
- POST, PUT, DELETE
- Missing or invalid token → 403 Forbidden

A cookie alone is no longer sufficient.

The attacker cannot read or guess the CSRF token due to the Same-Origin Policy.

How does it work in real world?

For protected requests (e.g POST / PUT / DELETE):

Frontend sends the token:
- Header: X-CSRF-Token
- or body field _csrf
csurf validates:
- Is the session valid?
- Does the token match this session?

If not → 403 Forbidden

IMPORTANT: Please note than by implementing CSRF, when you rotate a session, the CSRF secret changes, therefore:

Previously issued CSRF tokens become invalid
Frontend must fetch a new CSRF token

This is expected and correct behavior.

Security tradeoff:

✔️ smaller attack window
❌ more frontend coordination

CSRF middleware

Add the following config to main.ts to set up csurf middleware:

pnpm i csurf
pnpm i -D @types/csurf

File: main.ts

import csurf from "csurf";

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  app.use((req: Request, res: Response, next: NextFunction) => {
    const csrfExcludedPaths = ["/auth/google", "/auth/google/callback"];

    if (csrfExcludedPaths.includes(req.path)) {
      return next();
    }

    return csurf({ cookie: false })(req, res, next);
  });

  await app.listen(envs.PORT ?? 3000);
}

Why this configuration?

CSRF secrets are stored inside the session, not cookies
OAuth routes cannot include CSRF tokens
Middleware runs after session & passport restoration

CSRF token endpoint

File: auth/auth.controller.ts

@Get('csrf-token')
@UseGuards(SessionAuthenticationGuard)
getCsrf(@Req() req: Request) {
  return { csrfToken: req.csrfToken() };
}

This endpoint allows the frontend to:

Fetch a valid CSRF token
Bind it to the current authenticated session
Refresh it after session rotation

⚠️ Important

When a session is rotated, the CSRF secret changes.

Previously issued tokens become invalid — this is expected and correct.

Example request sequence with CSRF

1️⃣ User logs in

GET /auth/google
→ Redirect to Google

GET /auth/google/callback
→ Session is regenerated
→ Session stored in Redis
→ Cookie set: sid=abc123

2️⃣ Client asks for CSRF token

GET /auth/csrf-token
Cookie: sid=abc123

Server:

Loads session from Redis
Generates CSRF token
Returns it

{ "csrfToken":"XyZ123..." }

3️⃣ Client performs a protected action

POST /transfer
Cookie: sid=abc123
Header: X-CSRF-Token: XyZ123...
Body: { amount: 100 }

Server:

express-session loads session
passport.session restores req.user
csurf validates token against session secret
Request is allowed ✅

4️⃣ Attack attempt (CSRF)

POST /transfer
Cookie: sid=abc123   (browser auto-sends it)

But:

Attacker cannot read or generate the CSRF token
Token missing or invalid → 403 Forbidden

Conclusion & Further Steps

We now have a production-ready, session-based authentication system with strong security guarantees:

Redis-backed, revocable sessions
Per-user session tracking
Session rotation against fixation attacks
Secure logout semantics
Proper CORS configuration
CSRF protection bound to sessions
Clean Passport lifecycle integration

Possible extensions

Session metadata (IP, device, timestamps)
User-facing session management UI
Security signal detection (IP / country changes)
Absolute session lifetimes
Automatic revocation on password or role changes
Audit logging
Rate limiting and abuse protection

⭐ Github Repo

If this repository saved you time or effort, please ⭐ star it on GitHub.

📚 Article Series

Building Secure Session-Based Authentication in NestJS - Part 2

juanpeyrot — Mon, 29 Dec 2025 17:57:35 +0000

PART 2 - Sessions

This article continues the authentication series and focuses on how sessions work internally, how they are restored on every request, and how to secure them properly using Redis, Passport, and session rotation.

Sessions Overview

Imagine a user wants to change their password in our application.

Before doing so, they must authenticate.

The authentication flow begins when the user initiates:

GET /auth/google

After a successful authentication, Google redirects the user back to our application at:

GET /auth/google/callback

At this point, the user is considered logged in.

Later on, the same user sends another request—this time to change their password.

When the application receives this request, a critical question arises:

How can the server be sure this request comes from the same authenticated user, and not from someone else impersonating them?

HTTP requests are stateless and independent by nature. Each request is processed in isolation, and without a persistent mechanism, the server has no memory of who authenticated previously.

This is exactly where sessions become essential.

By creating a server-side session during login and associating it with the user, the application can reliably identify that user across subsequent requests. Every protected action—such as changing a password—can then validate the session and ensure the request truly belongs to the authenticated user.

Desired Authentication Flow

Once the user successfully logs in, the server creates a new authenticated session.

On the server side, this session is stored in Redis. Conceptually, Redis works like a dictionary: each entry represents a user and maps to one or more active sessions belonging to that user.

For a first login, the application creates a Redis entry with the key:

user_session:<user_id>

Inside this entry, the server stores the identifiers of all sessions associated with that user. Each individual session is stored using the format:

sess:<session_id>

This design allows a single user to maintain multiple active sessions at the same time—for example, across different browsers or devices.

Once the session has been created and persisted in Redis, and just before sending the response back to the client, the server attaches a cookie to the response:

Set-Cookie: sid=<session_id>

This cookie is HTTP-only and securely configured. From this moment onward, the browser automatically includes the sid cookie in every subsequent request.

When a new request arrives, the server:

Reads the sid cookie
Retrieves the corresponding session from Redis
Reconstructs the authenticated context for that request

Thanks to this mechanism, the server can consistently identify the same user across multiple, independent HTTP requests.

As a result, when the user later performs a sensitive action—such as changing a password or performing a transfer—the server verifies that:

A valid session exists
The session belongs to an authenticated user
The session has not been revoked or expired

Only if all these checks pass does the application allow the operation to proceed.

Middleware Chain

Before looking at code, it is crucial to understand how middleware execution works.

For every incoming HTTP request, Express / NestJS executes middleware in the exact order they are registered:

Request
  ↓
express-session
  ↓
passport.initialize()
  ↓
passport.session()
  ↓
Controller / Route Handler

Each middleware has a very specific responsibility, and understanding this order is fundamental.

1. `express-session`

Responsibility

Load the session associated with the request (if any)
Provide state continuity across requests
Attach req.session

1️⃣ Reads the session ID from cookies

Express looks for a cookie named:

sid

If the cookie exists, it may look like:

sid=abc123

2️⃣ Resolves the session from Redis

Using the cookie value, Express queries Redis:

sess:abc123

If found → session data is loaded
If not found → the session is treated as empty

3️⃣ Attaches `req.session`

Regardless of whether the session existed, Express always attaches a session object:

req.session = { ... }

Existing session → contains stored data
Missing session → an empty session object is created

⚠️ Important

This does not authenticate the user
It only provides state continuity

Why no error if the cookie is missing?

Sessions are optional.

Anonymous users must be able to access endpoints such as login, signup, and OAuth initiation.

Therefore:

No cookie → no error
req.session exists, but is empty

2. `passport.initialize()`

Responsibility

Prepare the request object to support authentication
Expose Passport helper methods

File

main.ts

app.use(passport.initialize());

This middleware decorates req with methods such as:

req.login()
req.logout()
req.isAuthenticated()

What it does NOT do

❌ Does not read sessions
❌ Does not authenticate users
❌ Does not restore users

Think of it as:

“Enable authentication capabilities, but do not authenticate yet.”

3. `passport.session()`

Responsibility

Restore the authenticated user from the session (if present)

File

main.ts

app.use(passport.session());

This middleware depends on express-session having already executed.

Step-by-step behavior

Checks that req.session exists (it always does)
Looks for:

req.session.passport?.user;

Case A: User is logged in

If the value exists:

req.session.passport.user = userId;

Passport then:

Reconstructs the user identifier
Fetches the full user from the database
Attaches it to:

req.user;

✅ The request becomes authenticated

Case B: User is NOT logged in

If the value does not exist:

req.session.passport === undefined;

Then:

Passport does nothing
The request continues as anonymous
req.user === undefined

✅ This is expected behavior

Important clarification

No middleware automatically sets req.session.passport.user.

This value is created only when req.login() is called, usually during:

OAuth callbacks (/auth/google/callback)
Username/password login endpoints

It persists because:

express-session stores it in Redis
Redis persists across requests
The browser keeps sending the sid cookie

Timeline Example

Login request

GET /auth/google

Inside the controller:

req.login(user);

This stores the following in Redis:

sess:abc123 → { passport: { user: "42" } }

Subsequent request

POST /some-private-endpoint

Middleware execution:

express-session loads sess:abc123
passport.session() detects passport.user
Passport reconstructs the user
req.user is populated

👉 Same user identity, different HTTP request.

Middleware Setup

File: `main.ts`

This is where all session-related middleware is registered.

import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module";
import { envs } from "./config/envs";
import { REDIS_CLIENT } from "./redis/redis.constants";
import { RedisStore } from "connect-redis";
import session from "express-session";
import passport from "passport";

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const redisClient = app.get(REDIS_CLIENT);

  app.use(
    session({
      store: new RedisStore({
        client: redisClient,
        prefix: "sess:",
      }),
      name: "sid",
      secret: envs.SESSION_SECRET,
      resave: false,
      saveUninitialized: false,
      rolling: true,
      cookie: {
        httpOnly: true,
        secure: envs.NODE_ENV === "production",
        sameSite: "lax",
        maxAge: 1000 * 60 * 60,
      },
    })
  );

  app.use(passport.initialize());
  app.use(passport.session());

  await app.listen(envs.PORT ?? 3000);
}
bootstrap();

Session Authentication Guard

File: `guards/session-authentication.guard.ts`

This guard protects private endpoints by ensuring a request is authenticated.

import { CanActivate, ExecutionContext, Injectable } from "@nestjs/common";

@Injectable()
export class SessionAuthGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {
    const req = context.switchToHttp().getRequest();
    return req.isAuthenticated();
  }
}

Passport Session Serializer

File: `auth/serializers/session.serializer.ts`

This serializer defines:

What minimal data is stored in the session
How the user is reconstructed on future requests

import { PassportSerializer } from "@nestjs/passport";
import { Injectable } from "@nestjs/common";
import { AuthService } from "../auth.service";
import { User } from "../entities/user.entity";

@Injectable()
export class SessionSerializer extends PassportSerializer {
  constructor(private readonly authService: AuthService) {
    super();
  }

  serializeUser(user: User, done: Function) {
    done(null, user.id);
  }

  async deserializeUser(userId: string, done: Function) {
    const user = await this.authService.findById(userId);
    done(null, user);
  }
}

providers: [AuthService, GoogleStrategy, SessionSerializer];

Session Rotation

Responsibility

Prevent session fixation
Invalidate old session IDs
Preserve authenticated user context

File: `redis/session-rotation.service.ts`

import { Injectable, InternalServerErrorException } from "@nestjs/common";
import { Request } from "express";
import { SessionService } from "./session.service";
import { User } from "src/auth/entities/user.entity";

@Injectable()
export class SessionRotationService {
  constructor(private readonly sessionService: SessionService) {}

  async rotate(req: Request, user: User): Promise<void> {
    if (!req.session) {
      throw new InternalServerErrorException("Session not initialized");
    }

    const oldSessionId = req.sessionID;

    await new Promise<void>((resolve, reject) =>
      req.session.regenerate((err) => (err ? reject(err) : resolve()))
    );

    await new Promise<void>((resolve, reject) =>
      req.login(user, (err) => (err ? reject(err) : resolve()))
    );

    await this.sessionService.registerSession(user.id, req.sessionID);

    if (oldSessionId) {
      await this.sessionService.unregisterSession(user.id, oldSessionId);
    }
  }
}

Session Service

File: `redis/session.service.ts`

This service encapsulates all direct interaction with Redis sessions.

import { Inject, Injectable } from "@nestjs/common";
import type { RedisClientType } from "redis";
import { REDIS_CLIENT } from "../redis.constants";

@Injectable()
export class SessionService {
  constructor(
    @Inject(REDIS_CLIENT)
    private readonly redis: RedisClientType
  ) {}

  async registerSession(userId: string, sessionId: string) {
    await this.redis.sAdd(`user_sessions:${userId}`, sessionId);
  }

  async unregisterSession(userId: string, sessionId: string) {
    const pipeline = this.redis.multi();

    pipeline.del(`sess:${sessionId}`);
    pipeline.sRem(`user_sessions:${userId}`, sessionId);

    await pipeline.exec();
  }

  async revokeAllSessions(userId: string) {
    const key = `user_sessions:${userId}`;
    const sessionIds = await this.redis.sMembers(key);

    const pipeline = this.redis.multi();

    for (const sid of sessionIds) {
      pipeline.del(`sess:${sid}`);
    }

    pipeline.del(key);
    await pipeline.exec();
  }
}

When to Rotate Sessions

✅ Recommended moments

After login
After re-authentication (2FA, password confirmation)
After privilege or role changes
After sensitive operations

❌ When you should NOT rotate sessions

On every request
On read-only operations
On regular business actions

Rotate sessions when the security context changes, not when normal business logic is executed.

Example: Google Callback

File: `auth/auth.controller.ts`

@Get('google/callback')
@UseGuards(GoogleOAuthGuard)
async googleCallback(@Req() req: Request, @GetUser() user: OAuthUser) {
  const authUser = await this.authService.findOrCreate(user);
  await this.sessionRotationService.rotate(req, authUser);
  return { success: true };
}

Testing a Protected Endpoint

File: `auth/auth.controller.ts`

// just for testing purposes, this is a GET endpoint in order to be easily
// called from browser, but it should be PATCH in-practice
@Get('users/password')
@UseGuards(SessionAuthenticationGuard)
async changePassword() {
  return 'Password changed!';
}

If accessed without authentication, this endpoint responds with HTTP 403 Forbidden.

We can run our app and open a new browser tab, and login as usual via doing a GET request to /auth/google. Once we are logged, we can open a new tab (or just replacing URL in the current one) and access to /auth/users/password to verify that we have proper access to that private endpoint (because we are authenticated).

Note that if we open a new private tab and try to access to the private endpoint, we get an HTTP Status Code 403 as we are not logged.

⭐ Github Repo

If this repository saved you time or effort, please ⭐ star it on GitHub.

📚 Article Series

Building Secure Session-Based Authentication in NestJS - Part 1

juanpeyrot — Sun, 28 Dec 2025 18:10:26 +0000

Introduction

Session-based authentication is everywhere — yet many developers rely on it daily without fully understanding how it actually works under the hood.

In this series, we will build a real, production-style session-based authentication system using NestJS, Passport, Redis, and HTTP cookies. Along the way, we will demystify what happens on every request:

How sessions are created
Where they are stored
How they are validated
How session rotation works
How sessions are revoked

No magic. No hidden abstractions.

This article is Part 1 of a 3-part series. By the end of the series, we will have a complete, working application.

Prerequisites

Before starting, make sure you have the following installed:

Docker – https://www.docker.com/
NestJS CLI – https://docs.nestjs.com/cli/overview
TablePlus (optional) – https://tableplus.com/download/ (or any database client of your choice)

PART 1 — Project Setup

Dependencies & Environment Variables

Project initialization

First, create a new NestJS project:

nest new nest-session

I will be using pnpm for this project, but you can use npm or yarn if you prefer.

Install the required dependencies:

pnpm i express-session redis connect-redis pg joi dotenv @nestjs/typeorm typeorm @nestjs/passport passport

And the development typings:

pnpm i -D @types/express-session @types/passport

Environment configuration

We will centralize and validate all environment variables using Joi.

Create the following file:

config/envs.ts

import 'dotenv/config';

import * as joi from 'joi';

interface EnvVars {
  PORT: number;
  NODE_ENV: string;

  GOOGLE_CLIENT_ID: string;
  GOOGLE_CLIENT_SECRET: string;
  GOOGLE_CALLBACK_URL: string;

  POSTGRES_HOST: string;
  POSTGRES_PORT: number;
  POSTGRES_USER: string;
  POSTGRES_PASSWORD: string;
  POSTGRES_DB_NAME: string;

  REDIS_PASSWORD: string;
  REDIS_HOST: string;
  REDIS_PORT: number;
  REDIS_URI: string;

  SESSION_SECRET: string;
}

const envsSchema = joi
  .object({
    PORT: joi.number().required(),
    NODE_ENV: joi.string().required(),

    GOOGLE_CLIENT_ID: joi.string().required(),
    GOOGLE_CLIENT_SECRET: joi.string().required(),
    GOOGLE_CALLBACK_URL: joi.string().required(),

    POSTGRES_HOST: joi.string().required(),
    POSTGRES_PORT: joi.number().required(),
    POSTGRES_USER: joi.string().required(),
    POSTGRES_PASSWORD: joi.string().required(),
    POSTGRES_DB_NAME: joi.string().required(),

    REDIS_PASSWORD: joi.string().required(),
    REDIS_HOST: joi.string().required(),
    REDIS_PORT: joi.number().required(),
    REDIS_URI: joi.string().required(),

    SESSION_SECRET: joi.string().required(),
  })
  .unknown(true);

const { error, value } = envsSchema.validate(process.env);

if (error) {
  throw new Error(`Config validation error: ${error.message}`);
}

const envVars: EnvVars = value;

export const envs = {
  PORT: envVars.PORT,
  NODE_ENV: envVars.NODE_ENV,

  GOOGLE_CLIENT_ID: envVars.GOOGLE_CLIENT_ID,
  GOOGLE_CLIENT_SECRET: envVars.GOOGLE_CLIENT_SECRET,
  GOOGLE_CALLBACK_URL: envVars.GOOGLE_CALLBACK_URL,

  POSTGRES_HOST: envVars.POSTGRES_HOST,
  POSTGRES_PORT: envVars.POSTGRES_PORT,
  POSTGRES_USER: envVars.POSTGRES_USER,
  POSTGRES_PASSWORD: envVars.POSTGRES_PASSWORD,
  POSTGRES_DB_NAME: envVars.POSTGRES_DB_NAME,

  REDIS_PASSWORD: envVars.REDIS_PASSWORD,
  REDIS_HOST: envVars.REDIS_HOST,
  REDIS_PORT: envVars.REDIS_PORT,
  REDIS_URI: envVars.REDIS_URI,

  SESSION_SECRET: envVars.SESSION_SECRET,
};

`.env` file

Make sure all required variables are defined in your .env file:

PORT=3000
NODE_ENV=development

GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GOOGLE_CALLBACK_URL=http://localhost:3000/auth/google/callback

POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=
POSTGRES_PASSWORD=
POSTGRES_DB_NAME=

REDIS_PASSWORD=
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_URI=redis://localhost:6379

SESSION_SECRET=

⚠️ Every variable must have a value, or the application will fail during startup.

OAuth provider (Google)

For this guide, we will use OAuth2 with Google as the authentication provider.

Create a new OAuth application and obtain your Client ID and Client Secret here:

https://console.cloud.google.com/

You can follow this series without OAuth by implementing traditional login and signup endpoints. The session concepts remain exactly the same.

Application entry point

Make sure your application uses the configured port:

main.ts

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { envs } from './config/envs';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(envs.PORT ?? 3000);
}
bootstrap();

Auth & Redis Setup

Generate the Auth module

nest g res auth --no-spec

Select:

Transport layer: REST API
Generate CRUD endpoints: No

Configure the AppModule

app.module.ts

import { envs } from 'src/config/envs';
import { Module } from '@nestjs/common';
import { AuthModule } from './auth/auth.module';
import { TypeOrmModule } from '@nestjs/typeorm';

@Module({
  imports: [
    AuthModule,
    TypeOrmModule.forRoot({
      type: 'postgres',
      host: envs.POSTGRES_HOST,
      port: envs.POSTGRES_PORT,
      username: envs.POSTGRES_USER,
      password: envs.POSTGRES_PASSWORD,
      database: envs.POSTGRES_DB_NAME,
      autoLoadEntities: true,
      synchronize: true, // ⚠️ Disable in production
    }),
  ],
  controllers: [],
  providers: [],
})
export class AppModule {}

Redis Module

We will create a simple global Redis provider.

Create a new folder: src/redis

`redis.constants.ts`

export const REDIS_CLIENT = Symbol('REDIS_CLIENT');

`redis.module.ts`

import { Module } from '@nestjs/common';
import { createClient } from 'redis';
import { envs } from 'src/config/envs';
import { REDIS_CLIENT } from './redis.constants';

@Module({
  providers: [
    {
      provide: REDIS_CLIENT,
      useFactory: async () => {
        const client = createClient({
          url: envs.REDIS_URI,
          password: envs.REDIS_PASSWORD,
        });

        await client.connect();
        return client;
      },
    },
  ],
  exports: [REDIS_CLIENT],
})
export class RedisModule {}

User Entity

Before finalizing the auth setup, let’s define how our users will be stored.

auth/entities/user.entity.ts

import { Column, Entity, PrimaryGeneratedColumn } from 'typeorm';

@Entity('user')
export class User {
  @PrimaryGeneratedColumn('uuid')
  id: string;

  @Column('varchar', { unique: true })
  email: string;

  @Column('varchar')
  fullName: string;

  @Column('varchar')
  provider: 'google' | 'github';

  @Column('varchar')
  providerId: string;

  @Column('varchar', { nullable: true })
  picture?: string;

  @Column('timestamp', { default: () => 'CURRENT_TIMESTAMP' })
  createdAt: Date;
}

AuthModule

auth.module.ts

import { Module } from '@nestjs/common';
import { AuthService } from './auth.service';
import { AuthController } from './auth.controller';
import { PassportModule } from '@nestjs/passport';
import { TypeOrmModule } from '@nestjs/typeorm';
import { User } from './entities/user.entity';
import { RedisModule } from 'src/redis/redis.module';

@Module({
  imports: [
    PassportModule.register({ session: true }),
    TypeOrmModule.forFeature([User]),
    RedisModule,
  ],
  controllers: [AuthController],
  providers: [AuthService],
})
export class AuthModule {}

Docker Setup

Create a docker-compose.yml file in the project root:

version: '3'

services:
  db:
    image: postgres:14.3
    restart: always
    ports:
      - '5432:5432'
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_DB: ${POSTGRES_DB_NAME}
    container_name: nest-session-postgres
    volumes:
      - ./postgres:/var/lib/postgresql/data

  redis:
    image: redis:7
    container_name: redis
    command: redis-server --requirepass "${REDIS_PASSWORD}"
    ports:
      - '${REDIS_PORT}:6379'
    volumes:
      - ./redis-data:/data
    restart: unless-stopped

Start the services:

docker compose up -d

Running the Application

Start the NestJS server:

pnpm run start:dev

At this point, your database schema should be created automatically.

You can verify it by connecting to Postgres using your favorite DB client (e.g. TablePlus) and confirming that the User table matches the entity definition.

In the next part, we’ll define our services, controllers, and guards, and explore how NestJS uses them to authenticate requests, manage session state, and protect routes.

Configuring OAuth2 (Google)

In this section, we will integrate Google OAuth2 using Passport. This will allow users to authenticate using their Google accounts while still relying on our session-based infrastructure.

Installing dependencies

First, install the Passport strategy for Google OAuth2:

pnpm i passport-google-oauth20

OAuth user interface

We define a shared interface that represents users coming from any OAuth provider.

auth/interfaces/oauth.interfaces.ts

export interface OAuthUser {
  provider: 'google' | 'github';
  providerId: string;
  email: string;
  fullName: string;
  picture?: string;
}

This interface acts as a contract between Passport strategies and our application logic.

Google OAuth strategy

Now we can implement the Google strategy. This class encapsulates all provider-specific authentication logic.

auth/strategies/google.strategy.ts

import { Injectable, UnauthorizedException } from '@nestjs/common';
import { PassportStrategy } from '@nestjs/passport';
import {
  Strategy as GoogleStrategyBase,
  Profile as GoogleProfile,
} from 'passport-google-oauth20';
import { envs } from 'src/config/envs';
import { OAuthUser } from '../interfaces/oauth.interfaces';

@Injectable()
export class GoogleStrategy extends PassportStrategy(
  GoogleStrategyBase,
  'google',
) {
  constructor() {
    super({
      clientID: envs.GOOGLE_CLIENT_ID,
      clientSecret: envs.GOOGLE_CLIENT_SECRET,
      callbackURL: envs.GOOGLE_CALLBACK_URL,
      scope: ['email', 'profile'],
    });
  }

  async validate(
    _accessToken: string,
    _refreshToken: string,
    profile: GoogleProfile,
  ): Promise<OAuthUser> {
    const email = this.getPrimaryEmail(profile);

    if (!email) {
      throw new UnauthorizedException('Google account has no verified email');
    }

    return {
      provider: 'google',
      providerId: profile.id,
      email,
      fullName:
        `${profile.name?.givenName ?? ''} ${profile.name?.familyName ?? ''}`.trim(),
      picture: this.getProfilePicture(profile),
    };
  }

  private getPrimaryEmail(profile: GoogleProfile): string {
    const email = profile.emails?.[0];

    if (!email?.verified) {
      throw new UnauthorizedException(`Email ${email?.value} is not verified`);
    }

    return email.value;
  }

  private getProfilePicture(profile: GoogleProfile): string | undefined {
    return profile.photos?.[0]?.value;
  }
}

⚠️ Important: Every Passport strategy must be registered as a provider in the AuthModule.

@Module({
  imports: [/* ... */],
  controllers: [/* ... */],
  providers: [
    /* other providers */,
    GoogleStrategy, // ← mandatory
  ],
})
export class AuthModule {}

OAuth Guard

The guard simply delegates execution to the Google strategy.

auth/guards/google-oauth.guard.ts

import { Injectable } from '@nestjs/common';
import { AuthGuard } from '@nestjs/passport';

@Injectable()
export class GoogleOAuthGuard extends AuthGuard('google') {}

No additional logic is required here.

Controller, Decorator and Logic

To complete the OAuth2 flow, we need two endpoints:

GET /auth/google

Initiates the Google login flow.
GET /auth/google/callback

Handles the response sent by Google after successful authentication.

auth.controller.ts

import { Controller, Get, UseGuards } from '@nestjs/common';
import { AuthService } from './auth.service';
import { GoogleOAuthGuard } from './guards/google-oauth.guard';
import { GetUser } from './decorators/get-user.decorator';
import type { OAuthUser } from './interfaces/oauth.interfaces';

@Controller('auth')
export class AuthController {
  constructor(private readonly authService: AuthService) {}

  @Get('google')
  @UseGuards(GoogleOAuthGuard)
  async googleAuth() {}

  @Get('google/callback')
  @UseGuards(GoogleOAuthGuard)
  async googleCallback(@GetUser() user: OAuthUser) {
    const authUser = await this.authService.findOrCreate(user);
    // we'll be introducing more logic later on
    return { success: true };
  }
}

Custom user decorator

To simplify access to the authenticated user, we implement a custom decorator.

auth/decorators/get-user.decorator.ts

import {
  createParamDecorator,
  ExecutionContext,
  InternalServerErrorException,
} from '@nestjs/common';
import { OAuthUser } from '../interfaces/oauth.interfaces';

export const GetUser = createParamDecorator(
  (data: keyof OAuthUser, ctx: ExecutionContext): OAuthUser => {
    const req = ctx.switchToHttp().getRequest();
    const user = req.user;

    if (!user) {
      throw new InternalServerErrorException('User not found in request');
    }

    return data ? user[data] : user;
  },
);

Authentication service logic

Finally, the AuthService handles persistence and lookup logic.

auth.service.ts

import { BadRequestException, Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { User } from './entities/user.entity';
import { OAuthUser } from './interfaces/oauth.interfaces';

@Injectable()
export class AuthService {
  constructor(
    @InjectRepository(User)
    private readonly userRepository: Repository<User>,
  ) {}

  async findOrCreate(oauthUser: OAuthUser): Promise<User> {
    if (!oauthUser) {
      throw new BadRequestException('Unauthenticated');
    }

    const existingUser = await this.userRepository.findOne({
      where: { email: oauthUser.email },
    });

    if (existingUser) {
      return existingUser;
    }

    const user = this.userRepository.create(oauthUser);
    return this.userRepository.save(user);
  }

  async findById(id: string): Promise<User | null> {
    return this.userRepository.findOne({ where: { id } });
  }
}

At this point, Google OAuth2 is fully integrated.

You can test the flow by opening:

http://localhost:3000/auth/google

After logging in with a Google account, you should see the user persisted in Postgres.

In the next part, we will build on top of this foundation by introducing sessions, Redis-backed storage, and secure cookie handling.

Forem: juanpeyrot

Building Secure Session-Based Authentication in NestJS - Part 3

PART 3 - Logout, CORS & CSRF

Logout

Logout (current session)

Logout all sessions

Typed authenticated request

CORS Configuration

CORS setup

CSRF Protection

How CSRF is mitigated

How does it work in real world?

CSRF middleware

CSRF token endpoint

Example request sequence with CSRF

Conclusion & Further Steps

Possible extensions

⭐ Github Repo

📚 Article Series

Building Secure Session-Based Authentication in NestJS - Part 2

PART 2 - Sessions

Sessions Overview

Desired Authentication Flow

Middleware Chain

1. express-session

Responsibility

1️⃣ Reads the session ID from cookies

2️⃣ Resolves the session from Redis

3️⃣ Attaches req.session

Why no error if the cookie is missing?

2. passport.initialize()

Responsibility

File

What it does NOT do

3. passport.session()

Responsibility

File

Step-by-step behavior

Case A: User is logged in

Case B: User is NOT logged in

Important clarification

Timeline Example

Login request

Subsequent request

Middleware Setup

File: main.ts

Session Authentication Guard

File: guards/session-authentication.guard.ts

Passport Session Serializer

File: auth/serializers/session.serializer.ts

Session Rotation

Responsibility

File: redis/session-rotation.service.ts

Session Service

File: redis/session.service.ts

When to Rotate Sessions

✅ Recommended moments

❌ When you should NOT rotate sessions

Example: Google Callback

File: auth/auth.controller.ts

Testing a Protected Endpoint

File: auth/auth.controller.ts

⭐ Github Repo

📚 Article Series

Building Secure Session-Based Authentication in NestJS - Part 1

Introduction

Prerequisites

PART 1 — Project Setup

Dependencies & Environment Variables

Project initialization

Environment configuration

.env file

OAuth provider (Google)

Application entry point

Auth & Redis Setup

Generate the Auth module

Configure the AppModule

Redis Module

redis.constants.ts

redis.module.ts

1. `express-session`

3️⃣ Attaches `req.session`

2. `passport.initialize()`

3. `passport.session()`

File: `main.ts`

File: `guards/session-authentication.guard.ts`

File: `auth/serializers/session.serializer.ts`

File: `redis/session-rotation.service.ts`

File: `redis/session.service.ts`

File: `auth/auth.controller.ts`

File: `auth/auth.controller.ts`

`.env` file

`redis.constants.ts`

`redis.module.ts`