Guard e ruoli
Utilizzi i Guard di NestJS per proteggere le route e implementi il controllo degli accessi basato sui ruoli (RBAC) per gestire le autorizzazioni degli utenti.
Guard e ruoli è una lezione Next.js 15 Fullstack (App Router + Server Actions) gratuita su CoddyKit. Questa è la lezione 4 di 6. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento Next.js 15 Fullstack (App Router + Server Actions), e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso Next.js 15 Fullstack (App Router + Server Actions) include 6 lezioni in totale.
Parti di questa lezione non sono ancora state tradotte e vengono mostrate in inglese.
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!
Impara TypeScript con un tutor IA — gratis
Scrivi ed esegui vero codice nel tuo browser, ricevi aiuto istantaneo da un tutor IA disponibile 24/7, e riprendi da dove hai lasciato sul web o nell'app.
- Corsi
- 22
- Lezioni
- 88
Domande Frequenti
La lezione «Guard e ruoli» è gratuita?
Sì — il testo completo di «Guard e ruoli» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso Next.js 15 Fullstack (App Router + Server Actions), passa a CoddyKit PRO. Il corso Next.js 15 Fullstack (App Router + Server Actions) include 6 lezioni in totale.
Cosa imparerò in «Guard e ruoli»?
Utilizzi i Guard di NestJS per proteggere le route e implementi il controllo degli accessi basato sui ruoli (RBAC) per gestire le autorizzazioni degli utenti. Eserciti Next.js 15 Fullstack (App Router + Server Actions) con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.
Ho bisogno di esperienza per iniziare Next.js 15 Fullstack (App Router + Server Actions)?
Non è richiesta alcuna esperienza precedente. Next.js 15 Fullstack (App Router + Server Actions) su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 4 di 6.
Quanto tempo richiede la lezione «Guard e ruoli»?
La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.
Posso scrivere ed eseguire codice in questa lezione Next.js 15 Fullstack (App Router + Server Actions)?
Sì. Ogni lezione Next.js 15 Fullstack (App Router + Server Actions) include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.
Tutte le lezioni di questo corso
- Integrare NextAuth.js
- Implementazione della strategia JWT
- Proteggere route e dati
- Guard e ruoli
- Strategie di autenticazione personalizzate
- Integrazione di Passport.js