Rate Limiting
Hawiyati Gateway applies Redis-backed rate limiting to the IdP login endpoint to protect against brute-force and credential-stuffing attacks. Rate limits are enforced per client IP address using a token-bucket algorithm.
How it works
The hawiyati-gateway module (Spring Cloud Gateway, port 8080) sits in front of hawiyati-http-server. All traffic — including login requests — passes through the gateway before reaching the IdP.
For POST /api/http/login requests, the gateway applies Spring Cloud Gateway's RequestRateLimiterGatewayFilterFactory backed by Redis. The rate limiter uses a token-bucket algorithm:
- Tokens are added to each bucket at a configurable replenish rate (tokens per second).
- Each request consumes one token. A request is allowed if a token is available; otherwise the gateway returns
429 Too Many Requests. - A burst capacity sets the maximum number of tokens a bucket can hold, allowing short bursts above the sustained rate.
Each client IP address gets its own bucket. The IP is extracted from X-Forwarded-For or the TCP remote address by the ipKeyResolver bean. If the remote address is unavailable (for example, in certain proxy configurations), the request is bucketed under the key unknown and is allowed through — this is the fail-open behaviour described below.
Configuration reference
Rate limiting is configured in hawiyati-gateway/src/main/resources/application.yml under the login-rate-limit route.
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
| Property | Default | Description |
|---|---|---|
redis-rate-limiter.replenishRate | 10 | Tokens added to each bucket per second. Represents the sustained allowed rate. |
redis-rate-limiter.burstCapacity | 20 | Maximum tokens a bucket can hold. Allows brief bursts without triggering a 429. |
key-resolver | #{@ipKeyResolver} | Spring Expression Language reference to the key resolver bean. Uses client IP address. |
deny-empty-key | false | Whether to deny requests when the key resolver returns an empty key. false = fail-open. |
REDIS_HOST | localhost | Environment variable for the Redis host. |
REDIS_PORT | 6379 | Environment variable for the Redis port. |
Fail-open behaviour
With deny-empty-key: false, the gateway allows requests through when Redis is unavailable or when the key resolver cannot determine a client key. This is intentional: a Redis outage does not take down the login flow. Availability is prioritised over strict enforcement.
Run Redis in a high-availability configuration (Redis Sentinel or Redis Cluster) to minimise the window during which rate limiting is inactive. See the Operations guide for HA Redis setup instructions.
If you require fail-closed behaviour (deny all requests when Redis is unavailable), set deny-empty-key: true. Be aware that this will cause all login requests to be rejected during any Redis outage.
Rate-limit response
When a request is rejected, the gateway returns:
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
(empty body)
Clients should inspect the X-RateLimit-* headers and implement exponential back-off before retrying. Login form users see the gateway's default 429 page; SAML SP-initiated flows that POST to the login endpoint will also receive a 429 response.
Redis requirements
The gateway requires a running Redis instance to enforce rate limits. Key requirements:
- Redis 6.0 or later (for scripting support used by the token-bucket implementation).
- The gateway connects using reactive Lettuce via
spring-boot-starter-data-redis-reactive. - No password or TLS is configured by default. For production deployments, add
spring.data.redis.passwordand TLS properties. - Rate-limit keys are automatically TTL-managed by Redis; no manual cleanup is required.
Monitoring and observability
Spring Cloud Gateway exposes rate-limit metrics through Spring Boot Actuator. The following metrics are relevant:
| Metric | Description |
|---|---|
spring.cloud.gateway.requests | Total requests by route, status, and HTTP method. Filter by routeId=login-rate-limit and status=429 to track rejected requests. |
spring.cloud.gateway.routes.count | Number of configured routes. Confirms the rate-limit route is loaded. |
Enable the gateway actuator endpoint in application.yml:
management:
endpoints:
web:
exposure:
include: health,metrics,gateway
Tuning guidelines
The default values (10 req/s replenish, 20 burst) are appropriate for a development or small-production deployment. Adjust for your traffic profile:
- High user count: Increase
replenishRateto accommodate concurrent morning sign-ins from many users. A value of 50–100 is reasonable for organisations with hundreds of users. - Stricter security posture: Reduce
replenishRateto 3–5 andburstCapacityto 10 to limit password-spray attempts more aggressively. - Load balancer / proxy: If the gateway sits behind a reverse proxy that does not forward the real client IP in
X-Forwarded-For, all requests will appear to come from a single IP and share one bucket. Configure your proxy to forwardX-Forwarded-Forand setspring.cloud.gateway.x-forwarded.for-enabled: true.