What Brute Force Protection Actually Defends Against

Keycloak’s Brute Force Protection, configured within a Realm’s Security Defenses, exists to defend against a brute force attack — an attempt to guess a user’s password by trying many candidate passwords in rapid succession against a single account. The defense works by counting failed login attempts and temporarily (or, in a stricter configuration, permanently) locking an account once a threshold of failures is crossed.

Why “Tuning” Becomes a Genuinely Advanced Problem at Scale

At a modest scale, Keycloak’s defaults are perfectly reasonable and rarely need adjustment. Scale changes the underlying statistics: a large user base has a proportionally larger number of people who genuinely mistype their own password, more shared network egress points making many real users look, from Keycloak’s perspective, like a single source, and attackers who are themselves increasingly aware of these thresholds and design their attacks specifically to stay under them. Tuning at scale is the discipline of adjusting these settings so the defense remains meaningfully protective against real attackers while producing an acceptably low rate of friction for real, legitimate users.

The Quick Login Check Window

Keycloak distinguishes between an ordinary, human-paced sequence of failed attempts and a suspiciously rapid one, using a configurable Quick Login Check window. Failures arriving faster than a human could plausibly type them are treated as a stronger signal of automated attack activity, and can be weighted or reacted to differently than a slower, more human-paced sequence of mistakes.

Why This Distinction Matters at Scale

A genuine human occasionally fat-fingering a password rarely produces failures faster than roughly one per second; a scripted, automated attack frequently does. Tuning the Quick Login Check window thoughtfully lets a large deployment apply its most aggressive response specifically to the traffic pattern most likely to represent genuine automated abuse, rather than treating every failure identically regardless of its actual timing signature.

The Minimum Quick Login Wait as a Distinct Lever

Closely related to the Quick Login Check window is a separate setting controlling the minimum delay imposed specifically after a rapid-fire failure is detected. This lever lets a deployment respond to a suspiciously fast sequence of failures with an immediate, short penalty distinct from the escalating lockout schedule covered in the next chapter — a first line of friction introduced the moment automated, non-human-paced behavior is actually observed, rather than waiting for the full failure threshold to be crossed before reacting at all.

Calibrating This Window Requires Real Traffic Data, Not Guesswork

Because human typing and retry cadence genuinely varies across different populations — a technically sophisticated internal user base types and retries differently than a general consumer audience — a genuinely well-tuned Quick Login Check window is calibrated against a deployment’s own actual, observed login timing data rather than an assumed, generic figure borrowed from an unrelated deployment’s own experience.

How Escalating Lockouts Work

The Wait Increment setting controls how much longer each successive lockout becomes compared to the one before it, up to a configured Max Wait ceiling. A first lockout might last a short period, a second lockout for the same account somewhat longer, and so on, until the ceiling is reached — a pattern commonly called exponential backoff.

The Tuning Trade-off Between Deterrence and User Frustration

A steep, rapidly escalating backoff schedule meaningfully discourages a patient attacker willing to wait out short lockouts and retry, since each subsequent attempt costs them progressively more time. The same steep schedule, applied to a legitimate user who has simply forgotten which of several similar passwords they’re using this month, can turn a minor inconvenience into a genuinely long, frustrating lockout — precisely the kind of trade-off this entire guide is built around making deliberately rather than by accident.

Choosing a Reasonable Ceiling Based on Genuine User Patience

A Max Wait ceiling deserves to be calibrated against how long a genuine, legitimate user can reasonably be expected to wait before either abandoning the login attempt entirely or escalating to a support channel. A ceiling measured in a small number of minutes generally preserves meaningful deterrent value against an automated attacker, who typically wants to run through very large numbers of guesses quickly, while still remaining tolerable for an occasional legitimate user who simply mistyped their password a few times in a row.

Resetting the Escalation Ladder on a Genuine Success

