Role-Based Authorization

Introduction: Why Role-Based Authorization?

Welcome back! In the last lesson, you learned how to protect your API routes so that only authenticated users with a valid JWT can access them. That’s a great start, but in most real-world applications, not all users should have the same permissions. For example, you might want only administrators to be able to delete books or update user information, while regular users can only view data. In the previous unit we only had JwtAuthGuard : any authenticated user could perform mutations (create/update/delete). That’s intentionally incomplete. In this unit we’ll require roles for sensitive actions. To make this concrete now, we’ll use an admin role (you already have a seeded admin user). In the SPA playground provided with the course you can try both a normal user and an admin; later, in the frontend path, you’ll build your own React UI . This is where role-based authorization comes in. With role-based authorization, you can control what actions different types of users can perform in your API. In this lesson, you’ll learn how to implement this in your NestJS project so you can restrict certain endpoints to users with specific roles, like admin or user .

Quick Recap: Our API Structure

Before we dive in, let’s quickly remind ourselves of the current setup. You already have: Registration (bcrypt hashes stored). JWT Login (token with sub, role, iat, exp). JwtAuthGuard (only checks if the token is valid \to user is logged in). Here’s a simplified code block to show where we are, focusing on how user roles fit in: TypeScript // Example: Protecting a route with JwtAuthGuard @Patch(':id') @UseGuards(JwtAuthGuard) update(@Param('id', ParseUUIDPipe) id: string, @Body() updateBookDto: UpdateBookDto,) {const book = this.booksService.update(id, updateBookDto); return { success: true, data: book };} What’s wrong Any logged-in user can call write endpoints (e.g., create a book). That violates least-privilege. What we’ll add @Roles() decorator to declare required roles on a route. RolesGuard to enforce those requirements after JwtAuthGuard authenticates the user. BooksController write routes become admin-only (read routes remain public or authenticated as you decide).

Creating a Roles Decorator

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

// src/common/decorators/roles.decorator.ts import { SetMetadata } from '@nestjs/common'; export const ROLES_KEY = 'roles'; export type Role = 'user' | 'admin'; export const Roles = (...roles: Role[]) => SetMetadata(ROLES_KEY, roles);

// Admin-only write; keep reads open or auth-only: @Controller('books') export class BooksController { constructor(private readonly booksService: BooksService) {} @Post() @UseGuards(AuthGuard('jwt'), RolesGuard) @Roles('admin') // Create a new book entry (admin only) create(@Body() createBookDto: CreateBookDto) { const book = this.booksService.create(createBookDto); return { success: true, data: book }; } @Get() // Retrieve all books. No guards required here findAll() { const books = this.booksService.findAll(); return { success: true, data: books }; } //...rest of the methods }

Building and Using a Roles Guard

A guard in NestJS is a class that decides whether a request should be handled or rejected. We’ll create a RolesGuard that checks if the user’s role matches the required roles for an endpoint.

Here’s the code for the guard:

TypeScript

// src/common/guards/roles.guard.ts
import { CanActivate, ExecutionContext, ForbiddenException, Injectable } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { ROLES_KEY, Role } from '../decorators/roles.decorator';

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

  canActivate(context: ExecutionContext): boolean {
    const required = this.reflector.getAllAndOverride<Role[]>(ROLES_KEY, [
      context.getHandler(),
      context.getClass(),
    ]);
    if (!required || required.length === 0) return true;

    const req = context.switchToHttp().getRequest() as any;
    const role = req.user?.role as Role | undefined;

    if (!role || !required.includes(role)) {
      throw new ForbiddenException('Insufficient role');
    }
    return true;
  }
}

// src/common/guards/roles.guard.ts
import { CanActivate, ExecutionContext, ForbiddenException, Injectable } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { ROLES_KEY, Role } from '../decorators/roles.decorator';

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

  canActivate(context: ExecutionContext): boolean {
    const required = this.reflector.getAllAndOverride<Role[]>(ROLES_KEY, [
      context.getHandler(),
      context.getClass(),
    ]);
    if (!required || required.length === 0) return true;

    const req = context.switchToHttp().getRequest() as any;
    const role = req.user?.role as Role | undefined;

    if (!role || !required.includes(role)) {
      throw new ForbiddenException('Insufficient role');
    }
    return true;
  }
}

Explanation:

Reflector is used to read the metadata set by the @Roles() decorator.
canActivate is called before the route handler runs.
It checks if the endpoint has required roles. If not, it allows access.
It then checks the user’s role (from req.user.role).
If the user’s role is not in the required roles, it throws a ForbiddenException.
If the role matches, the request is allowed.

What happens if a user without the right role tries to access an endpoint?

They will get a response like:

JSON

{
  "statusCode": 403,
  "message": "Insufficient role",
  "error": "Forbidden"
}

{
  "statusCode": 403,
  "message": "Insufficient role",
  "error": "Forbidden"
}

Important: Order matters. use @UseGuards(JwtAuthGuard, RolesGuard) so authentication happens first, then authorization. Why getAllAndOverride? It checks metadata on the handler first, then on the controller, and returns the first non-undefined value. That lets you set a default policy at the controller level and override per route.

Applying Role-Based Authorization in Controllers

Now, let’s see how to use the @Roles() decorator and RolesGuard in your controllers. You’ll combine them with the JwtAuthGuard to make sure only authenticated users with the right role can access certain endpoints.

Here’s an example from the Books controller:

