Rate Limiting, Abuse Prevention und API Keys in Symfony

1. Warum Rate Limiting für jede produktive API Pflicht ist

Rate Limiting schützt API-Infrastruktur vor drei Klassen von Problemen: DoS-Angriffen (absichtlich), fehlerhafte Clients (Retry-Loops ohne Backoff) und virales Wachstum (plötzlich hohe Last durch einen neuen Konsumenten). Ohne Rate Limiting kann ein einzelner fehlerhafter Client die gesamte Infrastruktur für alle anderen Clients unnutzbar machen. Das ist kein theoretisches Risiko: in der Praxis sind tight-loop-Fehler in Clients (ein Retry sofort nach einem Fehler, statt mit Backoff) eine häufige Ursache für API-Ausfälle.

Rate Limiting alleine ist nicht ausreichend – es muss mit sinnvollen Limits, transparenten Response-Headers und einer klaren Überschreitungsantwort (429 Too Many Requests) kombiniert werden. Clients müssen wissen, wie viele Anfragen sie noch haben, wann das Limit zurückgesetzt wird und wie sie ihre Anfragerate anpassen können. API-Keys ermöglichen differenzierte Limits: ein Free-Tier-Nutzer bekommt 100 Anfragen pro Stunde, ein Premium-Nutzer 10.000. Das Symfony RateLimiter-Component bietet alle notwendigen Bausteine für produktionstaugliches Rate Limiting.

2. Token Bucket vs. Sliding Window vs. Fixed Window

Der Token-Bucket-Algorithmus ist der flexibelste Rate-Limiting-Ansatz. Jeder Client hat einen "Bucket" mit einer maximalen Kapazität (z.B. 100 Tokens). Pro Zeiteinheit werden Tokens nachgefüllt (z.B. 10 pro Sekunde). Jede Anfrage verbraucht Tokens. Wenn der Bucket leer ist, wird die Anfrage abgelehnt. Der Vorteil: kurze Bursts sind erlaubt, solange der Bucket gefüllt ist. Ein Client kann also 100 Anfragen sofort senden, wenn er lange genug gewartet hat. Das ist fair für Clients, die periodisch viel Last erzeugen.

Das Sliding Window zählt Anfragen in einem gleitenden Zeitfenster. Eine Anfrage zählt immer für die letzte Stunde, egal wann genau sie kam. Das verhindert den "burst at boundary"-Effekt des Fixed Window, bei dem ein Client kurz vor und kurz nach dem Reset-Zeitpunkt doppelte Last erzeugen kann. Das Fixed Window (z.B. 1000 Anfragen pro Stunde, Reset um jede volle Stunde) ist einfach zu implementieren und zu kommunizieren, hat aber den Boundary-Effekt. Für die meisten APIs ist das Sliding Window die beste Balance aus Fairness und Implementierungskomplexität.

# config/packages/rate_limiter.yaml — Symfony RateLimiter configuration
framework:
  rate_limiter:
    # Token bucket — burst-friendly, refills over time
    api_anonymous:
      policy: token_bucket
      limit: 60           # max tokens in bucket
      rate:
        interval: '1 minute'
        amount: 10        # tokens added per interval

    # Sliding window — fair, no boundary burst
    api_authenticated:
      policy: sliding_window
      limit: 1000
      interval: '1 hour'

    # Fixed window per API key tier
    api_premium:
      policy: fixed_window
      limit: 10000
      interval: '1 hour'

    # Strict limit for write endpoints
    api_write:
      policy: sliding_window
      limit: 100
      interval: '1 minute'

    # Login endpoint — very strict
    login_attempts:
      policy: fixed_window
      limit: 5
      interval: '15 minutes'

3. Symfony RateLimiter: Konfiguration und Integration

Das symfony/rate-limiter-Component integriert sich sauber über EventListener oder direkt in Controller-Methoden. Die empfohlene Vorgehensweise für APIs: ein RateLimitSubscriber als KernelEvents::REQUEST-Listener, der vor der Controller-Ausführung prüft. Der Limiter-Key wird aus der Client-Identifikation gebaut – IP-Adresse für anonyme Clients, API-Key-Hash für authentifizierte Clients. Beim Überschreiten des Limits wird sofort eine 429-Response zurückgegeben, bevor der Controller erreicht wird.