It’s worth being explicit that a successful login should reset the escalation ladder back to its starting point, rather than leaving a user permanently on an elevated wait tier from some earlier, unrelated lockout. Without this reset, a single, long-past sequence of typos could leave a legitimate user facing a needlessly long wait on every subsequent, entirely unrelated mistake for far longer than the underlying risk actually justifies.

How Permanent Lockout Differs

Under Permanent Lockout, once the failure threshold is crossed, the account remains disabled indefinitely, requiring a deliberate, explicit administrative action (or, depending on configuration, a specific self-service recovery flow) to re-enable it, rather than automatically clearing itself after a wait period.

Why This Is Rarely the Right Default at Genuine Scale

At a large scale, Permanent Lockout’s requirement for explicit administrative intervention creates a direct, ongoing operational burden — a support team fielding a meaningful, continuous stream of “why is my account locked” requests, each requiring a human to manually investigate and re-enable. A temporary, self-expiring lockout with a well-tuned escalating wait, covered in Chapter 4, generally achieves comparable protective value with far less ongoing operational cost at real scale.

Building a Deliberate Escalation Path Instead of a Binary Choice

Rather than treating Permanent and Temporary Lockout as a single, all-or-nothing switch applied uniformly, a more advanced approach can treat repeated lockout events on the same account as an escalating signal in their own right — a first temporary lockout handled routinely, but a pattern of several distinct lockout events within a short overall window triggering a more deliberate, human-reviewed response, even for an account that wouldn’t otherwise be flagged for Permanent Lockout by default. This turns lockout history itself into a useful signal for prioritizing where genuine, scarce security attention gets spent, rather than treating every lockout as an identical, equally uninteresting event.

What This Setting Actually Controls

The Failure Reset Time determines how long a count of failed attempts is remembered before being cleared automatically, even if the user never actually succeeds in logging in during that window. Without this setting, a failure count would accumulate indefinitely across unrelated login sessions spread over days or weeks.

Tuning This Against Real User Behavior Patterns

A reset window set too short can allow a patient attacker to simply wait for the count to clear and resume guessing with a fresh allotment of attempts, undermining the whole point of counting failures in the first place. A reset window set too long can mean an unrelated failed attempt from weeks ago is still silently counted against a user today, contributing to an unexpected lockout that feels, from the user’s perspective, entirely unprovoked by anything they just did.

Why This Is Harder Than It First Appears

If each Node kept its own, entirely local failure count, an attacker (or simply an unlucky, unevenly load-balanced legitimate user) whose requests happened to spread across several different Nodes could accumulate far more actual attempts than the configured threshold intends, since no single Node would ever individually see the full picture.

How the Shared, Distributed Cache Solves This

Keycloak addresses this by storing failure counts in the same distributed Infinispan cache covered in this series’ Stateless Clustering guide, ensuring every Node consults and updates a single, consistent, shared count regardless of which specific Node actually handled any individual failed attempt.

Replication Latency and the Narrow Race-Condition Window

Even in a genuinely healthy cluster, replicating a failure count across every Node takes a small, nonzero amount of time. In the narrow window between a failure being recorded on one Node and that update fully propagating to every other Node, a nearly simultaneous second attempt landing on a different Node could theoretically be evaluated against a slightly stale count. At realistic replication speeds and realistic attacker request rates, this window is generally too narrow to meaningfully undermine the overall protection, but it’s worth understanding as an inherent property of any distributed counting system, rather than assuming the count is somehow instantaneously and perfectly synchronized across every Node at every possible moment.

Why This Reinforces the Case for Layered Defense

This small, inherent imprecision is a further, concrete reason the layered approach from Chapter 10 matters: a defense that depends on perfect, zero-latency precision from a single mechanism is more fragile than one where several complementary mechanisms, each with their own different failure characteristics, combine to produce robust protection overall.

Why This Assumption Breaks Down

Any detection strategy that weighs a request’s originating network address heavily runs directly into the reality that many real, distinct users can share the exact same visible address — a large corporate office behind one outbound proxy, a mobile carrier’s shared address pool, or a public Wi-Fi network at an airport or conference. From Keycloak’s perspective, dozens or hundreds of genuinely different people can appear to be a single source.

