À propos de ce cours
Objectifs de la leçon
- Expliquer le rôle d'un guard et sa place dans le cycle de requête.
- Écrire un guard avec CanActivate et ExecutionContext.
- Restreindre des routes par rôle avec des métadonnées et Reflector.
- Distinguer 401 et 403.
- Mettre en place un guard global avec des routes publiques.
Le rôle d'un guard
Un guard (« garde ») répond à une seule question : cette requête a-t-elle le droit d'exécuter cette route ? Il implémente CanActivate et sa méthode canActivate() renvoie true (la requête continue) ou false (NestJS répond 403). Contrairement à un middleware, il connaît le handler qui va être exécuté et peut lire ses métadonnées: c'est ce qui permet d'écrire @Roles(['admin']) au-dessus d'une route.
Deux guards successifs : identification, puis autorisation.
Un guard de clé API
nest g guard common/guards/cle-api --no-spec
📄 src/common/guards/cle-api.guard.ts
import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
import { Request } from 'express';
@Injectable()
export class CleApiGuard implements CanActivate {
canActivate(context: ExecutionContext): boolean {
const req = context.switchToHttp().getRequest<Request>();
return req.header('x-api-key') === (process.env.API_KEY ?? 'cle-de-demo'); // false → 403
}
}
ExecutionContext étend ArgumentsHost (leçon 9.3) avec deux méthodes précieuses : getHandler() (la méthode qui va être exécutée) et getClass() (son contrôleur).
Un guard de rôles
Il faut d'abord un moyen d'indiquer, sur chaque route, les rôles autorisés. Reflector.createDecorator() crée un décorateur qui enregistre une métadonnée typée :
📄 src/common/decorators/roles.decorator.ts
import { Reflector } from '@nestjs/core';
export type Role = 'admin' | 'formateur' | 'stagiaire';
// Décorateur qui attache la liste des rôles autorisés à une route (métadonnées)
export const Roles = Reflector.createDecorator<Role[]>();
📄 src/common/guards/roles.guard.ts
import { CanActivate, ExecutionContext, ForbiddenException, Injectable, UnauthorizedException } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { Request } from 'express';
import { Role, Roles } from './roles.decorator';
@Injectable()
export class RolesGuard implements CanActivate {
constructor(private readonly reflector: Reflector) {} // les guards peuvent injecter
canActivate(context: ExecutionContext): boolean {
// rôles demandés sur la méthode, sinon sur le contrôleur
const roles = this.reflector.getAllAndOverride(Roles, [context.getHandler(), context.getClass()]);
if (!roles || roles.length === 0) return true; // route sans restriction
const req = context.switchToHttp().getRequest<Request>();
const role = req.header('x-role') as Role | undefined; // simulation : l'authentification réelle arrive au chapitre 13
if (!role) throw new UnauthorizedException('Authentification requise');
if (!roles.includes(role)) {
throw new ForbiddenException(`Rôle « ${role} » insuffisant (attendu : ${roles.join(' ou ')})`);
}
return true;
}
}
getAllAndOverride(Roles, [handler, classe]) cherche la métadonnée sur la méthode, puis sur le contrôleur : un @Roles de méthode remplace celui du contrôleur. (getAllAndMerge fusionnerait les deux listes.)
📄 src/notes.controller.ts
import { Controller, Delete, Get, Param, ParseIntPipe, Post, UseGuards } from '@nestjs/common';
import { CleApiGuard } from './cle-api.guard';
import { Roles } from './roles.decorator';
import { RolesGuard } from './roles.guard';
@Controller('notes')
@UseGuards(CleApiGuard, RolesGuard) // dans cet ordre, pour toutes les routes
export class NotesController {
@Get()
lister() {
return ['SQL : 15', 'JS : 12']; // aucune restriction de rôle
}
@Post()
@Roles(['formateur', 'admin'])
ajouter() {
return { ajoutee: true };
}
@Delete(':id')
@Roles(['admin'])
supprimer(@Param('id', ParseIntPipe) id: number) {
return { supprimee: id };
}
}
const cle = { 'x-api-key': 'cle-de-demo' };
await appel('GET', '/api/notes'); // sans clé
await appel('GET', '/api/notes', { entetes: { 'x-api-key': 'mauvaise' } });
await appel('GET', '/api/notes', { entetes: cle });
await appel('POST', '/api/notes', { entetes: cle }); // sans rôle
await appel('POST', '/api/notes', { entetes: { ...cle, 'x-role': 'stagiaire' } });
await appel('POST', '/api/notes', { entetes: { ...cle, 'x-role': 'formateur' } });
await appel('DELETE', '/api/notes/3', { entetes: { ...cle, 'x-role': 'formateur' } });
await appel('DELETE', '/api/notes/3', { entetes: { ...cle, 'x-role': 'admin' } });
await appel('DELETE', '/api/notes/abc', { entetes: { ...cle, 'x-role': 'admin' } });
await appel('DELETE', '/api/notes/abc', { entetes: { ...cle, 'x-role': 'formateur' } });
Résultat réellement obtenu :
GET /api/notes → 403 {"message":"Forbidden resource","error":"Forbidden","statusCode":403}
GET /api/notes → 403 {"message":"Forbidden resource","error":"Forbidden","statusCode":403}
GET /api/notes → 200 ["SQL : 15","JS : 12"]
POST /api/notes → 401 {"message":"Authentification requise","error":"Unauthorized","statusCode":401}
POST /api/notes → 403 {"message":"Rôle « stagiaire » insuffisant (attendu : formateur ou admin)","error":"Forbidden","statusCode":403}
POST /api/notes → 201 {"ajoutee":true}
DELETE /api/notes/3 → 403 {"message":"Rôle « formateur » insuffisant (attendu : admin)","error":"Forbidden","statusCode":403}
DELETE /api/notes/3 → 200 {"supprimee":3}
DELETE /api/notes/abc → 400 {"message":"Validation failed (numeric string is expected)","error":"Bad Request","statusCode":400}
DELETE /api/notes/abc → 403 {"message":"Rôle « formateur » insuffisant (attendu : admin)","error":"Forbidden","statusCode":403}
Ce qu'il faut observer
- Quand
canActivaterenvoiefalse, NestJS répond 403 « Forbidden resource », un message peu explicite. Pour une clé absente, un 401 serait plus juste : leRolesGuardle fait en levant lui-même ses exceptions, avec des messages précis. - 401 Unauthorized = « je ne sais pas qui vous êtes » ; 403 Forbidden = « je sais qui vous êtes, mais vous n'avez pas le droit ».
GET /api/notesn'a pas de@Roles: seul le guard de clé s'applique.- Les deux dernières requêtes : avec
abccomme identifiant, l'admin obtient 400 (le pipe a refusé), mais le formateur obtient 403. Le guard a refusé avant que le pipe ne s'exécute : les guards passent avant les pipes. On ne révèle rien du format des données à quelqu'un qui n'a pas accès à la route.
Simulation : ici, le rôle est lu dans un en-tête x-role que n'importe quel client peut falsifier. C'est uniquement pour comprendre le mécanisme. Au chapitre 13, le rôle viendra d'un jeton JWT signé par le serveur, vérifié par un guard d'authentification ; le RolesGuard restera presque identique.
Un guard global et des routes publiques
Dans une vraie API, presque toutes les routes sont protégées. Plutôt que d'ajouter @UseGuards partout (et d'en oublier), on active le guard globalement et on marque les exceptions avec un décorateur @Public():
📄 src/common/decorators/public.decorator.ts
import { Reflector } from '@nestjs/core';
export const Public = Reflector.createDecorator<boolean>({ transform: () => true });
📄 src/common/guards/cle-api-global.guard.ts
import { CanActivate, ExecutionContext, Injectable, UnauthorizedException } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { Request } from 'express';
import { Public } from './public.decorator';
@Injectable()
export class CleApiGlobalGuard implements CanActivate {
constructor(private readonly reflector: Reflector) {}
canActivate(context: ExecutionContext): boolean {
const estPublic = this.reflector.getAllAndOverride(Public, [context.getHandler(), context.getClass()]);
if (estPublic) return true;
const cle = context.switchToHttp().getRequest<Request>().header('x-api-key');
if (cle !== 'cle-de-demo') throw new UnauthorizedException('Clé API absente ou invalide');
return true;
}
}
📄 src/app.controller.ts
import { Controller, Get } from '@nestjs/common';
import { Public } from './public.decorator';
@Controller()
export class AppController {
@Public()
@Get('sante')
sante() {
return { statut: 'ok' };
}
@Get('stagiaires')
stagiaires() {
return ['Ben Ali', 'Trabelsi'];
}
}
📄 src/app.module.ts
import { Module } from '@nestjs/common';
import { APP_GUARD } from '@nestjs/core';
import { AppController } from './app.controller';
import { CleApiGlobalGuard } from './cle-api-global.guard';
@Module({
controllers: [AppController],
providers: [{ provide: APP_GUARD, useClass: CleApiGlobalGuard }], // guard global, avec injection
})
export class AppModule {}
Résultat réellement obtenu :
GET /api/sante → 200 {"statut":"ok"}
GET /api/stagiaires → 401 {"message":"Clé API absente ou invalide","error":"Unauthorized","statusCode":401}
GET /api/stagiaires → 200 ["Ben Ali","Trabelsi"]
Avec APP_GUARD, le guard est créé par le conteneur et peut recevoir Reflector (et tout autre service). app.useGlobalGuards(new …) fonctionnerait aussi, mais sans injection. Plusieurs APP_GUARD peuvent être déclarés : ils s'exécutent dans l'ordre de déclaration, ce que le TP 6 utilise.
Portées des guards
| Portée | Syntaxe |
|---|---|
| Méthode | @UseGuards(MonGuard) sur le handler |
| Contrôleur | @UseGuards(GuardA, GuardB) sur la classe (exécutés dans cet ordre) |
| Global | { provide: APP_GUARD, useClass: MonGuard } ou app.useGlobalGuards() |
Ordre : guards globaux, puis du contrôleur, puis de la méthode. Le premier qui refuse arrête la requête. canActivate peut aussi être async (vérifier un jeton en base, par exemple).
Activités
Activité 1 401 ou 403 ?
Indiquez le statut attendu : (a) aucun jeton ; (b) jeton expiré ; (c) stagiaire qui veut supprimer un groupe ; (d) formateur qui modifie une note d'un groupe qu'il n'encadre pas ; (e) clé API mal orthographiée.
Voir le corrigé
(a) 401. (b) 401 : l'identité ne peut plus être établie. (c) 403. (d) 403 : identifié, mais pas autorisé sur cette ressource (règle souvent vérifiée dans le service, car elle dépend des données). (e) 401.
Activité 2 Un guard d'horaires
Écrivez HorairesGuard qui n'autorise les routes de saisie des notes que du lundi au vendredi, de 8 h à 18 h, et lève une ForbiddenException avec un message clair sinon. Comment le rendre testable ?
Voir le corrigé
@Injectable()
export class HorairesGuard implements CanActivate {
constructor(@Inject(HORLOGE) private readonly horloge: Horloge) {} // horloge injectée (leçon 7.4)
canActivate(): boolean {
const d = this.horloge.maintenant();
const jourOuvre = d.getDay() >= 1 && d.getDay() <= 5;
const heureOk = d.getHours() >= 8 && d.getHours() < 18;
if (!jourOuvre || !heureOk) {
throw new ForbiddenException('La saisie des notes est ouverte du lundi au vendredi, de 8 h à 18 h');
}
return true;
}
}
En injectant l'horloge, un test peut fournir une date fixe (un dimanche, un mardi à 10 h) et vérifier les deux cas.
Activité 3 getAllAndOverride ou getAllAndMerge ?
Le contrôleur porte @Roles(['admin']) et une de ses méthodes @Roles(['formateur']). Avec getAllAndOverride, qui peut exécuter cette méthode ? Et avec getAllAndMerge?
Voir le corrigé
getAllAndOverride: seulement le formateur (la méthode remplace le contrôleur). getAllAndMerge: ['formateur', 'admin'], les deux rôles. Le premier est le plus courant : la méthode précise une exception à la règle du contrôleur.
Activité 4 Protéger api-formation
Dans votre projet, activez CleApiGlobalGuard avec APP_GUARD, rendez publiques les routes de lecture (GET) des formations et la route de santé, et vérifiez avec votre fichier .http que les créations et suppressions exigent la clé.
Voir le corrigé
Ajoutez @Public() sur les handlers findAll et findOne et sur SanteController (sur la classe : toutes ses routes). Dans le fichier .http, définissez une variable @cle = cle-de-demo et ajoutez x-api-key: {{cle}} aux requêtes protégées. Testez aussi sans l'en-tête pour constater le 401.
À retenir
- Un guard implémente CanActivate : true laisse passer, false donne 403 « Forbidden resource ».
- Lever soi-même UnauthorizedException (401) ou ForbiddenException (403) donne des messages plus clairs.
- ExecutionContext.getHandler() / getClass() + Reflector permettent de lire les métadonnées (@Roles).
- Les guards s'exécutent après les middlewares et AVANT les intercepteurs et les pipes.
- Guard global avec APP_GUARD (injection possible) et décorateur @Public() pour les exceptions.
Cet article vous a-t-il aidé ?
Merci pour votre avis sur cet article 🙏
Merci, votre message nous a bien été transmis 🙏
Cette leçon vous a été utile ? Partagez-la !