Avez-vous une question? (216) 97 656 803 hajjriadh@gmail.com
NestJS

Gestion des rôles et des permissions (RBAC, décorateur @Roles)

Cette leçon met en place l'autorisation. Un décorateur @Roles et un RolesGuard global, déclaré après le guard JWT, restreignent les routes selon le rôle (admin, formateur, stagiaire) et répondent 403....

0 chapitres 0 QCM Accès gratuit
Gestion des rôles et des permissions (RBAC, décorateur @Roles)

À propos de ce cours

Cette leçon met en place l'autorisation. Un décorateur @Roles et un RolesGuard global, déclaré après le guard JWT, restreignent les routes selon le rôle (admin, formateur, stagiaire) et répondent 403. L'exécution montre aussi la seconde moitié de l'autorisation, souvent oubliée : la propriété des données, vérifiée dans le service. Chaque utilisateur ne voit que ses notes ou celles de ses groupes, et un formateur ne peut modifier que les notes de ses matières. La leçon présente les permissions fines, l'ordre des guards et les erreurs classiques. Activités corrigées.

Objectifs de la leçon

  • Restreindre des routes par rôle avec @Roles et un RolesGuard global.
  • Ordonner les guards d'authentification et d'autorisation.
  • Vérifier la propriété des données dans les services.
  • Passer des rôles aux permissions quand les règles se multiplient.
Le contrôle d'accès par rôles (RBAC)

Le RBAC (Role-Based Access Control) attribue à chaque utilisateur un rôle, et à chaque route les rôles autorisés. Nous l'avions simulé au chapitre 09 avec un en-tête ; le rôle vient maintenant du jeton vérifié (et même de la base, leçon 13.5). Mais le rôle ne suffit pas : un formateur a le droit de saisir des notes… de ses stagiaires. C'est la règle de propriété.

Rôles et propriété

Trois questions successives : identité, rôle, propriété de la ressource.

Le décorateur et le guard

📄 src/auth/roles.decorator.ts

import { SetMetadata } from '@nestjs/common';
import { Role } from '../utilisateurs/utilisateur.entity';

export const ROLES = 'roles';
export const Roles = (...roles: Role[]) => SetMetadata(ROLES, roles);

📄 src/auth/roles.guard.ts

import { CanActivate, ExecutionContext, ForbiddenException, Injectable } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { Role } from '../utilisateurs/utilisateur.entity';
import { ROLES } from './roles.decorator';

@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private readonly reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    const roles = this.reflector.getAllAndOverride<Role[]>(ROLES, [context.getHandler(), context.getClass()]);
    if (!roles?.length) return true;                              // pas de restriction de rôle
    const user = context.switchToHttp().getRequest().user;        // placé par JwtAuthGuard (exécuté avant)
    if (!user) return true;                                       // route publique
    if (!roles.includes(user.role)) {
      throw new ForbiddenException(`Accès réservé : ${roles.join(', ')}`);
    }
    return true;
  }
}

📄 src/app.module.ts

import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { TypeOrmModule } from '@nestjs/typeorm';
import { AuthModule } from './auth/auth.module';
import { UtilisateursModule } from './utilisateurs/utilisateurs.module';
import { APP_GUARD } from '@nestjs/core';
import { JwtAuthGuard } from './auth/jwt-auth.guard';
import { RolesGuard } from './auth/roles.guard';
import { NotesController } from './notes/notes.controller';
import { NotesService } from './notes/notes.service';

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }),
    TypeOrmModule.forRootAsync({
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        type: 'mysql',
        host: config.get('DB_HOTE'),
        port: Number(config.get('DB_PORT', 3306)),
        username: config.get('DB_UTILISATEUR'),
        password: config.get('DB_MOT_DE_PASSE'),
        database: config.get('DB_NOM'),
        autoLoadEntities: true,
        synchronize: true,
      }),
    }),
    UtilisateursModule,
    AuthModule,
  ],
  controllers: [NotesController],
  providers: [
    NotesService,
    { provide: APP_GUARD, useClass: JwtAuthGuard },     // 1. qui êtes-vous ? (401)
    { provide: APP_GUARD, useClass: RolesGuard },       // 2. avez-vous le droit ? (403)
  ],
})
export class AppModule {}

Les deux APP_GUARD s'exécutent dans l'ordre de déclaration: d'abord JwtAuthGuard (qui remplit req.user), puis RolesGuard (qui le lit). Inversés, RolesGuard trouverait req.user vide.

