Interface LoginAttemptPolicy

All Known Implementing Classes:
InMemoryLoginAttemptPolicy, NoopLoginAttemptPolicy, StoreBackedLoginAttemptPolicy
public interface LoginAttemptPolicy
Policy that throttles repeated failed login attempts.

The expected call sequence inside an authentication flow is:

  1. beforeAttempt(LoginAttemptContext) — before the password check. If the decision is not allowed, skip the check and return the user a generic "try again later" error.
  2. recordSuccess(LoginAttemptContext) — after the password check succeeds. Resets the failure counter.
  3. recordFailure(LoginAttemptContext) — after the password check rejects the credentials. Increments the failure counter and may escalate the throttling decision for subsequent attempts.

Implementations decide which key to track by — typically a combination of username and clientAddress. The default InMemoryLoginAttemptPolicy tracks the combined key plus the raw username so an attacker cannot cycle clients to escape the counter.

  • Method Details

    • beforeAttempt

      LoginAttemptDecision beforeAttempt(LoginAttemptContext context)
      Decides whether the attempt described by context may proceed. Implementations must not mutate the failure counter here — that is the responsibility of recordSuccess(LoginAttemptContext) / recordFailure(LoginAttemptContext) after the actual check.
      Parameters:
      context - attempt context
      Returns:
      decision; never null

    • recordSuccess

      void recordSuccess(LoginAttemptContext context)
      Records a successful attempt. Implementations typically reset the per-key failure counter so a successful login lifts a partial lockout immediately.
      Parameters:
      context - attempt context

    • recordFailure

      void recordFailure(LoginAttemptContext context)
      Records a failed attempt. Implementations typically increment a per-key counter and may escalate the throttling decision.
      Parameters:
      context - attempt context