Lockout Policy
This pages explains how the Lockout Policy works, what the implications are for users and how it is set.
From version 5.0.0 of the SDK onwards the lockout policy is configured on the server side and errors will be tracked and count towards the policy regardless of whether they occur on the client or server side. Please contact the Keyless team if you have questions or you would like to request changes to your policy.
Keyless has both client side (applicable to a specific device) and server side (applicable to all users and devices) lockout policies to help prevent brute force attacks.
Client side lockout is configurable in the SDK, and determines how many failed login attempts (lockoutAttemptsThreshold) are allowed over a set time period (lockoutAttemptsResetAfter) before the user is locked out for the set duration (lockoutDuration) on that device.
Account lockoutDuration must be greater than or equal to the lockoutAttemptsResetAfter so that it is not reset by lockoutAttemptsResetAfter.
lockoutDuration: Long, //seconds - default 300 seconds
lockoutAttemptsResetAfter: Long, //seconds - default 180 seconds
lockoutAttemptsThreshold: Int //number - default 5 attemptsServer side lockout works similarly, except applies to all authentication devices for a specific user, and is configured to lock a user out for 10 minutes after 5 failed attempts. A successful login resets the count of failed authentication attempts to zero.
Lockout options and defaults
When a user exceeds a maximum number of failed attempts within a specified tine window, they will be locked out for the duration of the specified time window. This is effectively controlled by three configurable settings, with definitions of each and defaults listed below.
Max failed attempts
How many failed authentications a user is allowed before being “locked out” for the defined suspension period
5
Time window
The number of consecutive failed authentication attempts that must occur within X seconds for authentication to be suspended. Note that any successful authentication resets this to zero.
600 (10 minutes)
Suspension period
How long the account will be suspended, given the max failed attempts is exceeded during the defined time window (in seconds).
600 (10 minutes)
How it works
The policy is applied per Keyless instance, per Keyless ID (representing a single user).
For this reason, customers that are leveraging our component interoperability capability (i.e. with users authenticating on both Web and Mobile) should note that a customer's errors, and any subsequent lockouts, will apply to both Web and Mobile
We count failed authentications across the given time window (see table above). Any successful authentication before reaching the failed attempt threshold resets the failed attempt count to zero.
The lockout policy cannot be disabled. If a non-restrictive behavior is desired, it's recommended to set a high max failed attempts value and/or reduce sensitivity in the time window settings.
If you would like to change the settings at any time, get in-touch with a Keyless team member or [email protected]
When is the lockout policy applied
The lockout policy applies to Authentications but is not applied at all to enrollment flows.
From SDK v5.3.x and above the lockout policy also applies to Account Recovery leveraging the Enroll from Client State flow.
Note in the case of an enrollment failure, the reason the lockout policy cannot be applied is that no Keyless ID has been generated and it is therefore not possible for Keyless to track the relationship between enrollment attempts currently.
If a user is locked-out
Any authentication attempt for that Keyless ID will trigger a
30007"User Lockout" error.They must wait for the lockout duration to expire. There is no way to override or bypass this lockout.
If a user attempts to authenticate while being locked out, the Time Window doesn’t reset even if it’s presented with an error for having reached the maximum number of attempts.
In this case the biometric authentication is not attempted at all and circuits are not consumed.
Last updated
Was this helpful?