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

Limiter le nombre de requêtes (Rate limiting, @nestjs/throttler)

Cette leçon limite le nombre de requêtes qu'un client peut envoyer à une API NestJS avec @nestjs/throttler. Elle explique le principe (une limite, une fenêtre de temps, une clé, la réponse 429), confi...

0 chapitres 0 QCM Accès gratuit
Limiter le nombre de requêtes (Rate limiting, @nestjs/throttler)

À propos de ce cours

Cette leçon limite le nombre de requêtes qu'un client peut envoyer à une API NestJS avec @nestjs/throttler. Elle explique le principe (une limite, une fenêtre de temps, une clé, la réponse 429), configure deux limites globales nommées et les vérifie sur de vraies rafales de requêtes. Elle protège la connexion contre la force brute avec @Throttle et blockDuration, montre le piège de @SkipThrottle avec des limites nommées et la faille de « trust proxy » mal configuré, réellement exploitée puis corrigée. Elle aborde enfin le stockage partagé entre plusieurs instances. Activités corrigées.

Objectifs de la leçon

  • Comprendre pourquoi une API doit limiter le débit de ses clients.
  • Configurer @nestjs/throttler avec des limites globales nommées.
  • Protéger la connexion contre la force brute (@Throttle, blockDuration).
  • Exclure une route de la limite sans tomber dans le piège des limites nommées.
  • Configurer correctement l'adresse IP du client derrière un proxy.

Versions: NestJS 12.5 (projet CommonJS créé avec nest new), TypeScript 6, Node.js 24, MariaDB 10.11, helmet 8.3, @nestjs/throttler 6.7. Tout le code de ce chapitre provient d'un vrai projet, api-securisee, et toutes les sorties ont réellement été obtenues en l'exécutant. Les mêmes notions s'appliquent à NestJS 10 et 11.

Pourquoi limiter le débit ?

Sans limite, rien n'empêche un programme d'envoyer des milliers de requêtes par seconde à votre API :

  • force brute: essayer des milliers de mots de passe sur /auth/connexion;
  • aspiration: télécharger toute la base page par page ;
  • déni de service applicatif: saturer le serveur ou la base avec des requêtes coûteuses (recherche, export, hachage bcrypt) ;
  • abus de coût: déclencher des milliers d'e-mails ou de SMS (« mot de passe oublié »).

Le rate limiting (limitation de débit) compte les requêtes de chaque client pendant une fenêtre de temps. Au-delà de la limite, l'API répond immédiatement 429 Too Many Requests, sans exécuter la route. C'est le risque API4 de l'OWASP (leçon 19.3).

Fonctionnement de @nestjs/throttler

Un guard global compte les requêtes par client et par limite ; au-delà, réponse 429.

Installer et configurer @nestjs/throttler
npm install @nestjs/throttler

Le module se configure dans AppModule; le ThrottlerGuard est déclaré comme guard global (APP_GUARD), pour que toutes les routes soient protégées par défaut :