Rôles et propriété dans le service

📄 src/notes/notes.service.ts

import { ForbiddenException, Injectable, NotFoundException } from '@nestjs/common';
import { UtilisateurConnecte } from '../auth/auth.decorators';

interface Note { id: number; stagiaireId: number; formateurId: number; matiere: string; valeur: number }

@Injectable()
export class NotesService {
  private readonly notes: Note[] = [
    { id: 1, stagiaireId: 3, formateurId: 2, matiere: 'SQL', valeur: 15 },
    { id: 2, stagiaireId: 3, formateurId: 2, matiere: 'JS', valeur: 12.5 },
    { id: 3, stagiaireId: 4, formateurId: 2, matiere: 'SQL', valeur: 9 },
    { id: 4, stagiaireId: 4, formateurId: 5, matiere: 'Anglais', valeur: 14 },
  ];

  // Ce que chacun a le droit de VOIR dépend de qui il est : règle de propriété
  lister(u: UtilisateurConnecte) {
    if (u.role === 'admin') return this.notes;
    if (u.role === 'formateur') return this.notes.filter((n) => n.formateurId === u.id);
    return this.notes.filter((n) => n.stagiaireId === u.id);
  }

  modifier(id: number, valeur: number, u: UtilisateurConnecte) {
    const note = this.notes.find((n) => n.id === id);
    if (!note) throw new NotFoundException(`Note ${id} introuvable`);
    if (u.role === 'formateur' && note.formateurId !== u.id) {
      throw new ForbiddenException('Vous ne pouvez modifier que les notes de vos matières');
    }
    note.valeur = valeur;
    return note;
  }

  supprimer(id: number) {
    const i = this.notes.findIndex((n) => n.id === id);
    if (i < 0) throw new NotFoundException(`Note ${id} introuvable`);
    this.notes.splice(i, 1);
  }
}

📄 src/notes/notes.controller.ts

import { Body, Controller, Delete, Get, HttpCode, Param, ParseIntPipe, Patch } from '@nestjs/common';
import { Utilisateur, UtilisateurConnecte } from '../auth/auth.decorators';
import { Roles } from '../auth/roles.decorator';
import { Role } from '../utilisateurs/utilisateur.entity';
import { NotesService } from './notes.service';

@Controller('notes')
export class NotesController {
  constructor(private readonly notesService: NotesService) {}

  @Get()                                                    // tout utilisateur connecté…
  lister(@Utilisateur() u: UtilisateurConnecte) {
    return this.notesService.lister(u);                     // … mais chacun voit SES notes
  }

  @Patch(':id')
  @Roles(Role.Formateur, Role.Admin)
  modifier(@Param('id', ParseIntPipe) id: number, @Body('valeur', ParseIntPipe) valeur: number, @Utilisateur() u: UtilisateurConnecte) {
    return this.notesService.modifier(id, valeur, u);
  }

  @Delete(':id')
  @Roles(Role.Admin)
  @HttpCode(204)
  supprimer(@Param('id', ParseIntPipe) id: number) {
    this.notesService.supprimer(id);
  }
}
  const port = app.getHttpServer().address().port;
  const auth = app.get(AuthService);
  const users = app.get(UtilisateursService);
  const hache = (m: string) => bcrypt.hash(m, 10);
  await users.create({ email: 'admin@exemple.tn', nom: 'Hajji', motDePasse: await hache('Admin2026!'), role: Role.Admin });          // id 1
  await users.create({ email: 'mansouri@exemple.tn', nom: 'Mansouri', motDePasse: await hache('Formateur2026'), role: Role.Formateur }); // id 2
  await auth.inscrire({ email: 'sami@exemple.tn', nom: 'Sami Ben Ali', motDePasse: 'Stagiaire2026' });                                // id 3
  await auth.inscrire({ email: 'ines@exemple.tn', nom: 'Ines Trabelsi', motDePasse: 'Stagiaire2026' });                               // id 4
  const jeton = async (email: string, motDePasse: string) => {
    const r = await fetch(`http://localhost:${port}/api/auth/connexion`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ email, motDePasse }) });
    return { authorization: `Bearer ${(await r.json()).access_token}` };
  };
  const admin = await jeton('admin@exemple.tn', 'Admin2026!');
  const formateur = await jeton('mansouri@exemple.tn', 'Formateur2026');
  const sami = await jeton('sami@exemple.tn', 'Stagiaire2026');
  console.log('— Lecture : chacun voit ce qui le concerne');
  await appel('GET', '/api/notes', { entetes: sami });
  await appel('GET', '/api/notes', { entetes: formateur });
  await appel('GET', '/api/notes', { entetes: admin });
  console.log('— Rôles');
  await appel('PATCH', '/api/notes/1', { entetes: sami, corps: { valeur: 20 } });
  await appel('PATCH', '/api/notes/1', { entetes: formateur, corps: { valeur: 16 } });
  await appel('PATCH', '/api/notes/4', { entetes: formateur, corps: { valeur: 20 } });
  await appel('DELETE', '/api/notes/3', { entetes: formateur });
  await appel('DELETE', '/api/notes/3', { entetes: admin });
  await appel('DELETE', '/api/notes/3');

