Brute force attacks

A brute force attack attempts to guess a user’s password by trying to log in multiple times. Keycloak has brute force detection capabilities and can temporarily disable a user account if the number of login failures exceeds a specified threshold.

Keycloak disables brute force detection by default. Enable this feature to protect against brute force attacks.
Procedure

To enable this protection:

  1. Click Realm Settings in the menu

  2. Click the Security Defenses tab.

  3. Click the Brute Force Detection tab.

    Brute force detection

    brute force

Keycloak can deploy permanent lockout and temporary lockout actions when it detects an attack. Permanent lockout disables a user account until an administrator re-enables it. Temporary lockout disables a user account for a specific period of time. The time period that the account is disabled increases as the attack continues.

When a user is temporarily locked and attempts to log in, Keycloak displays the default Invalid username or password error message. This message is the same error message as the message displayed for an invalid username or invalid password to ensure the attacker is unaware the account is disabled.

Common Parameters

Name Description Default

Max Login Failures

The maximum number of login failures.

30 failures.

Quick Login Check Milliseconds

The minimum time between login attempts.

1000 milliseconds.

Minimum Quick Login Wait

The minimum time the user is disabled when login attempts are quicker than Quick Login Check Milliseconds.

1 minute.

Permanent Lockout Flow

  1. On successful login

    1. Reset count

  2. On failed login

    1. Increment count

    2. If count greater than Max Login Failures

      1. Permanently disable user

    3. Else if the time between this failure and the last failure is less than Quick Login Check Milliseconds

      1. Temporarily disable user for Minimum Quick Login Wait

When Keycloak disables a user, the user cannot log in until an administrator enables the user. Enabling an account resets the count.

Temporary Lockout Parameters

Name Description Default

Wait Increment

The time added to the time a user is temporarily disabled when the user’s login attempts exceed Max Login Failures.

1 minute.

Max Wait

The maximum time a user is temporarily disabled.

15 minutes.

Failure Reset Time

The time when the failure count resets. The timer runs from the last failed login.

12 hours.

Temporary Lockout Algorithm

  1. On successful login

    1. Reset count

  2. On failed login

    1. If the time between this failure and the last failure is greater than Failure Reset Time

      1. Reset count

    2. Increment count

    3. Calculate wait using Wait Increment * (count / Max Login Failures). The division is an integer division rounded down to a whole number

    4. If wait equals 0 and the time between this failure and the last failure is less than Quick Login Check Milliseconds, set wait to Minimum Quick Login Wait.

      1. Temporarily disable the user for the smaller of wait and Max Wait seconds

'count` does not increment when a temporarily disabled account commits a login failure.

The downside of Keycloak brute force detection is that the server becomes vulnerable to denial of service attacks. When implementing a denial of service attack, an attacker can attempt to log in by guessing passwords for any accounts it knows and eventually causing Keycloak to disable the accounts.

Consider using intrusion prevention software (IPS). Keycloak logs every login failure and client IP address failure. You can point the IPS to the Keycloak server’s log file, and the IPS can modify firewalls to block connections from these IP addresses.

Password policies

Ensure you have a complex password policy to force users to choose complex passwords. See the Password Policies chapter for more information. Prevent password guessing by setting up the Keycloak server to use one-time-passwords.