Keycloak’s brute force protection is designed to stop attackers from guessing user passwords by limiting the number of failed login attempts allowed.
Let’s see it in action. Imagine a user, "testuser," is trying to log in.
# Simulate a failed login attempt (this is a conceptual representation, actual logs vary)
# Keycloak server logs might show:
# 2023-10-27 10:00:00,123 ERROR [org.keycloak.services.resources.LoginActionsService] (executor-thread-1) Failed login for user 'testuser' from 192.168.1.100
If "testuser" tries again with the wrong password:
# Second failed attempt
# Keycloak server logs:
# 2023-10-27 10:00:05,456 ERROR [org.keycloak.services.resources.LoginActionsService] (executor-thread-2) Failed login for user 'testuser' from 192.168.1.100
And a third time:
# Third failed attempt
# Keycloak server logs:
# 2023-10-27 10:00:10,789 ERROR [org.keycloak.services.resources.LoginActionsService] (executor-thread-3) Failed login for user 'testuser' from 192.168.1.100
After a configured number of failures (let’s say 5), Keycloak will temporarily block further login attempts for that user or from that IP address.
# Fourth failed attempt
# Keycloak server logs:
# 2023-10-27 10:00:15,012 ERROR [org.keycloak.services.resources.LoginActionsService] (executor-thread-4) Failed login for user 'testuser' from 192.168.1.100
# Fifth failed attempt
# Keycloak server logs:
# 2023-10-27 10:00:20,345 ERROR [org.keycloak.services.resources.LoginActionsService] (executor-thread-5) Failed login for user 'testuser' from 192.168.1.100
# Sixth failed attempt - now blocked
# Keycloak server logs:
# 2023-10-27 10:00:25,678 WARN [org.keycloak.services.resources.LoginActionsService] (executor-thread-6) Too many failed login attempts for user 'testuser' from IP 192.168.1.100. Account or IP is temporarily blocked.
The system’s core problem it solves is preventing automated scripts (bots) from systematically trying every possible password combination against user accounts, which is known as a brute-force attack. Without this, an attacker could eventually gain access to legitimate accounts simply by trying enough passwords. Keycloak addresses this by acting as a gatekeeper, imposing a temporary "timeout" on users or IP addresses that exhibit suspicious login behavior.
Internally, Keycloak maintains a count of failed login attempts. This count is associated with either the specific username or the IP address from which the login attempt originated. When the count for a given entity (user or IP) exceeds a predefined threshold within a specified time window, Keycloak triggers a temporary lockout. This lockout prevents any further login attempts from that entity for a set duration.
The key levers you control are found within the Keycloak Administration Console under Authentication -> Flows -> Browser -> Configure (for the default browser flow). Here, you’ll find the "Brute Force Protection" component.
You can configure:
- Max attempts: The maximum number of failed login attempts allowed before an account or IP is considered for blocking. A common starting point is
5. - Min wait (seconds): The minimum duration (in seconds) an account or IP will be blocked after the
Max attemptsthreshold is reached.60seconds is a reasonable starting point. - Max wait (seconds): The maximum duration (in seconds) an account or IP can be blocked. This prevents indefinite lockouts.
3600seconds (1 hour) is often used. - Lockout duration (seconds): The total time an account or IP remains blocked. This is calculated dynamically based on
Min waitandMax wait.
Additionally, you can enable "Permanent Lockout" which, if checked, will permanently block the user account after reaching the attempt limit, requiring manual intervention by an administrator to unlock. This is usually reserved for highly sensitive environments.
The "Failure Factor" setting, often set to 1.0, determines how the lockout duration scales. A value of 1.0 means the lockout duration increases linearly with each subsequent failure beyond the initial Max attempts. For instance, if Min wait is 60 seconds and Max wait is 3600 seconds, and a user fails 6 times, they might be locked for 60 seconds. If they fail 7 times, the lockout might increase, potentially reaching the Max wait if failures continue.
It’s crucial to understand that the brute force protection can operate on two levels: per user and per IP address. By default, Keycloak often tracks failures per IP address first. If an IP address exceeds the Max attempts, that IP is blocked. If the "User Lockout" setting is also enabled in the Brute Force Protection configuration, Keycloak will also track failures per user. When a user account reaches the Max attempts limit, that specific user account is locked, regardless of the IP address they are logging in from. This dual approach provides more robust protection.
The "Wait increment" setting dictates how much the lockout duration increases for each additional failed attempt beyond the initial Max attempts. For example, if Max attempts is 5, Min wait is 60, and Wait increment is 30, the 6th failed attempt might result in a 60-second lockout, the 7th in a 90-second lockout, and so on, up to the Max wait.
After configuring brute force protection, you might encounter issues with legitimate users being temporarily locked out if they frequently mistype their passwords. The next logical step in securing your login process will involve exploring account recovery mechanisms, such as password reset flows, to ensure users can regain access if legitimately locked out.