Résultat réellement obtenu :

— Lecture : chacun voit ce qui le concerne
GET /api/notes → 200 [{"id":1,"stagiaireId":3,"formateurId":2,"matiere":"SQL","valeur":15},{"id":2,"stagiaireId":3,"formateurId":2,"matiere":"JS","valeur":12.5}]
GET /api/notes → 200 [{"id":1,"stagiaireId":3,"formateurId":2,"matiere":"SQL","valeur":15},{"id":2,"stagiaireId":3,"formateurId":2,"matiere":"JS","valeur":12.5},{"id":3,"stagiaireId":4,"formateurId":2,"matiere":"SQL","valeur":9}]
GET /api/notes → 200 [{"id":1,"stagiaireId":3,"formateurId":2,"matiere":"SQL","valeur":15},{"id":2,"stagiaireId":3,"formateurId":2,"matiere":"JS","valeur":12.5},{"id":3,"stagiaireId":4,"formateurId":2,"matiere":"SQL","valeur":9},{"id":4,"stagiaireId":4,"formateurId":5,"matiere":"Anglais","valeur":14}]
— Rôles
PATCH /api/notes/1 → 403 {"message":"Accès réservé : formateur, admin","error":"Forbidden","statusCode":403}
PATCH /api/notes/1 → 200 {"id":1,"stagiaireId":3,"formateurId":2,"matiere":"SQL","valeur":16}
PATCH /api/notes/4 → 403 {"message":"Vous ne pouvez modifier que les notes de vos matières","error":"Forbidden","statusCode":403}
DELETE /api/notes/3 → 403 {"message":"Accès réservé : admin","error":"Forbidden","statusCode":403}
DELETE /api/notes/3 → 204
DELETE /api/notes/3 → 401 {"message":"Unauthorized","statusCode":401}
Lecture
  • Lecture: la même route renvoie des résultats différents selon l'utilisateur. Sami (id 3) voit ses 2 notes, la formatrice Mansouri (id 2) les 3 notes de ses matières, l'admin les 4.
  • Rôle: le stagiaire ne peut pas modifier (403 du RolesGuard), le formateur ne peut pas supprimer.
  • Propriété: la formatrice a le bon rôle, mais la note 4 a été saisie par un autre formateur : 403, levé par le service, le seul à connaître les données.
  • Sans jeton : 401 (le premier guard refuse avant même de consulter les rôles).

La vérification de propriété ne peut pas être faite par un guard générique: elle dépend de la ressource (qui a saisi la note, quel groupe encadre le formateur). On la place dans le service, ou dans la requête elle-même (WHERE formateur_id = :moi), ce qui empêche aussi de lire les données des autres. Oublier cette vérification est l'une des failles d'API les plus fréquentes (Broken Object Level Authorization, n° 1 du classement OWASP API).

Des rôles aux permissions

Quand les règles se multiplient (« le secrétariat peut lire les notes mais pas les modifier », « le directeur des études peut tout valider »), on passe des rôles aux permissions: chaque route demande une permission, et chaque rôle en accorde un ensemble.

// Permissions fines : le rôle donne un ensemble de permissions
export const PERMISSIONS = {
  admin: ['notes:lire', 'notes:ecrire', 'notes:supprimer', 'comptes:gerer'],
  formateur: ['notes:lire', 'notes:ecrire'],
  stagiaire: ['notes:lire'],
} as const;

export const Permission = (...p: string[]) => SetMetadata('permissions', p);

