Keycloak brute force detection and password policies

Keycloak keeps a failure count for each user account and makes the lockout decision from that count, so the first thing to understand is what counts as a failure and what clears it. A failed password check for a known username adds to that user's record. Confirm in the server administration guide for your exact version whether a successful sign-in resets the count, whether attempts against unknown usernames are tracked, and whether counting also considers the client address. Since Keycloak 26.8, login failures are persisted to the database by default according to the upgrade notes, so counts survive restarts and are shared by every node in a cluster. That supports consistent enforcement, but it also means your database now records more security-relevant writes, and your capacity plan should reflect that.

Temporary and permanent lockout differ mainly in who ends the lock. A permanent lockout disables the account until an administrator re-enables it, so every triggered lock becomes a helpdesk ticket and possibly an identity recovery task. A temporary lockout blocks sign-in only for a set period and then allows attempts again, which keeps routine recovery automatic but gives an attacker a repeating opportunity after each wait. Neither mode is sufficient on its own. Decide which mode fits each population, such as workforce users with managed recovery or customer accounts with self-service reset. Then confirm the exact unlock path in the administration guide, including whether administrators can clear a lock early and whether the user is told that the account is locked.

The failure reset window and the wait increments interact in ways that surprise teams who set them independently. The reset window controls how long earlier failures count toward the threshold. If it expires before enough failures accumulate, the counter starts over, so a slow, spaced-out guessing pattern may never trigger a lock. Wait increments control how long a temporary lock lasts after repeated lockouts, typically growing with each cycle up to a maximum wait. Read the two together. A long reset window combined with aggressive increments can keep a user locked for a long time after a short burst of mistakes, while a short window with small increments barely slows a patient attacker. Build a table of the exact sequence your settings produce, and confirm its semantics against the version you run.

The central trade-off is between stopping guessing and creating denial-of-service risk against legitimate users. A low threshold with long waits makes online guessing expensive, but anyone who knows a username can deliberately fail sign-in and lock out a colleague or customer. That pattern lands on your support queue and disrupts work. A higher threshold protects legitimate users from that nuisance but leaves more room for guessing, so the right setting depends on what else stands in the way, such as strong password rules, multi-factor authentication, and alerting on spikes in failures. Decide the threshold per user population and per sign-in path, and record the reasoning, because auditors and incident responders will ask why the values were chosen.

Before anything reaches production, check the behavior in a separate test realm. Set the candidate values, script a controlled series of failed sign-ins against a test user, and confirm when the lock starts, how long it lasts, how it clears, and what the user sees at each step. Restart the server or a cluster node partway through the sequence to confirm that the persisted failure records keep the count. Then confirm that lock events appear in your event logging and metrics pipeline so the security team can see them. Finally, check that your runbook names who may unlock accounts and how that action is recorded. Take the actual values from the administration guide and your own test results, not from this page.

Keycloak's password policy is a set of rules configured per realm, and it governs the passwords that Keycloak stores and sets itself. The rules fall into four general families. The first shapes new passwords, for example through minimum length, character requirements, exclusion of the username, or custom pattern checks. The second is history, which blocks reuse of recent passwords. The third covers expiry and forced change, which set how long a password stays valid and when a user must replace it. The fourth is blacklist control, which rejects passwords known to be weak or compromised. Before you configure anything, decide which families your written password standard requires, because each one needs its own setting and its own evidence.

The policy does not reach every account that signs in to your applications. Users federated from LDAP or Active Directory often keep their passwords in the source directory, so Keycloak may not validate or store those credentials in the way the realm policy assumes. Whether a change made through Keycloak is written back to the directory, and whether the realm rules apply at all, depends on the federation mode and the sync settings. Users who sign in through an external identity provider, whether an OIDC or SAML broker or a social provider, authenticate at that provider, and the Keycloak password policy governs none of those credentials.

This creates a planning task that is easy to miss. Build an inventory of every user source in each realm, and mark which accounts have passwords that Keycloak actually controls. For the rest, the controls must sit in the source system: the directory's password policy, the external provider's rules, or multi-factor authentication enforced at the point of sign-in. Auditors who test password requirements will ask which system enforces each control, so the answer should be written down per user source, not assumed from the realm settings.

Confirm the details in the Keycloak server administration guide for your release. Check the exact rule names, the order in which Keycloak evaluates them, and whether a policy applies the same way on a user's password change as on an administrator's reset. Those behaviors can differ, and they determine what a user sees at each step. Then test each rule in a non-production realm with accounts from every user source you run, and keep the results as evidence of the configuration. Re-run the tests after each upgrade, because the defaults and the handling of federated accounts can change between releases.

Keycloak stores a hash of each password, computed with a configurable algorithm, rather than keeping passwords in any recoverable form. The hashing settings belong to each realm, so a workforce realm and a customer realm can use different configurations. The supported options include Argon2 and PBKDF2, and the parameters that tune each algorithm, such as iteration counts or memory cost, can change between releases. Before you change anything, record the algorithm and parameters active in every realm, then confirm the defaults for the release you run in the Keycloak server administration guide and its release notes. Treat those documented values as a starting point for your own testing, since the exact default algorithm and parameters must be confirmed for your release.

The main trade-off is CPU cost. A stronger hashing configuration takes longer to compute on every password check, so sign-in latency rises for each user, and the effect is largest when many people sign in at the same time, such as after a maintenance window or at the start of a working day. Bulk operations feel the change too. Importing users with password credentials, or any job that creates or verifies many passwords, takes longer as the parameters increase. Measure sign-in latency on the hardware and node count you plan to run, at the peak login rate you expect, and include the import job in the same test. A setting that looks acceptable for a single test login can still build a queue on a busy cluster.

Existing password hashes are typically upgraded when the user next signs in successfully. Keycloak checks the submitted password against the stored hash and, when the realm's current settings differ, stores a new hash under those settings. A realm can therefore hold hashes from several algorithms or parameter sets at once, and accounts that never sign in again keep their old hashes. Ask the team to confirm how the release in use handles this upgrade path, whether any administrative action can trigger rehashing for dormant accounts, and whether your compliance evidence requires a count of accounts still on older settings. Record that residual population in your risk register, and confirm that password reset produces hashes under the new settings.

FIPS-oriented environments may restrict which algorithms you can select, so a choice that works in a standard build may be unavailable or unsupported in a FIPS configuration. Confirm the permitted algorithm list with the documentation for your release and with your cryptographic validation owner before you schedule a change, because the approved set depends on the cryptographic module in use. A practical sequence starts with a documented baseline, then a staging realm loaded with production-like user data, then a latency test at expected peak load that includes the import path, and finally a rollback plan that restores the previous realm settings. Test brute force detection and password policy settings in the same pass, because failed login handling also adds load and affects the results.