Versa Director: Why and What Triggers a User to Go to LOCKED State

Summary

A Versa Director user moves to LOCKED when consecutive failed logins reach the configured max login fail count (default range 3-10). The lockout is automatic and server-side, and is recorded in the user_tracking table that backs the Track > Users > Locked Users view. A lock by itself is not a security incident; it means the credential supplied for that username failed authentication N times.

Applies to: All Directors.

What you will observe

The Locked Users API returns an entry like this:

GET https://<director>/versa/ncs-services/nextgen/track/users/lockedusers?offset=0&limit=25

{
  "userName": "testuser1",
  "accountStatus": "LOCKED",
  "loginFailCount": 3,
  "lockedTime": "2026-06-16 21:09:57.643",
  "remoteAddress": "172.30.59.59"
}

Director logs show three failed attempts from the same source IP, then the lock:

Reason noauth with user=null means the username/password pair did not authenticate (wrong password, wrong username, or no such valid login). Each failure still increments the counter for that username.

How the lockout works

On every failed login the counter increments: loginFailCount = previousCount + 1. When loginFailCount >= maxLoginFailCount, the account is set to LOCKED and lockedTime is stamped.

While locked, each new attempt is rejected before the password is checked. On each attempt Director compares now - lockedTime against defaultUnlockTime. Once the lock has aged past that window it auto-unlocks (status back to ACTIVE, fail count reset to 0). No admin action and no background job is required; the auto-unlock happens lazily on the next login attempt for that user.

On a successful login, the fail count is reset to 0 and the account is ACTIVE.

Key point: the failure counter does NOT decay over time

This is the usual reason a customer sees a user locked frequently. loginFailCount only returns to 0 on (1) a successful login, or (2) an unlock (manual admin unlock, or automatic after defaultUnlockTime elapses).

There is no sliding time window on the failure counter. Failures accumulate across sessions, browsers, scripts and devices until a success or an unlock clears them. So three stray failures spread over a day (a stale saved password, a background API client, a second open browser tab) reach the threshold just as surely as three rapid ones.

Configuration

Set under Administration > User Management > Global Settings (or via the user-settings API). Validated bounds:

Raising max login fail count (up to 10) and keeping default unlock time short reduces nuisance locks while preserving brute-force protection.

Why a specific user gets locked repeatedly (checklist)

1. Stale cached credential. A saved password in a browser, REST/API client, Postman, or automation still using the old password. Each silent retry adds a failure. This is the most common cause, because the counter never decays.
2. Automation or monitoring using that account. Scripts, CI jobs, or another integration polling with bad or expired credentials. Check remoteAddress in the Locked Users entry and trace what runs on that host.
3. Concurrent sessions or multiple tabs re-submitting an expired session or wrong password.
4. Password recently changed but not updated everywhere it is stored.
5. Username typos or an invalid login (Reason noauth, user=null) repeatedly hitting the same tracked record.
6. Account in IN_ACTIVE state is also treated as locked; that is a separate lifecycle state, not failed-login lockout.

How to investigate

1. Open Track > Users > Locked Users and read loginFailCount, lockedTime, and remoteAddress.
2. Correlate by source IP. Grep the Director logs for the username and pull the remoteAddress on each Login Failed line. Identical IP across locks points to a single misconfigured client. Logs: /var/log/vnms/spring-boot/vnms-spring-boot.log and /var/log/syslog. Search for isValid false, Locking user ... as exceeded maximum attempts, and User Account is locked so not processing.

Remediation

• Unlock now: Track > Users > Locked Users > Unlock. Resets the counter to 0.
• Wait it out: the lock auto-clears after defaultUnlockTime on the next attempt.
• Fix the root client: update the stored/automation password at the source identified by remoteAddress. Without this, the user re-locks as soon as the counter refills.
• Tune policy if locks are disruptive: raise maxLoginFailCount and/or shorten defaultUnlockTime.

Short answer for the end-users:

The user is not being locked arbitrarily. It is locked because that username accumulated enough failed authentications (the node's max-login-fail-count) with no successful login in between. Because Director does not time-decay the failure counter, even a handful of failures from a stale saved password or an automated client will keep relocking the same user until that client's credential is corrected or the account is unlocked.