Für den Storage-Backend empfiehlt sich Redis für produktive Umgebungen, weil Redis die atomaren Inkrement-Operationen liefert, die für korrekte Sliding-Window-Implementierungen notwendig sind. Symfony konfiguriert den Storage über den cache.pool-Mechanismus. Ein häufiger Fehler: den In-Memory-Store für Rate Limiting in mehrinstanzierten Deployments zu verwenden – jede App-Instanz zählt dann separat, was zu ineffektivem Rate Limiting führt. Redis als gemeinsamer Storage ist Pflicht.

 ['onRequest', 10]];
    }

    public function onRequest(RequestEvent $event): void
    {
        $request = $event->getRequest();

        // Only limit API routes
        if (!str_starts_with($request->getPathInfo(), '/api/')) {
            return;
        }

        $apiKey = $request->headers->get('X-API-Key');
        if ($apiKey !== null) {
            $limiter = $this->apiAuthenticatedLimiter->create(hash('sha256', $apiKey));
        } else {
            $limiter = $this->apiAnonymousLimiter->create($request->getClientIp());
        }

        $limit = $limiter->consume(1);

        if (!$limit->isAccepted()) {
            $retryAfter = $limit->getRetryAfter()->getTimestamp() - time();
            $event->setResponse(new JsonResponse([
                'type' => 'https://mironsoft.de/errors/rate-limit-exceeded',
                'title' => 'Too Many Requests',
                'status' => 429,
                'detail' => sprintf(
                    'Rate limit exceeded. Retry after %d seconds.',
                    max(1, $retryAfter)
                ),
            ], 429, [
                'Content-Type' => 'application/problem+json',
                'Retry-After' => (string) max(1, $retryAfter),
                'X-RateLimit-Limit' => (string) $limit->getLimit(),
                'X-RateLimit-Remaining' => '0',
                'X-RateLimit-Reset' => (string) $limit->getRetryAfter()->getTimestamp(),
            ]));
        } else {
            // Attach rate limit headers to the response via request attribute
            $request->attributes->set('_rate_limit', $limit);
        }
    }
}

4. API-Key-Generierung, Speicherung und Validierung

API-Keys müssen kryptografisch sicher generiert werden. In PHP bedeutet das random_bytes(32) für 256 Bit Entropie, base64url-enkodiert für URL-sichere Darstellung. Ein API-Key wird niemals im Klartext in der Datenbank gespeichert – der Hash (SHA-256 oder bcrypt) wird gespeichert, der Key wird dem Nutzer nur einmal angezeigt. Das gleiche Prinzip wie bei Passwörtern. Für die Identifikation beim Request wird ein Prefix verwendet (z.B. msi_live_ für Production-Keys), der in der Datenbank im Klartext steht und das schnelle Lookup ermöglicht, ohne den vollen Key zu speichern.

Die Validierung folgt einem zweistufigen Ablauf: zuerst wird der Prefix aus dem Key extrahiert und der passende Datenbank-Eintrag geladen, dann wird der Hash des vollständigen Keys gegen den gespeicherten Hash geprüft. Redis-Caching des validierten Keys (TTL: 5 Minuten) reduziert Datenbankzugriffe auf ein Minimum. Revoking ist sofort wirksam, weil gecachte Keys nach dem TTL neu validiert werden müssen. Wichtig: nie einen Timing-Attack-anfälligen String-Vergleich verwenden – immer hash_equals() für Hash-Vergleiche.

5. Abuse Prevention: Muster erkennen und blockieren

Rate Limiting alleine reicht nicht für Abuse Prevention. Ein Angreifer kann viele IP-Adressen rotieren und das Rate Limit pro IP elegant umgehen. Abuse Prevention erfordert zusätzliche Signale: Fingerprinting über User-Agent, Accept-Header-Kombination und TLS-Fingerprint; Verhaltensanalyse (immer dieselben Endpoints in derselben Reihenfolge, kein Browsing-Verhalten); geografische Anomalien (plötzlich tausend Requests aus demselben Rechenzentrum). Diese Signale werden kombiniert und ein Anomalie-Score berechnet.

Einfache Abuse-Prevention-Maßnahmen, die ohne komplexe ML-Modelle sofort Wirkung zeigen: Honeypot-Endpoints, die kein legitimer Traffic treffen sollte; Burst-Detection, die Clients sperrt, die in einem sehr kurzen Zeitfenster viele Anfragen senden; Account-Sharing-Detection über parallele Session-Indikatoren. Für die Implementierung in Symfony eignet sich ein dedizierter AbuseDetectionService, der Metriken in Redis akkumuliert und Schwellwerte auswertet. Gesperrte Clients werden in einem Redis-Set mit TTL geführt und ein 403-Response mit einer klaren Erklärung zurückgegeben.