Why Per-Account Counting Remains the Sounder Default

This is a core reason Keycloak’s Brute Force Protection is fundamentally structured around counting failures per user account rather than per network address — an approach that sidesteps the shared-address problem entirely, since it tracks the actual thing genuinely being attacked (one specific account) rather than a network address that may or may not correspond to a single real actor.

What Per-Account Counting Misses

An attacker running a credential stuffing attack — trying one password guess each against thousands of different accounts, rather than many guesses against one account — largely evades per-account failure counting entirely, since no single account ever accumulates enough failures to trigger its own lockout.

Why an Additional, Complementary Signal Is Needed

This is precisely the gap a network-address-aware signal, used carefully and in addition to (never as a full replacement for) per-account counting, is meant to fill: an unusually high volume of failed attempts against many different accounts originating from one specific source is a meaningfully different, and often more actionable, signal than the failure count on any single account in isolation.

Where a Web Application Firewall (WAF) Fits

A Web Application Firewall, typically sitting in front of Keycloak at the network edge, can apply broader, network-level rate limiting and anomaly detection — including the credential-stuffing pattern described in Chapter 9 — before a request ever reaches Keycloak’s own login endpoint at all.

Avoiding Redundant or Conflicting Thresholds

Without deliberate coordination, an organization can end up with two separate, independently tuned thresholds — one at the WAF, one inside Keycloak — that interact in confusing, hard-to-diagnose ways: a user blocked by the WAF’s own rate limit might appear, from Keycloak’s perspective, to simply never have attempted a login at all, obscuring the real cause of a reported access problem from whoever is trying to troubleshoot it.

Attempt Made. A login attempt reaches whichever Keycloak Node the Load Balancer happened to route it to.

Current State Checked. That Node consults the shared, distributed failure cache to see whether this account is currently locked, and if not, how many prior failures are already on record within the current reset window.

Authentication Evaluated. The actual credential check proceeds normally, entirely independent of the brute force machinery itself.

Outcome Recorded. A failure increments the shared count (and, depending on timing, may register against the Quick Login Check window from Chapter 3); a success clears the count entirely, resetting the account to a clean slate.

Threshold Evaluated. If the updated failure count meets or exceeds the configured Max Login Failures, a lockout begins, with its duration governed by the Wait Increment and Max Wait settings from Chapter 4.

Lockout Expiry or Reset. A temporary lockout eventually expires on its own; independently, the whole failure count itself may also clear via the Failure Reset Time from Chapter 6, even without an intervening lockout.

