Let’s define the term plainly before looking at how Keycloak implements it.

A brute force attack is when someone (or, far more commonly, an automated program) tries to log into an account by guessing the password over and over, often trying thousands or millions of combinations very quickly. Brute force detection is the defensive feature that watches for this pattern of repeated failed login attempts and reacts — usually by temporarily locking the account or slowing down further attempts — before the attacker can succeed through sheer repetition.

Brute force detection is one of Keycloak’s built-in security features, configured entirely inside the realm settings, requiring no custom code. It sits quietly in the background of every login attempt, watching for the telltale pattern of repeated failure that separates a forgetful legitimate user from an automated attack.

To appreciate the defense, it helps to understand exactly what it’s defending against.

Passwords, by nature, have a limited set of possible combinations. A short, simple password might have only a few million possible variations. A computer program can try enormous numbers of these variations extremely quickly, especially if nothing is stopping it. Left completely unprotected, a login form is essentially an open invitation for this kind of automated guessing.

Keycloak’s brute force detection doesn’t try to guess whether an attempt is malicious by analyzing intent — that’s very hard to do reliably. Instead, it relies on a simple, powerful signal: repeated, consecutive failure on the same account is, statistically, almost always a sign of an attack rather than an honest mistake.

A handful of simple ideas combine to form the entire protection mechanism.

Consecutive Failures

Keycloak tracks how many times, in a row, a login attempt for a specific account has failed. A single successful login resets this counter back to zero — only unbroken strings of failure count toward a lockout.

Lockout

Once the failure count crosses a configured threshold, the account is temporarily locked. Further login attempts — even with the correct password — are rejected until the lockout period ends.

Wait Increment

Rather than a single fixed lockout, Keycloak can be configured so that each additional lockout after the first grows progressively longer, making repeated attack attempts increasingly costly for the attacker.

A look at the moving pieces involved in this protection mechanism.

This protection applies at the realm level, meaning it’s automatically active for every user and every client application inside that realm — no per-application code changes are required. Because it plugs directly into the same event pipeline used for logging, brute force protection also naturally contributes to the audit trail every login attempt already generates.

Let’s trace exactly what happens behind the scenes on each login attempt.

flowchart TD
    A[Login Attempt Received] --> B{Account Currently Locked?}
    B -->|Yes| C[Reject Immediately, Log Attempt]
    B -->|No| D{Password Correct?}
    D -->|Yes| E[Reset Failure Counter, Grant Access]
    D -->|No| F[Increment Failure Counter]
    F --> G{Threshold Reached?}
    G -->|Yes| H[Lock Account for Wait Time]
    G -->|No| I[Allow Another Attempt]
        

Seeing this play out against a real automated attack makes the mechanism click.

sequenceDiagram
    participant Attacker as Automated Script
    participant KC as Keycloak
    Attacker->>KC: Guess #1 (wrong)
    KC-->>Attacker: Denied, failure count = 1
    Attacker->>KC: Guess #2 (wrong)
    KC-->>Attacker: Denied, failure count = 2
    Attacker->>KC: Guess #3 (wrong)
    KC-->>Attacker: Denied, failure count = 3, threshold hit
    KC->>KC: Lock account for wait period
    Attacker->>KC: Guess #4 (even if correct)
    KC-->>Attacker: Rejected instantly, account locked
        

Notice the crucial detail in the final step: once locked, Keycloak rejects the attempt without even checking whether the submitted password happens to be correct. This is intentional — it means even if the attacker’s fourth guess would have worked, the lockout still holds, buying real protective time.

Keycloak offers more than one way to shape how strict this protection should be.

Like every security control, brute force detection is a genuine balancing act.

A few deeper points worth understanding before relying on this feature alone.

It’s One Layer, Not the Whole Defense

Brute force detection protects against repeated guessing on one account, but it should be combined with other defenses — strong password policies, multi-factor authentication, and rate limiting at the network level — for well-rounded protection.

Distributed Attacks Can Evade Simple Thresholds

An attacker spreading a small number of guesses across thousands of different accounts, or trying one guess per account instead of many, can sometimes stay just under the per-account failure threshold. This is why broader network-level monitoring is a useful complement.

Account Enumeration Risk

Care should be taken that lockout messages don’t accidentally reveal whether a given username exists at all in the system, since that information itself can help an attacker narrow their targets.

Watching how this feature behaves in production is just as important as configuring it correctly.

A few tested ways to configure this feature well, and a few traps to avoid.

A practical checklist for tuning and operating this feature well.

Seeing this feature applied to real situations helps make the concept concrete.

No, it must be explicitly enabled and configured in the realm’s security settings. It doesn’t require any custom code, but it isn’t automatically turned on out of the box.

Not necessarily. Once an account is locked, Keycloak rejects further attempts without even checking whether the submitted password is correct — the lockout itself is what blocks access, independent of what’s being entered.

Yes, this is a known trade-off. Anyone who knows a valid username could submit a few wrong passwords on purpose to lock that account, which is why thresholds should be chosen carefully rather than set as strictly as possible.

Not on its own — since it tracks failures per account, an attacker trying one guess against many different accounts may stay under any single account’s threshold. Broader network-level monitoring helps cover this gap.

It unlocks automatically once the configured wait time has passed. A permanently locked account, by contrast, requires an administrator to manually unlock it.

No, they solve different problems and work best together. Brute force detection slows down guessing attempts; MFA ensures that even a correct password alone still isn’t enough to log in.

Brute force detection in Keycloak is a built-in defense that watches for repeated, consecutive login failures on an account and responds by temporarily — or, if configured, permanently — locking that account before an automated guessing attack can succeed through sheer repetition. It works by tracking a failure counter per account, comparing it against a configurable threshold, and rejecting further attempts once that threshold is crossed, regardless of whether the next guess would have been correct. Configured well, alongside strong passwords and multi-factor authentication, it turns what could be a fast, cheap automated attack into a slow, impractical one. Configured poorly, it can either fail to stop determined attackers or become a tool attackers use to lock out legitimate users — which is exactly why understanding its mechanics, not just flipping it on, matters.