Rate Limiting and Throttling
Relevant source files
The following files were used as context for generating this wiki page:
Rate limiting and throttling in the FLEXT Auth project serve as a primary security layer designed to prevent brute-force attacks and resource exhaustion. The system monitors authentication attempts per user and restricts access when pre-defined thresholds are exceeded within specific time windows. This ensures system stability and protects user identities from automated credential stuffing.
The implementation relies on a centralized manager that tracks failed attempts and enforces a sliding window strategy. It integrates with the broader Authentication Service to intercept requests before processing sensitive cryptographic operations.
Sources: src/flext_auth/_utilities/_managers/rate_limiter.py:22-30, src/flext_auth/history.json:285-290
Architecture and Components
The rate limiting system is structured around the FlextAuthRateLimiter class, which resides within the FlextAuthRateLimiterManagers namespace. It utilizes an in-memory storage mechanism to track attempt data, associated with specific usernames.
Key Logic Flow
The rate limiter operates by checking the current state of a user's attempts against a temporal window. If a user exceeds the maximum allowed attempts, the system returns a failure result with a standardized error message.
The diagram shows the integration of the rate limiter into the authentication flow, ensuring checks occur before authentication and failures are recorded after.
Sources: src/flext_auth/_utilities/_managers/rate_limiter.py:34-51
Rate Limiting Configuration
The behavior of the rate limiter is governed by constants defined in the domain layer. These limits define the strictness of the throttling policies across different time scales.
| Configuration Constant | Value | Description |
|---|---|---|
MAX_ATTEMPTS_DEFAULT | 5 | Default maximum failed attempts before lockout. |
LOCKOUT_DURATION_MINUTES | 30 | Standard duration for a user lockout. |
MAX_REQUESTS_PER_MINUTE | 60 | Global limit for requests per minute. |
MAX_REQUESTS_PER_HOUR | 3600 | Global limit for requests per hour. |
_window_minutes | 15 | The internal sliding window size for attempt tracking. |
Sources: src/flext_auth/history.json:237-241, src/flext_auth/_utilities/_managers/rate_limiter.py:32
Implementation Details
Attempt Tracking and Cleanup
The manager maintains a mapping of usernames to ManagersAttemptData. Every time a check or record operation is performed, a cleanup process filters out timestamps that fall outside the defined window (e.g., 15 minutes).
def _cleanup_window(self, username: str, now: datetime) -> t.Auth.ManagersAttemptEvents:
window_start = now - timedelta(minutes=self._window_minutes)
attempt_data = self._attempts.get(username)
if attempt_data is None:
return []
attempts_value = attempt_data.get("attempts")
# Returns only attempts greater than window_start
recent_attempts = [attempt for attempt in attempts_value if attempt > window_start]
return recent_attempts
Sources: src/flext_auth/_utilities/_managers/rate_limiter.py:68-83
Results and Error Handling
FLEXT Auth uses a functional Result pattern for rate limiting responses. When a limit is breached, it specifically returns a failure with the message: "Too many failed attempts. Please try again later.". This prevents leaking specific details about the lockout state while informing the client of the throttle.
Sources: src/flext_auth/_utilities/_managers/rate_limiter.py:46-49, tests/README.md:280-290
Security Context
Rate limiting is categorized as a "Resilience" and "Performance" testing concern within the FLEXT quality gates. It is essential for protecting the bcrypt hashing process, which is computationally expensive (configured at 12 rounds by default) and thus a target for Denial of Service (DoS) attacks.
The relationship between the manager and the central constants registry ensures a single source of truth for security thresholds.
Sources: src/flext_auth/history.json:200-205, pyproject.toml:500-510, examples/advanced_features_02.py:75-80
Summary
The Rate Limiting and Throttling system provides a robust defense mechanism by tracking failed authentication events within a sliding 15-minute window. By enforcing a 5-attempt limit and offering global request throttling (up to 3600 requests/hour), FLEXT Auth maintains high availability and protects against brute-force exploitation. Its integration into the Result-based application flow allows for clean error propagation without exposing sensitive security state.