Authorization in NestJS

This chapter follows Authentication in NestJS.

Authentication put a verified user on request.user. Authorization uses it to answer two different questions. The first is about the route: may a user with these roles call DELETE /cats/:id at all? A guard answers that before the handler runs, from metadata on the route. The second is about the data: may this user delete this cat? Only code that has loaded the cat can answer that, so it belongs in the service. Most authorization bugs come from answering only the first question.

Roles as metadata

Roles are a fixed list, and the routes declare which ones they need. Reflector.createDecorator() gives a typed decorator for that:

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

3
export enum Role {
4
  User = 'user',
5
  Admin = 'admin',
6
}
7

8
export const Roles = Reflector.createDecorator<Role[]>();

1
@Controller('cats')
2
export class CatsController {
3
  @Get()
4
  findAll() {}
5

6
  @Delete(':id')
7
  @Roles([Role.Admin])
8
  remove(@Param('id') id: string) {}
9
}

The decorator only stores data. Nothing is enforced until a guard reads it.

A roles guard

The guard reads the required roles from the handler, falling back to the controller, and compares them with the roles on the authenticated user:

1
import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
2
import { Reflector } from '@nestjs/core';
3
import type { AuthUser } from './auth-user';
4
import { Roles } from './roles';
5

6
@Injectable()
7
export class RolesGuard implements CanActivate {
8
  constructor(private readonly reflector: Reflector) {}
9

10
  canActivate(context: ExecutionContext): boolean {
11
    const required = this.reflector.getAllAndOverride(Roles, [context.getHandler(), context.getClass()]);
12
    if (!required?.length) return true;
13

14
    const { user } = context.switchToHttp().getRequest<{ user?: AuthUser }>();
15
    return required.some((role) => user?.roles.includes(role));
16
  }
17
}

A route without @Roles() is open to every authenticated user. Returning false makes Nest answer 403 Forbidden. That is the correct status here: the user is known but not allowed, which is different from the 401 that authentication sends for an unknown user.

Running guards in the right order

RolesGuard reads request.user, so it must run after the JWT guard has set it. Global guards run in the order they are registered. Registering both in the same module, in this order, makes the dependency explicit:

1
providers: [
2
  AuthService,
3
  LocalStrategy,
4
  JwtStrategy,
5
  { provide: APP_GUARD, useClass: JwtAuthGuard },
6
  { provide: APP_GUARD, useClass: RolesGuard },
7
],

Roles copied into the token at sign-in are a snapshot. Revoking a user’s admin role takes effect only when their token expires, unless JwtStrategy.validate() reloads the user on every request. Short token lifetimes keep that window small.

The current user as a parameter

Handlers that need the user should not reach for @Req() and the platform’s request type. A custom parameter decorator returns just the user:

1
import { createParamDecorator, ExecutionContext } from '@nestjs/common';
2
import type { AuthUser } from './auth-user';
3

4
export const CurrentUser = createParamDecorator(
5
  (_data: unknown, context: ExecutionContext): AuthUser =>
6
    context.switchToHttp().getRequest<{ user: AuthUser }>().user,
7
);

1
@Delete(':id')
2
@HttpCode(204)
3
remove(@Param('id') id: string, @CurrentUser() user: AuthUser) {
4
  return this.catsService.remove(id, user);
5
}

The controller now passes the user on as data, and the service does not depend on HTTP.

Checking ownership in the service

A guard cannot see which cat :id refers to without loading it, and loading data in a guard duplicates the service. The service already loads the cat, so it checks ownership there:

1
async remove(id: string, user: AuthUser): Promise<void> {
2
  const cat = await this.findOne(id);
3
  const isOwner = String(cat.owner) === user.id;
4
  if (!isOwner && !user.roles.includes(Role.Admin)) {
5
    throw new ForbiddenException('You can only delete your own cats');
6
  }
7
  await this.catModel.deleteOne({ _id: id }).exec();
8
}

The same applies to lists: findAll() for a normal user filters by owner in the query, rather than loading everything and filtering afterwards. Forgetting this check is the classic insecure direct object reference, where any signed-in user can read or change another user’s data by guessing an ID.

Beyond roles

Roles stay manageable while the rules are “admins may do everything, users may do some things”. When rules start to combine roles, ownership, and resource state (“editors may publish articles in their own team that are not archived”), a policy library keeps them in one place. @casl/ability is the common choice in Nest projects. An AbilityFactory provider builds the user’s permissions, and both a guard and the services ask it ability.can('update', cat). The two-level split stays the same: coarse checks in a guard from route metadata, fine checks wherever the resource is loaded.

Next: Testing NestJS applications.