@Injectable()
export class PermissionsGuard implements CanActivate {
  constructor(private readonly reflector: Reflector) {}
  canActivate(ctx: ExecutionContext) {
    const requises = this.reflector.getAllAndOverride<string[]>('permissions', [ctx.getHandler(), ctx.getClass()]);
    if (!requises?.length) return true;
    const role = ctx.switchToHttp().getRequest().user?.role as keyof typeof PERMISSIONS;
    const accordees: readonly string[] = PERMISSIONS[role] ?? [];
    if (!requises.every((p) => accordees.includes(p))) throw new ForbiddenException('Permission insuffisante');
    return true;
  }
}

// utilisation
@Delete(':id')
@Permission('notes:supprimer')
supprimer() { … }

Ajouter un rôle ne demande alors aucune modification des contrôleurs : seulement de la table des permissions (qu'on peut même stocker en base). Pour des règles encore plus riches (« modifier un article seulement s'il est en brouillon »), des bibliothèques comme CASL permettent l'Attribute-Based Access Control.

Activités

Activité 1 Rôles sur un contrôleur

Placez @Roles(Role.Admin) sur la classe UtilisateursController, puis rendez une seule méthode (GET /utilisateurs/moi) accessible à tous les rôles. Comment, sans dupliquer le décorateur ?

Voir le corrigé

Sur la méthode : @Roles(Role.Admin, Role.Formateur, Role.Stagiaire). Avec getAllAndOverride, la valeur de la méthode remplace celle de la classe. Autre possibilité : un décorateur @TousLesRoles() qui pose une liste vide, que le guard interprète comme « pas de restriction ».

Activité 2 Filtrer dans la requête

Réécrivez lister() pour une base de données : un formateur ne doit recevoir que les notes des stagiaires des groupes qu'il encadre. Écrivez la condition dans le QueryBuilder plutôt qu'avec un filter en mémoire. Pourquoi ?

Voir le corrigé
const qb = this.notes.createQueryBuilder('n').innerJoin('n.stagiaire', 's').leftJoin('s.groupe', 'g');
if (moi.role === Role.Formateur) qb.where('g.formateurId = :id', { id: moi.id });
if (moi.role === Role.Stagiaire) qb.where('n.stagiaireId = :id', { id: moi.id });

Filtrer en mémoire chargerait toutes les notes de l'établissement à chaque appel (lent, et dangereux si un bug renvoyait la liste non filtrée). Dans la requête, seules les lignes autorisées sortent de la base. C'est ce que fait le TP 8.

Activité 3 Trouver la faille

Cette route permet à un stagiaire de consulter son bulletin. Quelle faille contient-elle ? Corrigez-la de deux façons.

@Get('bulletins/:stagiaireId')
@Roles(Role.Stagiaire, Role.Formateur, Role.Admin)
bulletin(@Param('stagiaireId', ParseIntPipe) id: number) {
  return this.notesService.bulletin(id);
}
Voir le corrigé

Un stagiaire peut demander le bulletin de n'importe quel autre stagiaire en changeant l'identifiant (IDOR). Correction 1 : une route GET /bulletins/moi qui utilise @Utilisateur('id'). Correction 2 : garder la route et vérifier dans le service : si le demandeur est stagiaire, id doit être le sien ; s'il est formateur, le stagiaire doit appartenir à l'un de ses groupes ; sinon 403 (ou 404, pour ne même pas confirmer l'existence).

Activité 4 Permissions

Remplacez @Roles par @Permission dans NotesController avec la table de la leçon, puis ajoutez un rôle secretariat qui peut lire et supprimer des notes mais pas en saisir. Combien de fichiers avez-vous modifiés ?

Voir le corrigé

Deux : l'énumération Role (nouvelle valeur) et la table PERMISSIONS (secretariat: ['notes:lire', 'notes:supprimer']). Aucun contrôleur. Attention aussi à la règle de propriété de lister(): elle doit prévoir le nouveau rôle (ici, tout voir, comme l'admin).

À retenir

  • @Roles(...) + RolesGuard (Reflector) : 403 si le rôle de req.user n'est pas autorisé.
  • APP_GUARD dans l'ordre : JwtAuthGuard (401) puis RolesGuard (403).
  • Le rôle ne suffit pas : la propriété des données se vérifie dans le service, ou dans la requête SQL.
  • Identifiant de l'utilisateur : depuis le jeton (@Utilisateur), jamais depuis l'URL sans contrôle.
  • Règles nombreuses : permissions par rôle ; règles sur les attributs : CASL.

Cet article vous a-t-il aidé ?