Spring Cloud Gateway rate limits: derive the key from authenticated identity

Last updated: 1 Oct 20264 min read

tutorial

A Redis token bucket only isolates callers when its key resolver uses a trusted principal or tenant claim.

The bucket needs an owner

A rate limit on the public path /api/orders is global if every request resolves to the same key. A key taken from ?tenant= is attacker-controlled. For an authenticated API, derive the key from the verified principal or a validated tenant claim and include the route's policy name when limits differ. The built-in principal-name resolver is useful only when the selected security chain actually authenticates the request. Tenant claim validation must happen before bucket assignment.

Size the token bucket deliberately

RedisRateLimiter uses replenishRate, burstCapacity and requestedTokens. A burst capacity of 47 with a replenish rate of 7 can admit a short spike and then recover roughly seven tokens per second, assuming one token per request. The defaults for empty keys deny requests; decide explicitly how anonymous endpoints are handled. A 429 should carry a client-facing retry policy, while gateway retries must not multiply calls to a saturated downstream service.

Test identity and failure

Send two authenticated principals and prove their buckets are separate. Then send a spoofed tenant header and verify it cannot change the key. Test Redis unavailability: whether the gateway fails closed or degrades is a product policy, not something to discover during an outage. The YAML sketch assumes a configured KeyResolver bean and reactive Redis dependency.

Implementation sketch

spring:
  cloud:
    gateway:
      server:
        webflux:
          routes:
            - id: order-api
              uri: http://order-service
              predicates:
                - Path=/api/orders/**
              filters:
                - name: RequestRateLimiter
                  args:
                    key-resolver: "#{@verifiedTenantKeyResolver}"
                    redis-rate-limiter.replenishRate: 7
                    redis-rate-limiter.burstCapacity: 47

Cost and verification

Each admitted request checks Redis. A shared Redis outage can affect every protected route, while overly broad keys make unrelated users contend for one bucket.

Common Mistakes

Do not key a tenant bucket from a query parameter or unchecked header.
Do not assume rate limiting replaces downstream admission control.
Do not forget the empty-key and Redis-outage behaviors in tests.