Account Lockout

Production - AccountLockoutService, configurable via SecurityProperties

Account lockout protects against brute-force password attacks by temporarily locking accounts after a configurable number of failed login attempts.

6.4.10Lockout Mechanism

How It Works

Each failed login attempt increments user.failedLoginAttempts
When attempts reach the threshold, user.lock(durationMinutes) is called
The user cannot authenticate until the lockout period expires or an admin unlocks the account

private void handleFailedLogin(User user) {
    user.incrementFailedLoginAttempts();
 
    if (user.getFailedLoginAttempts() >= securityProperties.getLockout().getMaxAttempts()) {
        user.lock(securityProperties.getLockout().getLockoutDurationMinutes());
    }
 
    userRepository.save(user);
}

Auto-Unlock

The User.isAccountLocked() method checks if the lockout period has expired:

public boolean isAccountLocked() {
    if (!locked) return false;
    if (lockedUntil != null && Instant.now().isAfter(lockedUntil)) {
        unlock();  // Auto-unlock
        return false;
    }
    return true;
}

6.4.11Configuration

Property	Default	Description
`security.lockout.max-attempts`	5	Failed attempts before lockout
`security.lockout.lockout-duration-minutes`	30	Lockout duration in minutes

Successful Login Reset

On successful authentication, the failed attempt counter is reset:

user.resetFailedLoginAttempts();
// Sets failedLoginAttempts = 0 and lockedUntil = null

Error Response

When a locked account attempts to login:

{
  "status": 423,
  "code": "ACCOUNT_LOCKED",
  "message": "Account is locked. Please try again later."
}

HTTP status 423 (Locked) is returned.

Enable & Disable Password Policies