Lockout Policy

This pages explains how the Lockout Policy works, what the implications are for users and how it is set.

v 5.0.0 and above

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.

v 4.8.2 and below

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 attempts

Server 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.

Lockout configurations	Description	Defaults (SaaS customers)
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.

  • 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

• A successful login before reaching the failed attempt threshold will reset the failure 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.

When is the lockout policy applied

• The lockout policy applies to Authentications only and is not applied at all to enrollments.

  • Note the reason is that, in the case of an enrollment failure, no Keyless ID has been generated and it is therefore not possible for Keyless to track the relationship between specific users

• The only exception to this applies to the account recovery / new device activation use case.

  • In this case we only lockout in the case of multiple Face Not Matching (30004 error code), which in-turn will trigger a 523 error.

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.