NestJS Guards Pattern

NestJS Guards Pattern

Protect routes with @UseGuards, CanActivate, JWT guards, and role-based access control

When to Use

• You need to verify authentication before a handler executes (JWT, API key, session)
• You need role-based or permission-based access control on specific routes
• You want to centralize authentication logic instead of repeating it in every controller method
• You need to read the current user from the token and attach it to the request

Instructions

1. Implement CanActivate and return true (allow) or false/throw (deny):

@Injectable()
export class JwtAuthGuard implements CanActivate {
  constructor(private jwtService: JwtService) {}

  canActivate(context: ExecutionContext): boolean {
    const request = context.switchToHttp().getRequest<Request>();
    const token = this.extractToken(request);
    if (!token) throw new UnauthorizedException();
    try {
      request['user'] = this.jwtService.verify(token, { secret: process.env.JWT_SECRET });
      return true;
    } catch {
      throw new UnauthorizedException();
    }
  }

  private extractToken(req: Request): string | undefined {
    const [type, token] = req.headers.authorization?.split(' ') ?? [];
    return type === 'Bearer' ? token : undefined;
  }
}

2. Apply guards with @UseGuards(GuardClass) at the controller or handler level. Handler-level overrides controller-level.
3. Apply globally in main.ts for app-wide auth: app.useGlobalGuards(new JwtAuthGuard(jwtService)). For DI in global guards, use APP_GUARD provider instead:

providers: [{ provide: APP_GUARD, useClass: JwtAuthGuard }];

4. Use Reflector and custom decorators to build a roles guard:

export const Roles = (...roles: string[]) => SetMetadata('roles', roles);

@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    const required = this.reflector.getAllAndOverride<string[]>('roles', [
      context.getHandler(),
      context.getClass(),
    ]);
    if (!required) return true; // no roles required
    const { user } = context.switchToHttp().getRequest();
    return required.some((role) => user?.roles?.includes(role));
  }
}

5. Use @Public() with a SetMetadata('isPublic', true) decorator to bypass global auth guards on specific routes.
6. ExecutionContext is transport-agnostic — use context.switchToWs() for WebSockets and context.switchToRpc() for microservices.

Details

Guards run after middleware but before interceptors and pipes in the NestJS request lifecycle. They are the correct place for authorization decisions because they have access to ExecutionContext, which provides the handler and class metadata.

Guard vs Middleware: Middleware runs before routing and has no knowledge of which handler will process the request. Guards run after routing with full handler context, making them the right tool for authorization logic that depends on route metadata (roles, permissions).

Throwing vs returning false: Throwing UnauthorizedException (or any HttpException) is preferred over returning false. Returning false causes NestJS to throw a generic ForbiddenException (403), which may not communicate the correct HTTP status.

Multiple guards: @UseGuards(AuthGuard, RolesGuard) applies guards in order. If AuthGuard throws, RolesGuard never runs. Compose authentication and authorization as separate guards for clean separation of concerns.

Passport integration: @nestjs/passport provides AuthGuard('jwt'), AuthGuard('local'), etc. that wrap Passport strategies. Use it when you need OAuth2, SAML, or complex multi-strategy auth flows.

Source

https://docs.nestjs.com/guards

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.