User Lockout in PhenixID Server

This article describes the User Lockout Settings in PhenixID Server.

The reader of this document should have some basic knowledge about PhenixID Server.

NOTE: Hard lockout should only be enabled in PhenixID Server version 2.6 or later.

Overview

This document describes the User Lockout settings available in PhenixID Server.

The user lockout count will be increased independent of where the login fails. Meaning that both wrong password and wrong one-time password will trigger the same counter.

Lockout can be set in two different ways. Soft lockout and hard lockout. A soft lockout will be released automatically after the time specified. A hard lockout must be released by an administrator.

We will make changes to the file phenix-store.json.
So please make sure that you have a recent copy/backup of this file.

NOTE: Hard lockout should only be enabled in PhenixID Server version 2.6 or later.

Instruction

As of version 2.6 of Phenix Server, user lockout configuration is done in the valve, LockoutCheckValve, in conjunction with one or more of the following valves, that support user lockout:
    LDAPBindValve
    OTPValidationValve
    TokenValidationValve.

The example below shows the configuration on user/password validation pipe and LDAPBindvalve.
The same procedure should be used for otp validation pipe with OTPValidationValve and TokenValidationValve.

Possible configuration on these valves is:

"userid_param_name" : "{{request.User-Name}}", parameter representing the unique user id
"lockout_enabled" : "true/false",
"lockout_login_attempts" : "3", attempts before we lock the account
"lockout_time" : "60", the amount of time, in minutes, the user is locked out/not able to authenticate
"lockout_login_window" : "30", the time window the user can enter x login attempts before lockout

To check if the user is already locked, the valve 'LockoutCheckValve' must be configured first in respective pipe, se example below.

Example: User lockout on RADIUS username & password scenario

This example assumes that there is already configuration in place for RADIUS username & password.

Start by choosing the 'Execution flow' tab on the scenario. This is where we will add the valve, LockoutCheckValve, to support user lockout.

Click the 'Add valve' button and add the LockoutCheckValve to the configuration. 

This new valve should be the first valve for every pipe it's in. Drag and drop the valve in place.

Adjust the settings accordingly and make sure to set the parameter 'userid_param_name'  to: '{{request.User-Name}}'

Next, expand the LDAPBindValve, go to the tab 'Lockout' and enable lockout for the valve. Make sure to verify the settings according to the ones set on 'LockoutCheckValve'.

Click the 'Save' button to activate the new configuration.

Lock status in MFA Admin

From version 2.6, user lockout status can be administrated in MFA Admin. Search for the account and go to the tab 'LOCK STATUS':

Example of an account that has been locked out:

As seen in the example above, the configuration has only allowed for two failed attempt before locking the account. The padlock is not locked because this is a soft lockout. The lock will be released when the configured 'lockout_time' has been reached.

Hard lockout

NOTE: Make sure that the version of PhenixID Server is 2.6 or later before enabling hard lockout.

Hard lockout needs to be enabled on both 'LockoutCheckValve' and one or more of the valves:
    LDAPBindValve
    OTPValidationValve
    TokenValidationValve

To set hard lockout on 'LockoutCheckValve', go to the tab 'Advanced', click on the pencil besides 'Pipe valves' and locate the 'LockoutCheckValve' where you want to enable hard lockout.
Add the following parameters to the valve:

"lockout_hard_enabled": "true",
"lockout_hard_threshold": "2"

Should now look like this:

Click Stage changes and commit changes.

The value for 'lockout_hard_treshold' is the number of soft lockouts before hard lockout trigger.

Now go to the login scenario, press 'Execution flow', expand LDAPBindValve, go to the lockout tab and enable hard lockout, like this example:

The value for 'HARD LOCKOUT TRESHOLD' is the number of soft lockouts before hard lockout trigger.

Example in MFA Admin of an account that has a hard lockout:

As seen in this example, an administrator needs to unlock the account. It will mot be unlocked when the configured 'lockout_time' has been reached.