📄 src/app.module.ts (extrait)

    // 19.2 : deux limites appliquées ensemble à chaque route
    ThrottlerModule.forRoot({
      throttlers: [
        { name: 'court', ttl: seconds(1), limit: 5 },
        { name: 'long', ttl: minutes(1), limit: 100 },
      ],
      errorMessage: 'Trop de requêtes : réessayez dans quelques instants.',

📄 src/app.module.ts (extrait)

  providers: [
    // l'ordre compte : la limite de débit s'applique avant l'authentification
    { provide: APP_GUARD, useClass: ThrottlerGuard },
    { provide: APP_GUARD, useClass: AuthGuard },
  ],
  • Chaque limite a un nom, une durée ttl (en millisecondes : les fonctions seconds() et minutes() évitent les erreurs) et un nombre maximal de requêtes limit.
  • Les deux limites s'appliquent ensemble: « court » coupe les rafales (5 par seconde), « long » limite l'usage continu (100 par minute).
  • Par défaut, la clé est l'adresse IP du client, combinée avec la route : chaque route a son propre compteur.
  • L'ordre des guards compte: le ThrottlerGuard est déclaré avant l'AuthGuard, il s'exécute donc en premier. Un client non connecté qui inonde l'API est arrêté avant la vérification du jeton.
Vérifier : une rafale de requêtes

Huit requêtes immédiates sans jeton sur /api/demandes, puis une neuvième une seconde plus tard :

Résultat réellement obtenu :

$ for i in $(seq 1 8); do curl -s -o /dev/null -w "%{http_code} " http://localhost:3000/api/demandes; done; echo
401 401 401 401 401 429 429 429 
$ sleep 1; curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3000/api/demandes
401

Les cinq premières passent le ThrottlerGuard et sont refusées par l'AuthGuard (401, pas de jeton). Les trois suivantes dépassent la limite « court » : 429, sans même vérifier le jeton. Une seconde plus tard, la fenêtre est terminée : la requête passe de nouveau. Chaque réponse indique au client où il en est, avec un jeu d'en-têtes par limite (ici une requête de Sami, connecté) :

Résultat réellement obtenu :

$ curl -si http://localhost:3000/api/demandes -H "Authorization: Bearer $SAMI" | grep -iE "^HTTP|ratelimit"
HTTP/1.1 200 OK
X-RateLimit-Limit-court: 5
X-RateLimit-Remaining-court: 4
X-RateLimit-Reset-court: 1
X-RateLimit-Limit-long: 100
X-RateLimit-Remaining-long: 99
X-RateLimit-Reset-long: 60

Remaining: requêtes restantes dans la fenêtre ; Reset: secondes avant la fin de la fenêtre. Un client bien écrit (votre application Angular) peut s'en servir pour ralentir de lui-même.

Protéger la connexion contre la force brute

100 essais par minute, c'est beaucoup trop pour une connexion. Le décorateur @Throttle() remplace les valeurs d'une ou plusieurs limites pour une route (ou un contrôleur entier) :

📄 src/auth/auth.controller.ts (extrait)

  // 19.2 : 5 tentatives par minute et par adresse IP, puis 5 minutes de blocage
  @Throttle({ long: { limit: 5, ttl: minutes(1), blockDuration: minutes(5) } })
  @Post('connexion')
  @HttpCode(200)
  connexion(@Body() dto: ConnexionDto, @Ip() ip: string) {
    return this.auth.connecter(dto, ip);
  }

  @Throttle({ long: { limit: 3, ttl: minutes(10) } })
  @Post('inscription')
  inscription(@Body() dto: InscriptionDto) {
    return this.utilisateurs.inscrire(dto);
  }

blockDuration: une fois la limite atteinte, le client reste bloqué 5 minutes, au lieu d'attendre seulement la fin de la fenêtre. Un attaquant passe de 100 essais par minute à 5 toutes les 6 minutes environ : environ 1 200 essais par jour au lieu de 144 000. Essayons cinq mots de passe courants, puis le bon :

Résultat réellement obtenu :

$ for mdp in azerty 123456 sami2026 motdepasse soleil; do
  curl -s -X POST http://localhost:3000/api/auth/connexion -H "Content-Type: application/json" \
    -d "{\"email\":\"sami@exemple.tn\",\"motDePasse\":\"$mdp\"}"; echo
done
{"message":"Identifiants incorrects","error":"Unauthorized","statusCode":401}
{"message":"Identifiants incorrects","error":"Unauthorized","statusCode":401}
{"message":"Identifiants incorrects","error":"Unauthorized","statusCode":401}
{"message":"Identifiants incorrects","error":"Unauthorized","statusCode":401}
{"message":"Identifiants incorrects","error":"Unauthorized","statusCode":401}
$ # 6e essai, avec le BON mot de passe
curl -si -X POST http://localhost:3000/api/auth/connexion -H 'Content-Type: application/json' -d '{"email":"sami@exemple.tn","motDePasse":"Stagiaire2026!"}' | grep -E "^HTTP|^Retry|^X-RateLimit|^\{"
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit-court: 5
X-RateLimit-Remaining-court: 1
X-RateLimit-Reset-court: 1
Retry-After-long: 300
{"statusCode":429,"message":"Trop de requêtes : réessayez dans quelques instants."}

Le même essai depuis Swagger UI, après cinq échecs, affiche la réponse 429 et ses en-têtes :

Réponse 429 dans Swagger UI

Swagger UI : la connexion avec le bon mot de passe reçoit 429 et retry-after-long: 300 (capture réelle).

Même le bon mot de passe est refusé pendant le blocage : l'attaquant ne peut pas savoir s'il l'a trouvé. Retry-After-long: 300 indique au client d'attendre 300 secondes. Côté serveur, les échecs sont journalisés (leçon 19.4) :

Journal du serveur (réel) :

[API] 5659  - 11/15/2026, 6:05:43 PM    WARN [AuthService] Échec de connexion { email: 'sami@exemple.tn', ip: '127.0.0.1' }
[API] 5659  - 11/15/2026, 6:05:43 PM    WARN [AuthService] Échec de connexion { email: 'sami@exemple.tn', ip: '127.0.0.1' }
[API] 5659  - 11/15/2026, 6:05:44 PM    WARN [AuthService] Échec de connexion { email: 'sami@exemple.tn', ip: '127.0.0.1' }
[API] 5659  - 11/15/2026, 6:05:44 PM    WARN [AuthService] Échec de connexion { email: 'sami@exemple.tn', ip: '127.0.0.1' }
[API] 5659  - 11/15/2026, 6:05:44 PM    WARN [AuthService] Échec de connexion { email: 'sami@exemple.tn', ip: '127.0.0.1' }
[API] 5659  - 11/15/2026, 6:05:44 PM    WARN [HTTP] POST /api/auth/connexion 429 1ms { requete: '269e3ed8', ip: '127.0.0.1', utilisateur: null }

Et le vrai stagiaire ? Si un attaquant partage l'adresse IP d'un utilisateur (même réseau Wi-Fi, même établissement derrière une seule IP publique), ce dernier est bloqué lui aussi. C'est le compromis de toute limite par IP. Pour la connexion, on peut compter par e-mail visé plutôt que par IP (activité 3) : l'attaquant ne bloque alors que le compte attaqué, pendant quelques minutes.

Exclure une route : le piège des limites nommées

La route /api/sante est appelée toutes les 10 secondes par l'outil de supervision (chapitre 20) : elle ne doit jamais renvoyer 429. Le décorateur @SkipThrottle() semble fait pour cela. Résultat réel avec @SkipThrottle() et 20 appels rapides :

Résultat réellement obtenu :

$ for i in $(seq 1 20); do curl -s -o /dev/null -w "%{http_code} " http://localhost:3000/api/sante; done; echo
200 200 200 200 200 429 429 429 429 429 429 429 429 429 429 429 429 429 429 429 

La route est toujours limitée ! Sans argument, @SkipThrottle() désactive uniquement la limite nommée default, celle qu'on obtient quand on ne donne pas de nom. Avec des limites nommées, il faut les citer toutes:

📄 src/sante/sante.controller.ts

import { Controller, Get } from '@nestjs/common';
import { SkipThrottle } from '@nestjs/throttler';
import { Public } from '../auth/decorateurs';

@Public()
@SkipThrottle({ court: true, long: true }) // appelé toutes les 10 s par la supervision
@Controller('sante')
export class SanteController {
  @Get()
  etat() {
    return { statut: 'ok', disponibleDepuis: Math.round(process.uptime()) + ' s' };
  }
}

Résultat réellement obtenu :

$ for i in $(seq 1 20); do curl -s -o /dev/null -w "%{http_code} " http://localhost:3000/api/sante; done; echo
200 200 200 200 200 200 200 200 200 200 200 200 200 200 200 200 200 200 200 200 
Derrière un proxy : la bonne adresse IP

En production, l'API sera derrière nginx (chapitre 20). Toutes les requêtes arrivent alors de nginx, donc de 127.0.0.1: tous les utilisateurs partageraient le même compteur et seraient bloqués ensemble. Nginx transmet la vraie adresse dans l'en-tête X-Forwarded-For, et Express sait la lire si on lui dit de faire confiance au proxy (trust proxy) :

📄 src/configurer-app.ts (extrait)

  // 19.2 : derrière nginx, l'adresse du client est dans X-Forwarded-For
  // (loopback, une adresse, un nombre de proxys ; jamais true sans proxy devant l'API)
  const proxy = config.get<string>('TRUST_PROXY');
  if (proxy) app.set('trust proxy', proxy === 'true' ? true : /^\d+$/.test(proxy) ? Number(proxy) : proxy);

Mais cet en-tête, n'importe quel client peut l'écrire. Si l'API fait confiance à tout le monde (TRUST_PROXY=true) alors qu'aucun proxy n'est devant elle, un attaquant change de « fausse IP » à chaque requête. Huit requêtes avec un X-Forwarded-For différent, d'abord sans trust proxy:

Résultat réellement obtenu :

$ for i in 1 2 3 4 5 6 7 8; do curl -s -o /dev/null -w "%{http_code} " -H "X-Forwarded-For: 10.0.0.$i" http://localhost:3000/api/demandes; done; echo
401 401 401 401 401 429 429 429 

L'en-tête est ignoré : 429 dès la 6e. Avec TRUST_PROXY=true:

Résultat réellement obtenu :

$ for i in 1 2 3 4 5 6 7 8; do curl -s -o /dev/null -w "%{http_code} " -H "X-Forwarded-For: 10.0.0.$i" http://localhost:3000/api/demandes; done; echo
401 401 401 401 401 401 401 401 

Journal du serveur (réel) :

[API] 4237  - 11/15/2026, 5:58:01 PM    WARN [HTTP] GET /api/demandes 401 7ms { requete: '013aeb89', ip: '10.0.0.1', utilisateur: null }
[API] 4237  - 11/15/2026, 5:58:01 PM    WARN [HTTP] GET /api/demandes 401 1ms { requete: '5076d58a', ip: '10.0.0.2', utilisateur: null }
[API] 4237  - 11/15/2026, 5:58:01 PM    WARN [HTTP] GET /api/demandes 401 1ms { requete: 'eea1d390', ip: '10.0.0.3', utilisateur: null }

La limite ne s'applique plus jamais : l'API croit recevoir huit clients différents. Règle : ne faites confiance qu'au proxy réellement placé devant l'API. Nginx sur la même machine : TRUST_PROXY=loopback. Un seul proxy sur une autre machine : son adresse, ou 1 (le nombre de proxys).

Une anecdote réelle de cette leçon: la première version de configurerApp écrivait app.set('trust proxy', proxy) avec la chaîne lue dans .env. Avec TRUST_PROXY=true, l'API refusait de démarrer : TypeError: invalid IP address: true. Express attend le booléen true ou un nombre, pas les chaînes "true" ou "1": d'où la conversion dans le code ci-dessus. Les variables d'environnement sont toujours des chaînes de caractères.

Plusieurs instances de l'API

Les compteurs sont gardés en mémoire, dans le processus. Si l'API tourne en plusieurs exemplaires (PM2 en mode cluster, plusieurs conteneurs : chapitre 20), chacun a ses propres compteurs et la limite réelle est multipliée par le nombre d'instances. On utilise alors un stockage partagé, en général Redis (chapitre 15), via l'option storage de ThrottlerModule.forRoot() qui accepte toute classe implémentant l'interface ThrottlerStorage. Le paquet communautaire @nest-lab/throttler-storage-redis en fournit une ; à la date d'écriture, il n'annonce pas encore NestJS 12 dans ses dépendances.

Côté Angular

L'intercepteur du chapitre 18 peut traiter le statut 429 comme les autres : afficher « Trop de tentatives, réessayez dans quelques minutes » au lieu d'un message d'erreur générique, et désactiver le bouton de connexion pendant la durée indiquée.

Activités

Activité 1 Choisir des limites

Proposez une limite (nombre, fenêtre, éventuel blocage) pour : (a) POST /auth/mot-de-passe-oublie, qui envoie un e-mail ; (b) GET /stagiaires (liste paginée utilisée par Angular) ; (c) GET /exports/stagiaires.xlsx, qui génère un fichier de toute la base ; (d) GET /sante.

Voir le corrigé

Exemples raisonnables : (a) 3 par heure (un envoi d'e-mail coûte et peut harceler quelqu'un) ; (b) les limites globales suffisent ; (c) 2 par minute avec blocage de 10 minutes, car la requête est très coûteuse ; (d) aucune : @SkipThrottle({ court: true, long: true }). Toute valeur justifiée est acceptable ; l'essentiel est d'adapter la limite au coût et au risque de chaque route.

Activité 2 Mettre en place le throttler

Sur une branche securite/throttler de votre projet : installez @nestjs/throttler, configurez les deux limites, protégez la connexion et excluez la route de santé. Vérifiez chaque point avec les boucles curl de la leçon et notez les résultats dans la Pull Request.

Voir le corrigé

Vérifications attendues : 429 après 5 requêtes immédiates ; connexion bloquée au 6e essai, même avec le bon mot de passe, avec Retry-After-long: 300; 20 × 200 sur /sante. Si /sante renvoie 429, vérifiez que @SkipThrottle cite bien le nom de chaque limite. Commit : feat(securite): limitation de débit.

Activité 3 Compter par e-mail pour la connexion

Créez un guard ConnexionThrottlerGuard qui étend ThrottlerGuard et redéfinit protected async getTracker(req) pour renvoyer l'e-mail du corps de la requête (en minuscules), ou l'IP s'il est absent. Appliquez-le seulement à la route de connexion. Quel avantage ? Quel nouveau risque ?

Voir le corrigé
@Injectable()
export class ConnexionThrottlerGuard extends ThrottlerGuard {
  protected async getTracker(req: Record<string, any>): Promise<string> {
    const email = typeof req.body?.email === 'string' ? req.body.email.toLowerCase() : '';
    return email || req.ip;
  }
}

Sur la route : @UseGuards(ConnexionThrottlerGuard). Avantage : un attaquant ne bloque que le compte qu'il vise, pas tout l'établissement. Nouveau risque : n'importe qui peut bloquer le compte de quelqu'un d'autre pendant 5 minutes en ratant 5 connexions avec son e-mail. On garde donc aussi une limite par IP (les limites globales restent actives).

Activité 4 Diagnostic

Après la mise en production derrière nginx, tous les stagiaires reçoivent 429 en même temps vers 9 h, à l'ouverture des inscriptions. Les journaux montrent ip: '127.0.0.1' pour toutes les requêtes. Expliquez et corrigez.

Voir le corrigé

Express ne lit pas X-Forwarded-For: toutes les requêtes semblent venir de nginx (127.0.0.1) et partagent le même compteur. Correction : TRUST_PROXY=loopback dans le .env de production, et dans nginx proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; (chapitre 20). Ne pas mettre true.

À retenir

  • ThrottlerModule.forRoot + ThrottlerGuard en APP_GUARD, déclaré avant le guard d'authentification.
  • Des limites nommées (rafales et usage continu) ; au-delà : 429 et en-têtes X-RateLimit-* / Retry-After-*.
  • @Throttle avec blockDuration pour la connexion et les routes coûteuses.
  • @SkipThrottle() sans argument ne vise que la limite default: nommer chaque limite à ignorer.
  • Derrière nginx : trust proxy réglé sur le vrai proxy (loopback), jamais true sans proxy.
  • Plusieurs instances : un stockage partagé (Redis).

Cet article vous a-t-il aidé ?