Guards in NestJS

This chapter follows Middleware in NestJS.

Guards run after middleware and before interceptors and pipes. A guard returns true to let the request through or false to stop it, and it has one advantage over middleware: it knows which handler is about to run. That makes guards the home for authentication and authorization, and for any rule that depends on what a particular route declares about itself.

The CanActivate contract

A guard is a provider that implements CanActivate. Its canActivate() method may return a boolean, a Promise of one, or an Observable of one, so it can look things up before deciding.

1
import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
2
import { ConfigService } from '@nestjs/config';
3
import type { Request } from 'express';
4

5
@Injectable()
6
export class ApiKeyGuard implements CanActivate {
7
  constructor(private readonly config: ConfigService) {}
8

9
  canActivate(context: ExecutionContext): boolean {
10
    const request = context.switchToHttp().getRequest<Request>();
11
    return request.header('x-api-key') === this.config.getOrThrow<string>('API_KEY');
12
  }
13
}

When the guard returns false, Nest throws a ForbiddenException, and the client gets 403 Forbidden. To send a different status, throw it from the guard yourself. An authentication guard usually throws UnauthorizedException, so the client receives 401 and knows to sign in.

The ExecutionContext

The context argument is what separates guards from middleware. It wraps the arguments of the current call and adds two methods:

• getHandler() returns the route method that will run, for example CatsController.prototype.create.
• getClass() returns the controller class.

switchToHttp() gives access to the request and response. The same guard can serve other transports: switchToRpc() for microservices, switchToWs() for WebSockets, and GqlExecutionContext.create(context) from @nestjs/graphql for resolvers. context.getType() tells you which one you are in.

Steering a guard with metadata

Because a guard knows the handler, a decorator on that handler can configure it. Reflector.createDecorator() creates a typed decorator and a key to read it back with:

1
import { Reflector } from '@nestjs/core';
2

3
export const RequiresFeature = Reflector.createDecorator<string>();

1
import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
2
import { Reflector } from '@nestjs/core';
3
import { FeatureFlags } from './feature-flags.service';
4
import { RequiresFeature } from './feature-flag.decorator';
5

6
@Injectable()
7
export class FeatureFlagGuard implements CanActivate {
8
  constructor(
9
    private readonly reflector: Reflector,
10
    private readonly flags: FeatureFlags,
11
  ) {}
12

13
  canActivate(context: ExecutionContext): boolean {
14
    const feature = this.reflector.getAllAndOverride(RequiresFeature, [
15
      context.getHandler(),
16
      context.getClass(),
17
    ]);
18
    return feature === undefined || this.flags.isEnabled(feature);
19
  }
20
}

getAllAndOverride() checks the handler first and falls back to the class, so a method-level decorator overrides one on the controller. getAllAndMerge() combines both instead, which suits lists such as roles. The same pattern drives the @Public() and @Roles() decorators in Authentication in NestJS and Authorization in NestJS.

Binding guards

@UseGuards() binds guards to one controller or one route. Pass the class rather than an instance, so Nest creates it through the injector and its dependencies are resolved:

1
@Controller('cats')
2
@UseGuards(ApiKeyGuard)
3
export class CatsController {
4
  @Post('import')
5
  @RequiresFeature('bulk-import')
6
  @UseGuards(FeatureFlagGuard)
7
  import() {}
8
}

For a guard that protects everything, register it as a provider with the APP_GUARD token. It then runs for every route in the application, whichever module the provider is declared in:

1
import { APP_GUARD } from '@nestjs/core';
2

3
@Module({
4
  providers: [
5
    { provide: APP_GUARD, useClass: ApiKeyGuard },
6
    { provide: APP_GUARD, useClass: FeatureFlagGuard },
7
  ],
8
})
9
export class AppModule {}

Global guards run first, in the order they are registered, then controller guards, then route guards. All of them must pass. A guard cannot let a request through that an earlier guard rejected.

Guards and the rest of the pipeline

Guards run before pipes, so the body has not been validated yet when a guard reads it. Base a decision on headers, the authenticated user, or route parameters, and leave body checks to the pipes. Guards also run before interceptors, so a rejected request never reaches a logging or caching interceptor. If you need to log denied requests, log in the guard or in an exception filter.

Next: Interceptors in NestJS.