Passport strategies and JWT auth

Two strategies, two moments

Authentication in Nest is two distinct moments, and Passport models each with a strategy. The first moment is login: the client sends a username and password exactly once, you check them against the database, and if they match you hand back a token. That is LocalStrategy. The second moment is every request after: the client presents the token, you verify its signature and expiry, and you trust the identity inside it without touching the database. That is JwtStrategy. A strategy is a class extending PassportStrategy(...) whose validate() method returns the principal — and whatever validate() returns is what Passport attaches to req.user.

LocalStrategy reads the credentials, compares the password against the stored hash, and returns the user (minus the hash). The matching LocalAuthGuard is a one-liner — AuthGuard('local') — and you put it on POST /login so the strategy runs before your handler:

import { Strategy } from 'passport-local';
import { PassportStrategy } from '@nestjs/passport';
import { Injectable, UnauthorizedException } from '@nestjs/common';
import * as bcrypt from 'bcrypt';

@Injectable()
export class LocalStrategy extends PassportStrategy(Strategy) {
  constructor(private users: UsersService) {
    super(); // defaults to fields named 'username' and 'password'
  }

  async validate(username: string, password: string) {
    const user = await this.users.findByName(username);
    if (!user || !(await bcrypt.compare(password, user.passwordHash))) {
      throw new UnauthorizedException();
    }
    const { passwordHash, ...safe } = user;
    return safe; // -> becomes req.user
  }
}

The /login handler then mints the token. By the time the handler runs, the guard has already populated req.user, so all the handler does is sign a payload — never put the password or anything secret in it:

@UseGuards(LocalAuthGuard)
@Post('login')
async login(@Request() req) {
  const payload = { sub: req.user.id, username: req.user.username };
  return { access_token: this.jwt.sign(payload) };
}

Wiring the module: secret from config, not source

JwtModule needs a signing secret and a token lifetime, and both belong in configuration, not a string literal in your repo. registerAsync lets you inject ConfigService through a useFactory, so the secret comes from the environment and rotates without a code change. PassportModule registers the strategy infrastructure; you provide your strategy classes as normal providers:

@Module({
  imports: [
    PassportModule,
    JwtModule.registerAsync({
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        secret: config.getOrThrow<string>('JWT_SECRET'),
        signOptions: { expiresIn: '15m' }, // short-lived access token
      }),
    }),
  ],
  providers: [AuthService, LocalStrategy, JwtStrategy],
})
export class AuthModule {}

JwtStrategy is the verifier. ExtractJwt.fromAuthHeaderAsBearerToken() tells Passport to pull the token from Authorization: Bearer <token>; secretOrKey must be the same secret used to sign, or every verification fails; and leaving ignoreExpiration at its default false is what enforces the TTL. Passport verifies the signature and expiry before your validate() runs, so by the time you see the payload it is already proven authentic — you just shape the principal:

import { ExtractJwt, Strategy } from 'passport-jwt';
import { PassportStrategy } from '@nestjs/passport';
import { Injectable } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';

@Injectable()
export class JwtStrategy extends PassportStrategy(Strategy) {
  constructor(config: ConfigService) {
    super({
      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
      ignoreExpiration: false, // reject expired tokens (the default — keep it)
      secretOrKey: config.getOrThrow<string>('JWT_SECRET'),
    });
  }

  async validate(payload: { sub: string; username: string }) {
    return { userId: payload.sub, username: payload.username }; // -> req.user
  }
}

Fail closed: a global guard plus @Public()

The dangerous default is opt-in protection — sprinkling @UseGuards(JwtAuthGuard) on each route and hoping nobody forgets one. Invert it: register the JWT guard globally with APP_GUARD so every route is protected by default, then carve explicit holes with a @Public() decorator the guard checks via the Reflector. Forgetting the decorator now leaves a route locked, not open — the safe failure mode.

// public.decorator.ts
export const IS_PUBLIC_KEY = 'isPublic';
export const Public = () => SetMetadata(IS_PUBLIC_KEY, true);

// jwt-auth.guard.ts
@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {
  constructor(private reflector: Reflector) {
    super();
  }

  canActivate(context: ExecutionContext) {
    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
      context.getHandler(),
      context.getClass(),
    ]);
    if (isPublic) return true; // @Public() route -> skip JWT verification
    return super.canActivate(context); // else run AuthGuard('jwt')
  }
}

// app.module.ts — bind the guard globally
providers: [{ provide: APP_GUARD, useClass: JwtAuthGuard }],

Now POST /login and GET /health carry @Public(); everything else demands a valid Bearer token. The flow end to end:

What req.user holds after each guard

The two guards populate req.user from different sources, and conflating them is a common bug. After LocalAuthGuard, req.user is whatever LocalStrategy.validate() returned — the freshly-loaded database user. After JwtAuthGuard, req.user is whatever JwtStrategy.validate(payload) returned — derived from the token’s claims, not a database read. If a user’s roles change after the token is issued, a JWT-authenticated request still sees the old claims until the token expires.