Setting Up User Account Lockout
Locking User Accounts Based on Failed Authentication Attempts
If a user tries to authenticate multiple times and fails, you may want to prevent them from trying further. Typically you’d do so after a certain number of failures. Configuring this can help prevent brute force attacks, which is where attackers attempt to figure out your users' passwords by guessing repeatedly.
If you’re concerned about breached passwords compromising your systems, you may also be interested in Reactor, which can detect breached passwords on user login.
To accomplish this rules based account lockout, you need to take two steps:
Create a user action representing the account lock behavior
Configure tenant settings defining when to apply the lock and the duration of the lock
If you are interested in rate limiting other actions, such as forgot password requests or two-factor messages, you can use advanced threat detection to do so.
Creating the User Action
The first step is to create a user action, under Time-based and Prevent login checkboxes.. Give it a name of "Account Lock". Check the
There are other configuration options available, including localization and user notification options; check out the User Action APIs for more information.
Next, configure your tenant, under User action to your newly created user action,
You can configure the number of failed attempts which will trigger the lockout, the time period during which the allotted failures must take place, and the duration of the lockout.
For example, the below settings will allow five failed attempts in sixty seconds. Once the fifth attempt fails, the account will be locked for three minutes. However, each additional failed attempt restarts the three minute lockout.
What Happens When The Account is Locked
When a user account has been locked by this mechanism, they’ll be able to sign in after the duration has elapsed. All login paths will be locked. This user will not be able to log in using the FusionAuth login pages, and any login API access will return a 4xx error, as specified in the Login API docs.
This is what a user will see if the standard FusionAuth OAuth theme is used:
Since this is a temporary action, the user details screen in the administration user interface will not display a red lock. That is reserved for locks not applied by the user action rules, such as by users that have been soft deleted.
An administrator can manually remove or extend this lock. You can also modify the action applied to a user by using the Actioning Users API. Administrators can see the action under the user’s "Current actions" tab.
If you are interested in analytics around the number of lockout actions that are taken, you may want to listen for these webhooks and ingest the data into a reporting tool.
user.actionwhich will fire when the defined action starts and ends.
user.login.failedwhich will fire when a user login attempt fails
How helpful was this page?
See a problem?
File an issue in our docs repo
Have a question or comment to share?
Visit the FusionAuth community forum.