I guard determinano se una richiesta è autorizzata a procedere verso l'handler della route — sono il meccanismo dedicato di NestJS per l'autorizzazione (e spesso anche per i controlli di autenticazione). Un guard restituisce true per autorizzare la richiesta o false/lancia un'eccezione per bloccarla.
@Injectable()
export class AuthGuard implements CanActivate {
canActivate(context: ExecutionContext): boolean {
const request = context.switchToHttp().getRequest();
return !!request.headers.authorization; // true = allow, false = block (403)
}
}
Un guard implementa canActivate(), che restituisce un booleano (o una Promise/Observable di uno). Restituire false blocca la richiesta con un 403; puoi anche lanciare un'eccezione specifica (ad es. UnauthorizedException).
@UseGuards(AuthGuard) // on a single route
@Get("profile")
getProfile() {}
@UseGuards(AuthGuard) // on a whole controller (all routes)
@Controller("admin")
export class AdminController {}
app.useGlobalGuards(new AuthGuard()); // globally (all routes)
I guard possono essere applicati a livello di metodo, controller o globale.
@Injectable()
export class JwtAuthGuard implements CanActivate {
constructor(private jwtService: JwtService) {}
async canActivate(context: ExecutionContext): Promise<boolean> {
const request = context.switchToHttp().getRequest();
const token = request.headers.authorization?.split(" ")[1];
if (!token) throw new UnauthorizedException();
try {
request.user = await this.jwtService.verifyAsync(token); // attach the user
return true;
} catch {
throw new UnauthorizedException("Invalid token");
}
}
}
// a @Roles decorator stores required roles as metadata
@Roles("admin")
@Get("users")
listUsers() {}
// the RolesGuard reads the metadata and checks the user's roles
@Injectable()
export class RolesGuard implements CanActivate {
constructor(private reflector: Reflector) {}
canActivate(ctx: ExecutionContext): boolean {
const roles = this.reflector.get<string[]>("roles", ctx.getHandler());
const { user } = ctx.switchToHttp().getRequest();
return roles.some(role => user.roles?.includes(role)); // allow if the user has a required role
}
}
Combinare un decoratore @Roles() (metadati) con un guard che lo legge (tramite Reflector) è il pattern standard per il controllo degli accessi basato su ruoli.
The ExecutionContext gives guards rich info (the handler, class, request) — more
than plain middleware — which is why guards (not middleware) are the right place
for authorization decisions.
I guard sono il meccanismo dedicato e idiomatico di NestJS per l'autorizzazione — controllare quali richieste sono autorizzate a raggiungere gli handler in base all'autenticazione e alle autorizzazioni.
Comprenderli è essenziale perché praticamente ogni applicazione reale ha necessità di proteggere le route (richiedere il login, verificare ruoli/autorizzazioni), e i guard sono lo strumento corretto per questo (molto più pulito rispetto a inserire la logica di autenticazione nel middleware o in ogni handler).
I pattern standard — un guard JWT/autenticazione che verifica le credenziali e associa l'utente alla richiesta, e i guard basati su ruoli che combinano un decoratore @Roles() con un guard che legge con Reflector per RBAC — sono fondamentali per proteggere le API NestJS.
L'accesso dei guard al ricco ExecutionContext (conoscendo l'handler target, la classe e la richiesta) è esattamente ciò che li rende adatti a decisioni di autorizzazione che il middleware non può fare facilmente.
Saper scrivere, applicare (metodo/controller/globale) e combinare i guard con decoratori di metadati è una conoscenza fondamentale per costruire applicazioni NestJS sicure e un argomento frequente e architetturalmente importante nel framework.