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:

    1. Create a user action representing the account lock behavior

    2. 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 Settings → User Actions. Give it a name of "Account Lock". Check the Time-based and Prevent login checkboxes.

    Setting up the account lockout user action

    There are other configuration options available, including localization and user notification options; check out the User Action APIs for more information.

    Tenant Configuration

    Next, configure your tenant, under Tenants → Default. Then navigate to the "Password" tab. Under the "Failed authentication settings" section, change the User action to your newly created user action, Account Lock.

    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.

    Configuring user account lockout settings

    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:

    What the user sees when they try to log in to a locked account

    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.

    What an admin sees when viewing a locked out user's account

    Webhooks

    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.action which will fire when the defined action starts and ends.

    • user.login.failed which will fire when a user login attempt fails

    Feedback

    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.