repository->save($entity);

        return ['prefix' => $prefix, 'key' => $fullKey];
    }

    /**
     * Validates an API key against the stored hash.
     * Uses Redis cache to reduce database load.
     * Never uses == for hash comparison — uses hash_equals().
     */
    public function validate(string $rawKey): ?ApiKey
    {
        $cacheKey = 'apikey_' . hash('sha256', $rawKey);
        $cached = $this->cache->getItem($cacheKey);

        if ($cached->isHit()) {
            return $cached->get(); // null means invalid but cached
        }

        $prefix = substr($rawKey, 0, self::PREFIX_LENGTH);
        $entity = $this->repository->findByPrefix($prefix);

        $isValid = $entity !== null
            && hash_equals($entity->getKeyHash(), hash('sha256', $rawKey))
            && !$entity->isRevoked();

        $result = $isValid ? $entity : null;
        $cached->set($result)->expiresAfter(self::CACHE_TTL);
        $this->cache->save($cached);

        return $result;
    }

    public function revoke(string $keyId): void
    {
        $entity = $this->repository->find($keyId);
        if ($entity !== null) {
            $entity->revoke();
            $this->repository->save($entity);
            // Cache will expire naturally — revocation is eventually consistent
        }
    }
}

6. Rate-Limit-Headers: RFC 6585 und RateLimit-Header-Fields

Transparente Rate-Limit-Headers sind für API-Konsumenten essenziell: sie ermöglichen adaptive Clients, die ihre Anfragerate selbst anpassen, bevor ein 429 kommt. Der IETF-Draft "RateLimit Header Fields for HTTP" definiert drei Header: RateLimit-Limit (maximale Anfragen im Fenster), RateLimit-Remaining (verbleibende Anfragen) und RateLimit-Reset (Unix-Timestamp des nächsten Resets). Zusätzlich ist Retry-After bei 429-Responses Pflicht – entweder als Anzahl Sekunden oder als HTTP-Datum.

Das Symfony RateLimiter-Component liefert alle notwendigen Informationen über das RateLimit-Objekt: getLimit(), getRemainingTokens() und getRetryAfter(). Ein Response-Listener (oder Middleware) fügt diese Informationen als Header zu jeder API-Response hinzu – nicht nur bei 429, sondern bei jeder Antwort. So können Clients proaktiv drosseln, bevor sie das Limit erreichen. Wichtig: bei Redis-Clustern können die Werte durch Replikationsverzögerungen leicht ungenau sein – das ist akzeptabel und sollte in der API-Dokumentation erwähnt werden.

7. Differenzierte Limiting-Strategien nach Endpoint und Tier

Nicht alle Endpoints haben dieselbe Last und dasselbe Missbrauchspotenzial. GET-Endpunkte für Catalog-Daten können großzügigere Limits haben als POST-Endpunkte, die Bestellungen anlegen. Suchanfragen mit komplexen Queries belasten den Datenbankserver mehr als einfache ID-Lookups. Eine differenzierte Strategie definiert Limit-Profile pro Endpoint-Gruppe und API-Tier. In Symfony kann das über ein Attribut am Controller elegant gelöst werden: #[RateLimit(policy: 'api_write')] überschreibt das globale Limit für einzelne Endpoints.

Tier-basiertes Rate Limiting erfordert, dass der API-Key mit Tier-Informationen verknüpft ist. Ein Security Voter oder ein dedizierter TierResolver ermittelt den Tier des authentifizierten Clients und wählt den passenden RateLimiterFactory. Free-Tier: 100 req/h, Starter: 1.000 req/h, Pro: 10.000 req/h, Enterprise: Custom. Die Limits müssen in der API-Dokumentation klar kommuniziert werden, idealerweise pro Endpoint in der OpenAPI-Spezifikation als Extension (x-rate-limit).

8. Vergleich der Rate-Limiting-Strategien

Die Wahl des Rate-Limiting-Algorithmus hat direkte Auswirkungen auf Fairness, Implementierungskomplexität und Client-Erfahrung. Die folgende Tabelle vergleicht die drei gängigsten Algorithmen anhand der relevantesten Kriterien.

9. Zusammenfassung

Rate Limiting, API-Key-Management und Abuse Prevention sind kein nachträgliches Feature, sondern integraler Bestandteil einer produktiven API. Das Symfony RateLimiter-Component mit Redis-Backend bietet alle Bausteine für Token Bucket, Sliding Window und Fixed Window. API-Keys werden mit random_bytes(32) generiert, als SHA-256-Hash gespeichert und über Redis gecacht. Abuse Prevention ergänzt das Rate Limiting um Verhaltensanalyse und Anomalie-Detection. Transparente Rate-Limit-Headers ermöglichen adaptive Clients. Differenzierte Limits nach Endpoint-Typ und API-Tier machen das System fair und skalierbar.

Der häufigste Fehler in der Praxis: Rate Limiting wird pro App-Instanz im Speicher gehalten, statt in einem gemeinsamen Redis. Bei horizontaler Skalierung ist das Limit dann faktisch Instanz-Anzahl-mal höher als konfiguriert. Redis als zentraler Storage ist die einzige korrekte Lösung für mehrspielige Deployments.

10. FAQ: Rate Limiting und API Keys in Symfony