Authentication in NestJS

This chapter follows MongoDB with Mongoose in NestJS.

Authentication answers “who is making this request?”. In a Nest app the answer is produced by a guard, because a guard runs before the handler, can reject the request, and can see which routes are marked public. The guard puts the authenticated user on request.user, where later guards, interceptors, and handlers can read it. Passport supplies the actual checks as interchangeable strategies, and @nestjs/passport turns each strategy into a Nest guard.

How the pieces fit

The setup below has two flows. Signing in exchanges an email and password for a JSON Web Token. Every later request sends that token in the Authorization header.

Diagram 1

sequenceDiagram
  participant Client
  participant Local as LocalAuthGuard
  participant Jwt as JwtAuthGuard
  participant Auth as AuthService
  participant Handler as Route handler
  Client->>Local: POST /auth/login with email and password
  Local->>Auth: validateUser(email, password)
  Auth-->>Local: user or null
  Local->>Handler: request.user is set
  Handler-->>Client: accessToken
  Client->>Jwt: GET /cats with Bearer token
  Jwt->>Jwt: verify signature and expiry
  Jwt->>Handler: request.user from token payload
  Handler-->>Client: 200 with data

The token is signed, not encrypted. Anyone holding it can read the payload, so it carries an ID and roles, never a password or other secrets. JWT, JWS, JWE, and JOSE explains the format.

Installing Passport and JWT

1
pnpm add @nestjs/passport passport passport-local @nestjs/jwt passport-jwt argon2
2
pnpm add -D @types/passport-local @types/passport-jwt

argon2 hashes passwords. Users are stored with a hash, never with the password itself, and a sign-in compares against the hash.

Checking credentials with the local strategy

AuthService holds the logic. It looks the user up and verifies the password:

1
import { Injectable } from '@nestjs/common';
2
import { JwtService } from '@nestjs/jwt';
3
import * as argon2 from 'argon2';
4
import { UsersService } from '../users/users.service';
5
import type { AuthUser } from './auth-user';
6

7
@Injectable()
8
export class AuthService {
9
  constructor(
10
    private readonly users: UsersService,
11
    private readonly jwt: JwtService,
12
  ) {}
13

14
  async validateUser(email: string, password: string): Promise<AuthUser | null> {
15
    const user = await this.users.findByEmail(email);
16
    if (!user || !(await argon2.verify(user.passwordHash, password))) return null;
17
    return { id: user.id, email: user.email, roles: user.roles };
18
  }
19

20
  login(user: AuthUser) {
21
    return { accessToken: this.jwt.sign({ sub: user.id, email: user.email, roles: user.roles }) };
22
  }
23
}

A strategy class connects Passport to it. PassportStrategy(Strategy) registers the strategy under its default name, local. The options go to super(), and the object validate() returns becomes request.user:

1
import { Injectable, UnauthorizedException } from '@nestjs/common';
2
import { PassportStrategy } from '@nestjs/passport';
3
import { Strategy } from 'passport-local';
4
import { AuthService } from './auth.service';
5
import type { AuthUser } from './auth-user';
6

7
@Injectable()
8
export class LocalStrategy extends PassportStrategy(Strategy) {
9
  constructor(private readonly auth: AuthService) {
10
    super({ usernameField: 'email' });
11
  }
12

13
  async validate(email: string, password: string): Promise<AuthUser> {
14
    const user = await this.auth.validateUser(email, password);
15
    if (!user) throw new UnauthorizedException('Invalid email or password');
16
    return user;
17
  }
18
}

The error message deliberately does not say whether the email or the password was wrong, so the endpoint cannot be used to discover which emails have accounts.

Issuing a JWT

AuthGuard('local') from @nestjs/passport is the guard that runs the strategy. A named subclass avoids repeating the string:

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

4
@Injectable()
5
export class LocalAuthGuard extends AuthGuard('local') {}

The login route only runs when the guard has accepted the credentials, so the handler just signs a token for request.user:

1
import { Controller, HttpCode, Post, Req, UseGuards } from '@nestjs/common';
2
import type { Request } from 'express';
3
import { AuthService } from './auth.service';
4
import type { AuthUser } from './auth-user';
5
import { LocalAuthGuard } from './local-auth.guard';
6
import { Public } from './public.decorator';
7

