Guards and Roles
Utilize NestJS Guards to protect routes and implement role-based access control (RBAC) to manage user permissions.
Guards and Roles is a free Next.js 15 Fullstack (App Router + Server Actions) lesson on CoddyKit — lesson 4 of 6. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Next.js 15 Fullstack (App Router + Server Actions) learning path, one of 6 lessons in the course, and your progress syncs across the web and the CoddyKit app.
What are NestJS Guards?
In NestJS, Guards are special classes that decide if a given request should be processed by the route handler. Think of them as gatekeepers!
They sit between the incoming request and your application's logic, making authorization decisions.
- Authorization: Who is allowed to do what?
- Authentication: Who is this user? (Often handled before guards, but guards can confirm it).
Building a Basic Guard
All NestJS Guards must implement the CanActivate interface. This interface requires a single method: canActivate().
The canActivate() method returns a boolean, a Promise<boolean>, or an Observable<boolean>. If it returns true, the request proceeds; if false, it's blocked.
import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
import { Observable } from 'rxjs';
@Injectable()
export class AuthGuard implements CanActivate {
canActivate(
context: ExecutionContext,
): boolean | Promise<boolean> | Observable<boolean> {
// Logic to determine if user is authorized
// For now, let's just allow it
return true;
}
}A Simple Authentication Check
Let's make our AuthGuard actually do something! We'll simulate checking if a user is 'logged in' by looking for a specific header.
The ExecutionContext provides access to the request, response, and more, allowing us to inspect the incoming request.
import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
import { Observable } from 'rxjs';
@Injectable()
export class BasicAuthGuard implements CanActivate {
canActivate(
context: ExecutionContext,
): boolean | Promise<boolean> | Observable<boolean> {
const request = context.switchToHttp().getRequest();
// In a real app, you'd check JWT, session, etc.
// For this example, we check a simple header.
const hasAuthHeader = request.headers['authorization'] === 'Bearer secret-token';
return hasAuthHeader; // Only allow if header is correct
}
}Protecting Your Endpoints
To apply a guard, you use the @UseGuards() decorator. You can apply it to a single route handler or to an entire controller.
When applied to a controller, all routes within that controller will be protected by the guard.
import { Controller, Get, UseGuards } from '@nestjs/common';
import { BasicAuthGuard } from './common/guards/auth.guard';
@Controller('protected')
@UseGuards(BasicAuthGuard) // Protects all routes in this controller
export class ProtectedController {
@Get()
getProtectedData(): string {
return 'This data is protected!';
}
@Get('public')
getAnotherProtectedData(): string {
return 'More protected data.';
}
}
// src/app.module.ts
import { Module } from '@nestjs/common';
import { ProtectedController } from './app.controller';
@Module({
controllers: [ProtectedController],
providers: [],
})
export class AppModule {}
// src/main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
async function bootstrap() {
const app = await NestFactory.create(AppModule);
await app.listen(3000);
console.log('App running on http://localhost:3000');
}
bootstrap();Understanding RBAC
While basic authentication checks if a user is who they say they are, Role-Based Access Control (RBAC) checks what they are allowed to do.
With RBAC, users are assigned roles (e.g., 'admin', 'editor', 'viewer'), and permissions are granted to roles, not individual users.
- Role: A collection of permissions (e.g., 'admin' can 'create', 'read', 'update', 'delete').
- User: Assigned one or more roles.
- Resource: The data or functionality being accessed.
Marking Routes with Roles
To implement RBAC, we need a way to tell our guard which roles are allowed for a specific route. NestJS allows us to create custom decorators for this!
We'll create an @Roles() decorator to attach role metadata to our route handlers.
import { SetMetadata } from '@nestjs/common';
export const ROLES_KEY = 'roles';
export const Roles = (...roles: string[]) => SetMetadata(ROLES_KEY, roles);
// Example usage in a controller:
// @Roles('admin', 'editor')
// @Get('admin-only')
// someAdminMethod() { ... }The Roles Guard Logic
Now, let's build our RolesGuard. This guard will:
- Get the required roles from the route's metadata using the
Reflector. - Get the user's roles (e.g., from the request object after authentication).
- Compare them to see if the user has any of the required roles.
import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { Observable } from 'rxjs';
import { ROLES_KEY } from '../decorators/roles.decorator';
@Injectable()
export class RolesGuard implements CanActivate {
constructor(private reflector: Reflector) {}
canActivate(
context: ExecutionContext,
): boolean | Promise<boolean> | Observable<boolean> {
const requiredRoles = this.reflector.getAllAndOverride<string[]>(ROLES_KEY, [
context.getHandler(),
context.getClass(),
]);
if (!requiredRoles) {
return true; // No roles defined, so access is allowed by default
}
const request = context.switchToHttp().getRequest();
// In a real app, 'user' would come from an authentication guard
// and contain actual user data including roles.
const user = request.user || { roles: ['viewer'] }; // Dummy user for example
const hasPermission = requiredRoles.some((role) => user.roles.includes(role));
return hasPermission;
}
}Stacking Guards for Protection
You can use multiple guards on a single route or controller. NestJS executes guards in the order they are listed in the @UseGuards() decorator.
If any guard returns false, the request is immediately blocked, and subsequent guards (and the route handler) are not executed.
- First: Authentication (Is the user logged in?)
- Second: Authorization (Does the user have the right role?)
Applying Guards and Roles
Let's see how our BasicAuthGuard, RolesGuard, and @Roles() decorator work together to protect an endpoint.
We'll simulate a user with the 'admin' role.
import { Controller, Get, UseGuards, Req } from '@nestjs/common';
import { BasicAuthGuard } from './common/guards/auth.guard';
import { RolesGuard } from './common/guards/roles.guard';
import { Roles } from './common/decorators/roles.decorator';
// Assume this comes from a real authentication process
interface User {
username: string;
roles: string[];
}
@Controller('admin')
@UseGuards(BasicAuthGuard, RolesGuard) // Guards applied in order
export class AdminController {
@Get('dashboard')
@Roles('admin') // Only users with 'admin' role can access
getAdminDashboard(@Req() req): string {
// For this runnable example's context, manually set user.
// In a real app, BasicAuthGuard would populate req.user.
req.user = { username: 'testuser', roles: ['admin'] };
return `Welcome to the Admin Dashboard, ${req.user.username}!`;
}
@Get('reports')
@Roles('admin', 'editor') // Admins or Editors can access
getReports(@Req() req): string {
req.user = { username: 'editoruser', roles: ['editor'] };
return `Accessing reports as ${req.user.username}.`;
}
}
// src/app.module.ts
import { Module } from '@nestjs/common';
import { AdminController } from './app.controller';
@Module({
controllers: [AdminController],
providers: [],
})
export class AppModule {}
// src/main.ts (unchanged from previous runnable example)
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
async function bootstrap() {
const app = await NestFactory.create(AppModule);
await app.listen(3000);
console.log('Admin app running on http://localhost:3000');
}
bootstrap();Guard & Role Check
Consider a NestJS route protected by @UseGuards(AuthGuard, RolesGuard) and @Roles('admin', 'moderator').
If a request comes in with a valid authentication token (passed by AuthGuard), but the authenticated user has only the role 'viewer', what will happen?
Guards & Roles Summary
Great job! In this lesson, you learned about:
- NestJS Guards: Gatekeepers that implement
CanActivateto control route access. @UseGuards(): Decorator to apply guards at controller or method level.- Role-Based Access Control (RBAC): Managing permissions based on user roles.
- Custom Decorators: Using
@SetMetadata()to attach custom data (like roles) to routes. Reflector: Used by guards to read metadata from routes.
Guards are powerful for authorization. Next, you might explore how to integrate Passport.js strategies for more robust authentication!
Frequently asked questions
Is the “Guards and Roles” lesson free?
Yes — the full text of “Guards and Roles” is free to read here on the web, and the Next.js 15 Fullstack (App Router + Server Actions) course includes 6 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Next.js 15 Fullstack (App Router + Server Actions) course, upgrade to CoddyKit PRO.
What will I learn in “Guards and Roles”?
Utilize NestJS Guards to protect routes and implement role-based access control (RBAC) to manage user permissions. You practise Next.js 15 Fullstack (App Router + Server Actions) with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start Next.js 15 Fullstack (App Router + Server Actions)?
No prior experience is required. Next.js 15 Fullstack (App Router + Server Actions) on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 6, so you can start here or from the beginning and move at your own pace.
How long does the “Guards and Roles” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this Next.js 15 Fullstack (App Router + Server Actions) lesson?
Yes. Every Next.js 15 Fullstack (App Router + Server Actions) lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.