H· Hawiyati Documentation
Déploiement et opérations

Limitation de débit

Hawiyati Gateway applique une limitation de débit basée sur Redis au point de connexion de l'IdP afin de se protéger contre les attaques par force brute et le credential-stuffing. Les limites sont appliquées par adresse IP cliente via un algorithme de seau à jetons.

Fonctionnement

Le module hawiyati-gateway (Spring Cloud Gateway, port 8080) se place en frontal de hawiyati-http-server. Tout le trafic — y compris les demandes de connexion — passe par la gateway avant d'atteindre l'IdP.

Pour les requêtes POST /api/http/login, la gateway applique le filtre RequestRateLimiterGatewayFilterFactory de Spring Cloud Gateway, supporté par Redis. Le limiteur utilise un algorithme de seau à jetons :

  • Des jetons sont ajoutés à chaque seau à un taux de recharge configurable (jetons par seconde).
  • Chaque requête consomme un jeton. Une requête est autorisée si un jeton est disponible ; sinon la gateway retourne 429 Too Many Requests.
  • Une capacité de rafale définit le nombre maximum de jetons qu'un seau peut contenir, permettant de courtes rafales au-delà du taux soutenu.

Chaque adresse IP cliente possède son propre seau. L'IP est extraite de X-Forwarded-For ou de l'adresse TCP distante par le bean ipKeyResolver. Si l'adresse distante est indisponible, la requête est placée dans le seau sous la clé unknown et est autorisée — c'est le comportement de défaillance ouverte décrit ci-dessous.

Référence de configuration

La limitation de débit est configurée dans hawiyati-gateway/src/main/resources/application.yml sous la route login-rate-limit.

spring:
  data:
    redis:
      host: ${REDIS_HOST:localhost}
      port: ${REDIS_PORT:6379}
  cloud:
    gateway:
      routes:
        - id: login-rate-limit
          uri: ${IDP_URI:http://localhost:8085}
          predicates:
            - Path=/api/http/login
            - Method=POST
          filters:
            - name: RequestRateLimiter
              args:
                redis-rate-limiter.replenishRate: 10
                redis-rate-limiter.burstCapacity: 20
                key-resolver: "#{@ipKeyResolver}"
                deny-empty-key: false
PropriétéDéfautDescription
redis-rate-limiter.replenishRate10Jetons ajoutés à chaque seau par seconde. Représente le taux autorisé soutenu.
redis-rate-limiter.burstCapacity20Nombre maximum de jetons qu'un seau peut contenir. Permet de courtes rafales sans déclencher de 429.
key-resolver#{@ipKeyResolver}Référence Spring Expression Language au bean de résolution de clé. Utilise l'adresse IP cliente.
deny-empty-keyfalseRefuser les requêtes lorsque le résolveur de clé retourne une clé vide. false = défaillance ouverte.
REDIS_HOSTlocalhostVariable d'environnement pour l'hôte Redis.
REDIS_PORT6379Variable d'environnement pour le port Redis.

Comportement en cas de défaillance ouverte

Avec deny-empty-key: false, la gateway autorise les requêtes lorsque Redis est indisponible ou lorsque le résolveur de clé ne peut pas déterminer la clé cliente. C'est intentionnel : une panne Redis ne bloque pas le flux de connexion. La disponibilité est prioritaire sur l'application stricte de la limite.

Recommandation pour la production

Exécutez Redis dans une configuration haute disponibilité (Redis Sentinel ou Redis Cluster) pour minimiser la fenêtre pendant laquelle la limitation de débit est inactive. Consultez le guide des opérations pour les instructions de configuration Redis HA.

Si vous souhaitez un comportement en défaillance fermée (refuser toutes les requêtes lorsque Redis est indisponible), définissez deny-empty-key: true. Sachez que cela entraîne le refus de toutes les demandes de connexion lors de toute panne Redis.

Réponse en cas de dépassement

Lorsqu'une requête est rejetée, la gateway retourne :

HTTP/1.1 429 Too Many Requests
X-RateLimit-Remaining: 0
X-RateLimit-Requested-Tokens: 1
X-RateLimit-Burst-Capacity-Header: 20
X-RateLimit-Replenish-Rate-Header: 10

(corps vide)

Les clients doivent inspecter les en-têtes X-RateLimit-* et mettre en œuvre un back-off exponentiel avant de réessayer. Les utilisateurs du formulaire de connexion voient la page 429 par défaut de la gateway ; les flux SP-initiated SAML qui publient sur le point de connexion recevront également une réponse 429.

Prérequis Redis

La gateway nécessite une instance Redis en cours d'exécution pour appliquer les limites de débit. Exigences principales :

  • Redis 6.0 ou version ultérieure (pour la prise en charge des scripts utilisés par l'implémentation du seau à jetons).
  • La gateway se connecte via Lettuce réactif grâce à spring-boot-starter-data-redis-reactive.
  • Aucun mot de passe ni TLS n'est configuré par défaut. Pour les déploiements en production, ajoutez spring.data.redis.password et les propriétés TLS.
  • Les clés de limitation de débit sont gérées automatiquement par Redis via TTL ; aucun nettoyage manuel n'est nécessaire.

Supervision et observabilité

Spring Cloud Gateway expose les métriques de limitation de débit via Spring Boot Actuator. Les métriques suivantes sont pertinentes :

MétriqueDescription
spring.cloud.gateway.requestsTotal des requêtes par route, statut et méthode HTTP. Filtrez par routeId=login-rate-limit et status=429 pour suivre les requêtes rejetées.
spring.cloud.gateway.routes.countNombre de routes configurées. Confirme que la route de limitation est chargée.

Activez l'endpoint actuator de la gateway dans application.yml :

management:
  endpoints:
    web:
      exposure:
        include: health,metrics,gateway

Recommandations de réglage

Les valeurs par défaut (recharge 10 req/s, rafale 20) sont appropriées pour un déploiement de développement ou de petite production. Ajustez selon votre profil de trafic :

  • Nombre d'utilisateurs élevé : Augmentez replenishRate pour accommoder les connexions simultanées du matin. Une valeur de 50 à 100 est raisonnable pour des organisations de plusieurs centaines d'utilisateurs.
  • Posture de sécurité renforcée : Réduisez replenishRate à 3–5 et burstCapacity à 10 pour limiter plus agressivement les tentatives de password-spray.
  • Répartiteur de charge / proxy : Si la gateway se trouve derrière un proxy inverse qui ne transmet pas l'IP réelle dans X-Forwarded-For, toutes les requêtes sembleront provenir d'une seule IP et partageront un seul seau. Configurez votre proxy pour transmettre X-Forwarded-For et définissez spring.cloud.gateway.x-forwarded.for-enabled: true.