8
@Controller('auth')
9
export class AuthController {
10
  constructor(private readonly auth: AuthService) {}
11

12
  @Public()
13
  @UseGuards(LocalAuthGuard)
14
  @Post('login')
15
  @HttpCode(200)
16
  login(@Req() req: Request & { user: AuthUser }) {
17
    return this.auth.login(req.user);
18
  }
19
}

JwtModule signs with a secret from configuration. The same secret verifies the token later:

1
import { Module } from '@nestjs/common';
2
import { ConfigService } from '@nestjs/config';
3
import { APP_GUARD } from '@nestjs/core';
4
import { JwtModule } from '@nestjs/jwt';
5
import { PassportModule } from '@nestjs/passport';
6
import { UsersModule } from '../users/users.module';
7
import { AuthController } from './auth.controller';
8
import { AuthService } from './auth.service';
9
import { JwtAuthGuard } from './jwt-auth.guard';
10
import { JwtStrategy } from './jwt.strategy';
11
import { LocalStrategy } from './local.strategy';
12

13
@Module({
14
  imports: [
15
    UsersModule,
16
    PassportModule,
17
    JwtModule.registerAsync({
18
      inject: [ConfigService],
19
      useFactory: (config: ConfigService) => ({
20
        secret: config.getOrThrow<string>('JWT_SECRET'),
21
        signOptions: { expiresIn: '15m' },
22
      }),
23
    }),
24
  ],
25
  controllers: [AuthController],
26
  providers: [AuthService, LocalStrategy, JwtStrategy, { provide: APP_GUARD, useClass: JwtAuthGuard }],
27
})
28
export class AuthModule {}

A short lifetime limits the damage of a leaked token, since a JWT cannot be withdrawn once issued. Longer sessions add a refresh token, stored server-side so that it can be revoked.

Validating the JWT on later requests

The JWT strategy reads the bearer token, checks its signature and expiry, and only then calls validate() with the decoded payload:

1
import { Injectable } from '@nestjs/common';
2
import { ConfigService } from '@nestjs/config';
3
import { PassportStrategy } from '@nestjs/passport';
4
import { ExtractJwt, Strategy } from 'passport-jwt';
5
import type { AuthUser } from './auth-user';
6

7
interface JwtPayload {
8
  sub: string;
9
  email: string;
10
  roles: AuthUser['roles'];
11
}
12

13
@Injectable()
14
export class JwtStrategy extends PassportStrategy(Strategy) {
15
  constructor(config: ConfigService) {
16
    super({
17
      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
18
      ignoreExpiration: false,
19
      secretOrKey: config.getOrThrow<string>('JWT_SECRET'),
20
    });
21
  }
22

23
  validate(payload: JwtPayload): AuthUser {
24
    return { id: payload.sub, email: payload.email, roles: payload.roles };
25
  }
26
}

By the time validate() runs, the token is known to be genuine and current. It is the place to look the user up again if the app needs fresh data, or to check a list of revoked token IDs. A request with a missing, expired, or tampered token is rejected with 401 before any handler runs.

Protecting every route by default

Putting @UseGuards(JwtAuthGuard) on each controller works until someone forgets one. The safer default is the global guard registered with APP_GUARD in AuthModule above, combined with a decorator that marks the few public routes:

1
import { SetMetadata } from '@nestjs/common';
2

3
export const IS_PUBLIC_KEY = 'isPublic';
4
export const Public = () => SetMetadata(IS_PUBLIC_KEY, true);

1
import { ExecutionContext, Injectable } from '@nestjs/common';
2
import { Reflector } from '@nestjs/core';
3
import { AuthGuard } from '@nestjs/passport';
4
import { IS_PUBLIC_KEY } from './public.decorator';
5

6
@Injectable()
7
export class JwtAuthGuard extends AuthGuard('jwt') {
8
  constructor(private readonly reflector: Reflector) {
9
    super();
10
  }
11

12
  canActivate(context: ExecutionContext) {
13
    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
14
      context.getHandler(),
15
      context.getClass(),
16
    ]);
17
    return isPublic || super.canActivate(context);
18
  }
19
}

The login route carries @Public(), so the global JWT guard lets it through and the route’s own LocalAuthGuard checks the password instead. A new controller is protected the moment it exists. For GraphQL resolvers the same guard has to read the request through GqlExecutionContext by overriding getRequest(), as described in Authentication and authorization in GraphQL.

Knowing who the user is does not yet say what they may do. That is the next chapter.

Next: Authorization in NestJS.