- v1.0.0-latest-prod
This article describes the configuration and usage of the user lockout feature. This feature allows the locking of a user account after a certain number of failed login attempts in a period of time.
Configuration can be performed in a two ways:
Per Authorization Server (May be set programmatically, directly in the BLC_AUTHORIZATION_SERVER table or via admin)
Global defaults, via properties
A combination of the two can be used also, with Authorization Server specific lockout settings taking precedence over global defaults.
The following properties are available when configuring the user lockout feature:
| Name | Description | Authorization Server Field | Global Property |
|---|---|---|---|
Failed login Attempts Allowed |
The number of consecutive failed login attempts allowed before a user is locked. Note that this is how many failed login attempts are allowed. Setting this to 5, for example, would cause the user to be locked out on the sixth failed login attempt. Leaving this blank or setting it to zero will allow unlimited login attempts. |
AuthorizationServer#failedLoginAttemptsAllowed |
broadleaf.auth.user-lockout.failed-login-attempts-allowed |
Lockout Duration Minutes |
How long a user account will remain locked after exceeding the number of failed login attempts allowed. Leaving this blank will cause users to never be unlocked. |
AuthorizationServer#lockoutDurationMinutes |
broadleaf.auth.user-lockout.lockout-duration-minutes |
Login Fail Decay Minutes |
How long it takes for failed login attempts to decay. Login attempts that have decayed are not counted toward the failed login attempt allowed value. |
AuthorizationServer#loginFailDecayMinutes |
broadleaf.auth.user-lockout.login-fail-decay-minutes |
If a user is locked out, a org.springframework.security.authentication.LockedException is thrown. The default messaging can be customized via the message key login.error.user-locked.
Manually locking/unlocking a user can be achieved in the admin via specific customer or admin user’s page using the lock option on these pages.
Unlock actions should use the UserLockoutService, which has two methods: UserLockoutService#lockUser(User) and UserLockoutService#unlockUser(User). Manually updating
the User record without using the UserLockoutService may result in undesired behavior, such as the user becoming locked again on their next login attempt.
It shouldn’t usually be necessary to update a user record manually to unlock them, but if needed it can be done by following the steps below.
The user lock itself is determined via the BLC_USER table. Here, two fields are taken into account:
IS_LOCKED - The boolean that is checked when determining if a user is locked or not
USER_LOCKED_TIME - The time that the user account was locked. Should be null if the user is not locked, and non-null if the user is locked.
Locking/Unlocking a user manually via the database should take into account both of the above fields.
In addition, manually unlocking via DB should also be sure to update any entries related to the user in the BLC_USER_LOGIN_ATTEMPT table. Any entries for this user should have their CONSIDERED column set to N. This will result in these records not being counted against the number of login attempts allowed on the user’s next login attempt.