Les guards déterminent si une requête est autorisée à procéder vers le gestionnaire de route — ils sont le mécanisme dédié de NestJS pour l'autorisation (et souvent les vérifications d'authentification). Un guard retourne true pour autoriser la requête ou false/lève une exception pour la bloquer.
@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 implémente canActivate(), qui retourne un booléen (ou une Promise/Observable de celui-ci). Retourner false bloque la requête avec un 403 ; vous pouvez également lever une exception spécifique (p. ex. 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)
Les guards peuvent être appliqués au niveau de la méthode, du contrôleur ou global.
@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
}
}
Combiner un décorateur @Roles() (métadonnées) avec un guard qui le lit (via Reflector) est le modèle standard pour le contrôle d'accès basé sur les rôles.
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.
Les guards sont le mécanisme dédié et idiomatic de NestJS pour l'autorisation — contrôler quelles requêtes sont autorisées à atteindre les gestionnaires en fonction de l'authentification et des permissions.
Les comprendre est essentiel car pratiquement toute application réelle doit protéger les routes (exiger la connexion, vérifier les rôles/permissions), et les guards sont l'outil correct pour cela (beaucoup plus propre que d'entasser la logique d'authentification dans les middleware ou chaque gestionnaire).
Les modèles standards — un guard JWT/authentification qui vérifie les identifiants et attache l'utilisateur à la requête, et les guards basés sur les rôles combinant un décorateur @Roles() avec un guard lisant via Reflector pour le RBAC — sont fondamentaux pour sécuriser les API NestJS.
L'accès des guards au riche ExecutionContext (connaître le gestionnaire cible, la classe et la requête) est précisément ce qui les rend adaptés aux décisions d'autorisation que les middleware ne peuvent pas gérer proprement.
Savoir comment écrire, appliquer (méthode/contrôleur/global) et combiner les guards avec les décorateurs de métadonnées est une connaissance fondamentale pour construire des applications NestJS sécurisées et un sujet fréquent et architecturalement important dans le framework.