Lock a VRS Keycloak user after too many wrong passwords, show a clear message in the VRS UI, and unlock the user in Keycloak when needed.
Configure Brute Force Detection on the Keycloak realm your environment uses for VRS login. Lock duration and failure count are controlled in Keycloak, not by a VRS environment variable.
The Keycloak Admin console layout can look slightly different by install. Follow the same setting names below.
What Users See in VRS
|
Case |
Snackbar text |
|---|---|
|
Wrong password (account not locked yet) |
|
|
Account locked by Brute Force Detection |
|
|
Successful login |
|
The UI does not show remaining attempts or a countdown. After the Keycloak wait time (or after an admin unlock), the user can try again.
Prerequisites
-
VRS apis and front-end are deployed and reachable.
-
You can open Keycloak Admin for the realm used by VRS login (for example VRS or Expertflow; use whatever your site uses).
-
The confidential client service account VRS uses can call Keycloak Admin APIs for users and attack detection. Assign at least realm-management roles
view-usersandquery-users(see below). Without those roles, locked users may still see only the invalid-password message.
Service Account Roles (Required for Locked Snackbar)
VRS must call Keycloak Admin as the confidential client service account. Without the right roles, the lock check returns 403, APIs fail open, and the UI only ever shows Invalid username and/or password even when Keycloak shows the user locked.
-
Open Clients → select the confidential client VRS uses for login (for example
vrsorcim). -
Open Service accounts roles → Assign role.
-
Filter by realm-management and assign
view-usersandquery-users.
If Brute Force Detection locks the user but the service account is missing those roles, Admin APIs return 403 and VRS always returns the invalid-password snackbar. Assign the roles, then retest.
1. Open Realm Settings
-
Log in to the Keycloak Admin console for your environment.
-
Select the realm used for VRS login.
-
In the left menu under Configure, open Realm settings.
You land on the General tab. Next open Security defenses:
2. Enable Brute Force Detection
-
Open the Security defenses tab.
-
Open the Brute force detection sub-tab.
-
Configure the settings as shown below, then Save.
|
Setting |
Value |
Notes |
|---|---|---|
|
Enabled |
On |
Turns on lockout. Must be On for any of the other settings to apply. |
|
Max login failures |
5 |
Number of wrong passwords before a temporary lock. |
|
Permanent lockout |
Off |
Keep Off so the lock can clear after Max wait (temporary lock, not a permanent BFD lockout policy). |
|
Wait increment |
10 Minutes |
Initial lock wait duration. |
|
Max wait |
10 Minutes |
Cap on lock wait. Set equal to Wait increment for a simple fixed wait. |
|
Failure reset time |
12 Hours |
How long failure history is remembered. |
|
Quick login check milliseconds |
0 |
Use 0 to avoid odd early locks. |
|
Minimum quick login wait |
empty |
Leave empty (or 0) when Quick login check is 0. |
Configured Brute force detection:
Important: Lock duration and failure count are controlled only in Keycloak. Changing these values changes lock behavior for all realm users. There is no separate VRS config.env lock timer.
3. What a Temporary Lock Looks Like
After the user exceeds Max login failures, Keycloak locks the account. You typically need to clear both Temporarily locked and Disabled / Enabled before login works again.
Users List
While locked, the Users list may show a Temporarily locked Status badge (depending on your Keycloak Admin UI). If there is no badge, open the user Details to confirm the lock.
User Details
Open the user (Details). Confirm both:
-
Temporarily locked is On.
-
The account is not Enabled (Disabled / Enabled Off). Placement of the Enabled control can differ by Keycloak Admin UI; look for Enabled / Disabled on the user Details page.
4. Admin unlock (temporary lock)
To unlock immediately without waiting for Max wait, clear both controls:
-
Open Users → select the user.
-
On Details, set Temporarily locked to Off.
-
Set the account to Enabled (On).
-
Click Save.
After a full unlock, Temporarily locked is Off and Enabled is On:
The user can log in again with the correct password (subject to any other Keycloak rules).
5. If You Only Clear Temporarily Locked
When the account is locked, Keycloak uses two controls. You must fix both for login to work again.
|
Control |
After a lock |
What you must do |
|---|---|---|
|
Temporarily locked |
On |
Set to Off and Save, or wait for Max wait. |
|
Disabled / Enabled |
Enabled Off (account Disabled) |
Set Enabled to On and Save. |
If you only turn Temporarily locked Off and leave the account Disabled, the user still cannot log in. The Users list may then show Disabled. Always finish unlock with Enabled On.
4. Admin Unlock (Temporary Lock)
-
Valid login →
Login Successful. -
Wrong password under the max →
Invalid username and/or password. -
Fail until Max login failures (for example, 5) →
Account is locked. Try again later.. In Keycloak, open user Details and confirm Temporarily locked On (and that the account is not Enabled). -
Wait Max wait or admin unlock (Temporarily locked Off and Enabled On) → correct password works again.
7. Troubleshooting
|
Symptom |
Likely cause |
|---|---|
|
Always “invalid password” even when Details shows Temporarily locked On |
Service account missing |
|
Users list looks normal while the user cannot log in |
Status badge may be missing in your Admin UI; open Details and check Temporarily locked / Enabled |
|
Users list shows Disabled after you turned Temporarily locked Off |
Expected; account is still Disabled; set Enabled On and Save |
|
Locks too early |
Quick login check not 0; Wait values too small |
|
User stuck after wait / after clearing temp lock |
Temporarily locked was cleared but the account is still Disabled; set Enabled On and Save |
|
UI shows raw |
Login error handling is not mapping Keycloak lock responses to the snackbar message |