Turning on brute force detection in Keycloak without locking out real users
New Keycloak realms allow unlimited password guesses. Here is how to choose a lockout mode and sensible limits, and how to unlock a user who gets caught.
A new Keycloak realm, including master, starts with brute force detection switched off. Anyone who can reach the login page can try passwords for any account as fast as they like. Turning it on takes a minute; the only real decision is which lockout mode to use.
What realmlint reports
MEDIUM Brute-force protection is off [brute-force-disabled]
- brute-force detection is disabled
Choose a lockout mode
Keycloak offers four settings for Brute Force Mode:
- Disabled: no protection. This is the default.
- Lockout temporarily: after too many failures the account is locked for a while, and the wait grows with repeated failures. Use this one.
- Lockout permanently: the account stays locked until an admin unlocks it. This turns brute force protection into an easy way for anyone to lock your users out, so avoid it for user-facing realms.
- Lockout permanently after temporary lockout: temporary lockouts first, then a permanent one after a set number of them. Reasonable for a small admin-only realm.
Fix it in the admin console
- Open the realm and go to Realm settings, then the Security defenses tab, then Brute force detection.
- Set Brute Force Mode to Lockout temporarily.
- Lower Max login failures from its default of 30. Something between 5 and 10 stops guessing without catching people who mistype.
- Keep the defaults for the rest: Wait increment of 1 minute, Max wait of 15 minutes and Failure reset time of 12 hours. Repeated attacks slow down a lot, and a real user is never locked out for long.
- Click Save.
- Repeat for the master realm. It holds your Keycloak admins, so it needs protection most.
Unlocking a user
If a real user gets locked, open them under Users. The Temporarily locked switch shows the lock; turn it off to unlock them straight away. The users list also has Unlock all users for clearing every temporary lock in the realm after an attack.
Brute force detection counts failures per account, not per IP address. Rate limiting at your load balancer or WAF is still worth having in front of Keycloak.
Fix it in a realm file
{
"realm": "myrealm",
"bruteForceProtected": true,
"permanentLockout": false,
"failureFactor": 10,
"waitIncrementSeconds": 60,
"maxFailureWaitSeconds": 900,
"maxDeltaTimeSeconds": 43200
}
Check it worked
kc.sh export --realm myrealm --file myrealm.json realmlint check myrealm.json
The brute-force-disabled finding should be gone. Check the password policy next, under Authentication, then Policies, then Password policy: realmlint reports a missing or weak one as weak-password-policy.