TypeScript

// src/books/books.controller.ts
import {
  Controller,
  Get,
  Post,
  Body,
  Patch,
  Param,
  Delete,
  ParseUUIDPipe,
  UseGuards,
} from '@nestjs/common';
import { BooksService } from './books.service';
import { CreateBookDto } from './dto/create-book.dto';
import { UpdateBookDto } from './dto/update-book.dto';
import { AuthGuard } from '@nestjs/passport';
import { Roles } from '../common/decorators/roles.decorator';
import { RolesGuard } from '../common/guards/roles.guard';

@Controller('books')
export class BooksController {
  constructor(private readonly booksService: BooksService) {}

  @Post()
  @UseGuards(AuthGuard('jwt'), RolesGuard)
  @Roles('admin')
  // Create a new book entry (admin only)
  create(@Body() createBookDto: CreateBookDto) {
    const book = this.booksService.create(createBookDto);
    return { success: true, data: book };
  }

  @Get()
  // Retrieve all books
  findAll() {
    const books = this.booksService.findAll();
    return { success: true, data: books };
  }

  @Get(':id')
  // Retrieve a specific book by ID
  findOne(@Param('id', ParseUUIDPipe) id: string) {
    const book = this.booksService.findOne(id);
    return { success: true, data: book };
  }

  @Patch(':id')
  @UseGuards(AuthGuard('jwt'), RolesGuard)
  @Roles('admin')
  // Update a book's data (admin only)
  update(
    @Param('id', ParseUUIDPipe) id: string,
    @Body() updateBookDto: UpdateBookDto,
  ) {
    const book = this.booksService.update(id, updateBookDto);
    return { success: true, data: book };
  }

  @Delete(':id')
  @UseGuards(AuthGuard('jwt'), RolesGuard)
  @Roles('admin')
  // Remove a book by ID (admin only)
  remove(@Param('id', ParseUUIDPipe) id: string) {
    const removed = this.booksService.remove(id);
    return { success: true, data: removed };
  }
}

// src/books/books.controller.ts
import {
  Controller,
  Get,
  Post,
  Body,
  Patch,
  Param,
  Delete,
  ParseUUIDPipe,
  UseGuards,
} from '@nestjs/common';
import { BooksService } from './books.service';
import { CreateBookDto } from './dto/create-book.dto';
import { UpdateBookDto } from './dto/update-book.dto';
import { AuthGuard } from '@nestjs/passport';
import { Roles } from '../common/decorators/roles.decorator';
import { RolesGuard } from '../common/guards/roles.guard';

@Controller('books')
export class BooksController {
  constructor(private readonly booksService: BooksService) {}

  @Post()
  @UseGuards(AuthGuard('jwt'), RolesGuard)
  @Roles('admin')
  // Create a new book entry (admin only)
  create(@Body() createBookDto: CreateBookDto) {
    const book = this.booksService.create(createBookDto);
    return { success: true, data: book };
  }

  @Get()
  // Retrieve all books
  findAll() {
    const books = this.booksService.findAll();
    return { success: true, data: books };
  }

  @Get(':id')
  // Retrieve a specific book by ID
  findOne(@Param('id', ParseUUIDPipe) id: string) {
    const book = this.booksService.findOne(id);
    return { success: true, data: book };
  }

  @Patch(':id')
  @UseGuards(AuthGuard('jwt'), RolesGuard)
  @Roles('admin')
  // Update a book's data (admin only)
  update(
    @Param('id', ParseUUIDPipe) id: string,
    @Body() updateBookDto: UpdateBookDto,
  ) {
    const book = this.booksService.update(id, updateBookDto);
    return { success: true, data: book };
  }

  @Delete(':id')
  @UseGuards(AuthGuard('jwt'), RolesGuard)
  @Roles('admin')
  // Remove a book by ID (admin only)
  remove(@Param('id', ParseUUIDPipe) id: string) {
    const removed = this.booksService.remove(id);
    return { success: true, data: removed };
  }
}

Explanation:

@UseGuards(JwtAuthGuard, RolesGuard) applies both guards to the endpoint.
@Roles('admin') marks this endpoint as admin-only.
Only authenticated users with the admin role can create books.

Here’s another example from the Users controller:

TypeScript

// src/users/users.controller.ts

//...other endpoints 

@Patch(':id')
// Update an existing user
@UseGuards(AuthGuard('jwt'), RolesGuard)
@Roles('admin')
update(@Param('id', ParseUUIDPipe) id: string, @Body() updateUserDto: UpdateUserDto) {
    const user = this.usersService.update(id, updateUserDto);
    return { success: true, data: user };
}

// src/users/users.controller.ts

//...other endpoints 

@Patch(':id')
// Update an existing user
@UseGuards(AuthGuard('jwt'), RolesGuard)
@Roles('admin')
update(@Param('id', ParseUUIDPipe) id: string, @Body() updateUserDto: UpdateUserDto) {
    const user = this.usersService.update(id, updateUserDto);
    return { success: true, data: user };
}

Explanation:

Only admins can update user information.
If a regular user tries to access this endpoint, they will get a 403 Forbidden error.

Introduction: Why Role-Based Authorization?

Quick Recap: Our API Structure

Creating a Roles Decorator

Join the 1M+ learners on CodeSignal

Building and Using a Roles Guard

Applying Role-Based Authorization in Controllers

Try it in terminal (and in the SPA playground)

Summary And Practice Preview