graph LR
    A["Login Attempt"] --> B["Check Current
Failure State"]
    B --> C["Evaluate
Credentials"]
    C -->|"Success"| D["Clear Failure Count"]
    C -->|"Failure"| E["Increment Count"]
    E --> F{"Threshold
Reached?"}
    F -->|"Yes"| G["Lockout Begins"]
    F -->|"No"| H["Count Persists Until
Reset Window Expires"]
    

Credential Stuffing Deserves Its Own Explicit Mitigation Plan

Because per-account Brute Force Protection alone doesn’t meaningfully address credential stuffing, as covered in Chapter 9, a mature security posture at scale treats this as a distinct, separately mitigated risk — typically through the layered WAF or external anomaly-detection approach from Chapter 10, rather than assuming Keycloak’s own default settings alone provide adequate protection against this specific, increasingly common attack pattern.

Regularly Revisit Tuning Assumptions as the Threat Landscape Shifts

An attacker population is not static — techniques evolve, automated tooling improves, and attackers actively probe deployed thresholds to learn how to stay beneath them. A tuning configuration that was well calibrated a year ago deserves periodic, deliberate re-examination against current, observed attack patterns, rather than being treated as a permanently solved problem.

Attackers Deliberately Probe for a Deployment’s Actual Thresholds

A sufficiently patient, sophisticated attacker doesn’t need to guess a deployment’s specific thresholds blindly — they can often infer them directly through careful, deliberate testing, gradually increasing their own attempt rate against a disposable or low-value account until they observe a lockout, then calibrating their real attack to stay just under that discovered ceiling. This is a further, concrete argument for the layered, complementary defenses covered throughout this guide: a single, purely threshold-based mechanism is inherently learnable by exactly this kind of deliberate probing, while a combination of several different, independently tuned signals is considerably harder for an attacker to fully map out and quietly work around.

Documenting Tuning Rationale for Future Reviewers

Because tuning decisions rest on genuinely specific, deployment-dependent trade-offs rather than universal best practices, it’s worth explicitly documenting why each current threshold was chosen — what data informed it, what trade-off it was deliberately accepting — so a future reviewer isn’t left guessing whether an unusual-looking setting reflects careful, deliberate reasoning or simply an untouched, unexamined default.

Building a Feedback Loop, Not a One-Time Configuration

The most effective large-scale deployments treat these metrics as inputs into a recurring, scheduled review process — revisiting the actual Max Login Failures, Wait Increment, and Failure Reset Time settings on a regular cadence, informed by genuinely observed data from the metrics above, rather than tuning once at launch and never revisiting the decision again.

Segmenting Metrics by Population, Not Just in Aggregate

An aggregate, deployment-wide lockout rate can look perfectly healthy while masking a genuinely serious problem affecting one specific segment of the user base — a particular geographic region, a particular type of client application, or users behind one especially large shared corporate network. Breaking these metrics down by meaningful segments, rather than only ever reviewing a single blended, overall figure, surfaces exactly this kind of localized problem far sooner than an aggregate view alone ever would.

Correlating Lockout Spikes With Known External Events

A sudden, sharp spike in lockout volume is worth correlating against known external events before assuming it reflects a genuine attack — a recent, organization-wide password-policy change, a widely publicized data breach at an unrelated third-party service prompting many users to change passwords everywhere at once, or a major application update that altered how credentials are entered. Distinguishing a spike driven by one of these ordinary, explainable causes from a spike genuinely driven by malicious activity is an essential part of interpreting this monitoring data correctly, rather than reacting to every spike as if it were necessarily an active attack in progress.

Segmenting Thresholds by Genuine Risk Context, Where Supported

Rather than applying one uniform threshold across every possible login context, some deployments deliberately apply a more lenient threshold to lower-risk contexts (an internal tool used only by trusted, known staff) and a stricter one to higher-risk contexts (a public-facing customer login), reflecting a genuine difference in both the underlying attack surface and the real cost of a false lockout in each setting.

Clear, Actionable Self-Service Recovery

Because some rate of legitimate lockout is generally an accepted, unavoidable cost of any meaningful protection, providing a clear, low-friction, genuinely self-service path back into a locked account — rather than a dead end requiring a support ticket — substantially reduces the real-world cost of an occasional false positive without weakening the underlying protection itself.

Good Patterns

• Tune based on genuinely observed data from Chapter 14’s metrics, rather than intuition or an untested assumption carried over from a much smaller deployment
• Layer per-account counting with a complementary, network-aware signal to close the credential-stuffing gap described in Chapter 9
• Provide clear, self-service recovery to substantially reduce the real-world cost of an occasional, unavoidable false positive
• Revisit tuning on a recurring, scheduled cadence, treating it as an ongoing practice rather than a one-time launch decision

Anti-patterns to Avoid

The Single Most Common Mistake: Treating This as “Set and Forget”

If there’s one mistake more common than any individual misconfigured threshold, it’s treating Brute Force Protection tuning as a task completed once, at launch, rather than as an ongoing practice requiring the ongoing monitoring, feedback loop, and periodic re-tuning covered throughout this guide.

Tuning Brute Force Protection well at scale is ultimately less about finding one perfect set of numbers and more about building the discipline to keep revisiting those numbers as real, observed data comes in — treating the whole system as a living, monitored piece of infrastructure rather than a checkbox ticked once during initial setup and never opened again.