Account Lockout Policies

What Are Account Lockout Policies?

Account Lockout Policies are the profiles that determine how the failed attempts are counted and what is done at which thresholds in the authentication and MFA steps in the AGS access flow. The attempts are counted in the selected scope (the username, the IP address, the username + IP or a custom combination consisting of smart variables); when the count reaches the Warning Threshold value a warning is shown to the user, at the Captcha Threshold value a CAPTCHA is added to the login form, and at the Lockout Threshold value the scope key is locked for the Lockout Duration. The attempts are counted within the Attempt Tracking Window duration; the attempts outside the window are not taken into account.

The policies are bound at two levels: the Default Lockout Policies list in the AGS settings of the vService is valid for the authentication provider steps; an Authentication Providers profile uses, replaces, adds to or turns off these defaults with the Lockout Behavior setting. In the Multi-Factor Authentication (MFA) step only the own policy list of the MFA profile is applied; the vService defaults do not reach this step. Four built-in profiles come with TR7; a new vService comes with Default Username Lockout and Default IP Lockout by default.

4

Policy Scope

Username Only · Username + IP · IP Address Only · Custom Combination

3 Levels

Warning → CAPTCHA → Lock

The default thresholds in the form are 3 / 4 / 5 failed attempts

30 min

Lockout Duration

30 seconds – 24 hours; on repeated lockouts the duration is multiplied

24 h

Attempt Tracking Window

The attempts counted within 5 minutes – 365 days

4

Built-in Profiles

Default Username · Default IP · Default MFA · Default Username + IP

Lockout

Live Management

The locks are removed and the counters are reset from the Lockout tab on the vService screen

How does it work?

1. The policy is defined on this screen: the Policy Scope and the three thresholds (Warning Threshold, Captcha Threshold, Lockout Threshold), the lockout duration and the tracking window are configured; a CAPTCHA Providers profile is selected for the CAPTCHA level.
2. The policy is added to the Default Lockout Policies list in the vService AGS settings or is selected in the Lockout Policies list of an Authentication Providers profile.
3. Every failed verification is counted for the scope key of the policy (e.g. the username); as the thresholds are reached, the warning, CAPTCHA and lock levels come into play. More than one policy (e.g. with the username and the IP scope) works together on the same vService.
4. The locks and the failed attempt counters are monitored on the Lockout tab on the vService screen; they are cleared manually with Clear Lockouts and Reset Failures.

Built-in Profiles

Profile	Policy Scope	Warning Threshold	Captcha Threshold	Lockout Threshold	Lockout Duration (the first / the longest)	Attempt Tracking Window
Default Username Lockout (the vService default)	Username Only	3	3 (Standard TR7 CAPTCHA)	5	5 minutes / 24 hours	24 hours
Default IP Lockout (the vService default)	IP Address Only	20	25 (Standard TR7 CAPTCHA)	50	15 minutes / 1 hour	1 hour
Default MFA Lockout	Username Only	3	The CAPTCHA off	5	5 minutes / 24 hours	24 hours
Default Username + IP Lockout	Username + IP	3	3 (Standard TR7 CAPTCHA)	5	5 minutes / 24 hours	24 hours

The built-in MFA profiles carry the Default MFA Lockout policy; only this policy is applied in the MFA step. Since the built-in profiles are not in the list, they are not edited or deleted from this screen.

Operational Best Practices

• The scopes must be used together. The username scope alone allows the attacker to lock a single account and leave the legitimate user outside (denial of service); it must be used together with a policy with the IP scope and with the Captcha Threshold before the lock.
• The threshold order. It must be Warning Threshold ≤ Captcha Threshold < Lockout Threshold and Lockout Threshold > Warning Threshold; otherwise the profile is not saved.
• The CAPTCHA provider. While Enable Captcha Protection is on, a provider must be selected; the field comes with Standard TR7 CAPTCHA selected.
• The lock duration and the window. A short first lock (5–15 min) does not punish the legitimate user; since the duration is multiplied on repeated lockouts, the attacker still slows down. The tracking window must be kept long enough to cover the ordinary wrong password behavior.
• The policy condition. With Policy Condition the policy is applied only to certain requests (e.g. a certain path or header); when no condition is defined, the policy is always valid.
• The references before deleting. The delete confirmation does not show the usage locations; the vServices and the provider/MFA profiles that use the policy must be checked on the Used in tab in the preview.

How to Add?

A new Account Lockout Policies profile is added through the TR7 web management interface with the following steps:

1. The Configuration Menu is opened by clicking the TR7 logo at the bottom left.
2. The AGS → Protection Policies → Account Lockout Policies → Add steps are followed.
3. A unique and descriptive name is entered for the profile.
4. The Policy Scope is selected; the thresholds, the lockout duration and the tracking window are configured and a provider is selected for the CAPTCHA level.
5. The profile is added by clicking the Add button.

TIP

Reaching the page via quick search

Instead of navigating the menu step by step, the related page is reached directly by using the search bar in the bottom left corner of the screen. The search bar opens with the Alt + T shortcut on Windows and Opt + T on macOS; typing the name of the feature being searched for is then sufficient.

The created profile is used in the Default Lockout Policies list in the vService AGS settings and in the Lockout Policies list of the Authentication Providers profiles. The profile is also defined without leaving the page with the add icon next to the field in the vService AGS settings.

Account Lockout Policies Listing Screen

The list of all Account Lockout Policies profiles that are added on the TR7 device is reached by following the AGS → Protection Policies → Account Lockout Policies path. Profile adding, editing and deleting operations are performed on this screen. The built-in profiles are not listed.

Account Lockout Policies Profiles Listing Form

The table opens with the following columns by default:

Column	Description
Lockout Policy Name	The name of the profile.
Policy Scope	The scope in which the failed attempts are counted.
Lockout Threshold	The number of failed attempts at which the lock comes into play.
Attempt Tracking Window	The window in which the attempts are counted (e.g. 24 hour(s)).
Lockout Duration	The duration of the first lock (e.g. 30 minute(s)).
Enable Captcha Protection	The state of the CAPTCHA level: Enabled or Disabled.

There is no column that is hidden by default. The table is not sorted when it opens; when a column header is clicked, first a descending and then an ascending sort is applied, and on the third click the sort is removed.

The items in the toolbar are arranged from left to right in the following order; the last two items (Page Information and Page Size) are located in the information strip below the table.

Columns

Which columns are shown in the table is selected; all six of the columns come on. In the same panel the columns are reordered by dragging and the alignment is selected per column; the row height is fitted to the page with the Fit rows to the page button and the column layout is returned to the default with the Reset button. When the width badge next to a manually widened column is clicked, the column returns to the automatic width.

Filter

The Filter button is used to filter the profiles shown in the list according to certain criteria. There are three cards in the filter strip; the number next to the card name shows how many different values are found for that card in the profiles in the list:

Card	What it filters
Policy Scope	By the counting scope.
Enable Captcha Protection	By the state of the CAPTCHA level (Enabled / Disabled).
Used in	The vServices and the provider/MFA profiles that use the profiles and the Unused Entries value, which lists the profiles that are not used anywhere.

Export

The table is exported as Excel, CSV or PDF by clicking the Export button. In the window that opens, the Filename, Format and Data Source, together with the Columns to be exported, are determined; the remaining fields are displayed according to the format: CSV Separator for CSV, Excel Sheet Name for Excel, and Page Orientation and Page Size for PDF.

Add

By clicking the Add button, the form for creating a new profile opens in the Add tab.

Edit

By clicking the Edit button, the edit form of the selected profile opens in the Edit tab. The button becomes enabled only when a single profile is selected.

The edit form is the same as the add form; all the fields including the name are changed and the button at the bottom of the form carries the name Edit. The change is saved without asking for confirmation and the configuration of the vServices that use the profile is applied again.

Delete

When one or more profiles are selected and the Delete button is clicked, the related profiles are deleted. Before deleting, the "Are you sure?" confirmation is asked for.

WARNING

A profile that is in use can also be deleted and the confirmation window does not show the usage locations.

The reference in the vService defaults that list the profile and in the Lockout Policies lists of the provider profiles is not cleared automatically; a policy that cannot be found at runtime is skipped, the reference stays in the list and it must be removed manually while the related record is being saved again. The missing policy drops silently from the summary sentence on the vService AGS settings canvas; if all the policies in the default list are deleted, No default lockout policy — authentication providers may use their own is written on the canvas. On the Lockout tab the deleted policy appears with its raw id. The delete operation is written to the user operation record.

Search

Used to search all information in the table.

RegExp Search

Used to search all the information in the table with a regular expression (RegExp). While the usage filter is active, this button is hidden.

Column Based Search

Used to perform a column-based search on the information in the table.

Usage Filter

Used to filter where the profiles are used. While the filter is active, a selector takes the place of the search box; when the icon is clicked again, the search box returns.

Page Information

Contains information about the total number of defined profiles and the number of profiles displayed in the list: Showing N-M of T records and the number of selected profiles (N selected, or Nothing selected when there is no selection).

Page Size

The maximum number of profiles to be displayed on the page is selected. On this screen the default is 100; the options are 5, 10, 20, 50, 100, 200, 500 and All.

Right-Click Menu

When a row is right-clicked, a menu with the profile's name in its title opens. Both operations in the menu apply only to the right-clicked profile; a selection made in the list does not affect the menu.

Operation	What it does
Edit	Opens the editing form of the profile in the Edit tab; it is the same as the form opened by the Edit button in the toolbar.
Delete	Deletes the right-clicked profile; the same confirmation question as the deletion in the toolbar is displayed.

Preview of the Selected Profile

When a row in the list is clicked, the preview of the profile opens on the right of the screen; when the selected row is clicked again, the panel closes. The header contains the lock icon, the name of the profile and the Lockout Policy subtitle, and the single operation is at the top right.

Preview of the Selected Profile

Operation	What it does
Edit	Opens the editing form of the profile in the Edit tab.

There are three tabs in the panel; Used in is displayed only if the profile is used in at least one place:

Details

Lists the settings of the profile row by row (the table below).

Log

Lists the user operations on the profile (adding, editing, deleting) as a timeline.

Used in

Lists the vServices and the provider/MFA profiles that use the profile. The badge next to the tab name shows the usage count.

The rows in the Details tab are as follows, in order:

Row	Description	Visibility condition
Lockout Policy Name	The name of the profile.	Always
Policy Condition	The condition tree (read-only).	If a condition is defined
Policy Scope	The counting scope.	Always
Policy Components	The component variables, row by row (e.g. %BROWSER).	Custom Combination
Warning Threshold	After N failed attempts.	Always
Enable Captcha Protection	Enabled or Disabled.	Always
Captcha Threshold	After N failed attempts.	If the CAPTCHA is on
Captcha Provider	A link to the provider profile.	If the CAPTCHA is on
Lockout Threshold	After N failed attempts.	Always
Lockout Duration	The duration and the unit (e.g. 30 minute(s)).	Always
Escalate Repeated Lockouts	Enabled or Disabled.	Always
Maximum Lockout Duration	The duration and the unit (e.g. 24 hour(s)).	If Escalate Repeated Lockouts is on
Attempt Tracking Window	The duration and the unit (e.g. 24 hour(s)).	Always

Profile Add Form

A new Account Lockout Policies profile is added on the TR7 device by following the AGS → Protection Policies → Account Lockout Policies → Add steps.

Account Lockout Policies Profile Add Form

INFO

Lockout Policy Name Required

The name of the profile; it identifies the profile in the selections in the vService and provider settings, on the Lockout tab and in the logs. The name must be unique on the device; a second profile with the same name is not saved and the Name is used warning is displayed. When it is left empty, the Required field warning is displayed.

INFO

Policy Scope Required Default: Username only

The key for which the failed attempts are counted is selected:

Option	Meaning
Username Only	It is counted for the username written in the login form; the attempts coming to the same account from different addresses are counted together.
Username + IP	It is counted for the combination of the username and the source IP address; locking the account from other addresses becomes harder.
IP Address Only	It is counted for the source IP address; the attempts made from a single address to many accounts are caught.
Custom Combination	It is counted for the combination of the Smart Variables values selected in the Policy Components field.

INFO

Policy Condition Default: Disabled

When the switch is moved to the Enabled position, the HTTP request condition builder opens; the policy is applied only on the requests that match the condition. The conditions are selected from the HTTP conditions defined on the Conditions screen; the selector lists only the HTTP request conditions. A new condition is also defined without leaving the page with the add icon in the builder. At most four condition groups are combined with AND or OR. While the switch is off, the policy is always valid.

INFO

Policy Components Required (Custom combination)

Displayed only while Custom Combination is selected in the Policy Scope field. An HTTP request Smart Variables variable is selected on each row (e.g. %BROWSER); the rows do not repeat and at least one row is present. The counting key consists of the combination of these values.

INFO

Warning Threshold Default: 3

After this number of failed attempts a warning message is shown to the user; an integer between 1 and 100 is entered. When the field is left empty, the record is not rejected; the server applies the value 3.

INFO

Enable Captcha Protection Default: Enabled

While it is on, the level at which a CAPTCHA verification is added to the login form before the lock is enabled and the Captcha Threshold and Captcha Provider fields are displayed. While it is off, the lock level is passed to directly after the warning.

Captcha Threshold Default: 4

After this number of failed attempts a CAPTCHA is added to the login form; an integer between 1 and 100 is entered. The value cannot be lower than the Warning Threshold value and has to be lower than the Lockout Threshold value; otherwise one of the following warnings is displayed during saving. The messages carry the entered values in parentheses (4 and 5 in the examples below):

• Captcha threshold (4) cannot be below the warning threshold (5) - the user would meet a captcha before ever seeing the warning that explains why.
• Captcha threshold (5) must be below the lockout threshold (5), otherwise the lockout arrives first and the captcha step is never reached.

Captcha Provider Required Default: Standard TR7 CAPTCHA

The verification provider to be used at the CAPTCHA level; the built-in and defined CAPTCHA Providers profiles are listed. The summary of the profile is opened with the information icon next to the selected provider; with the add icon a new provider profile is defined without leaving the page and comes selected in the field.

INFO

Lockout Threshold Required Default: 5

After this number of failed attempts the scope key is locked; an integer between 2 and 100 is entered. The value has to be greater than the Warning Threshold value; otherwise the Lockout threshold (3) must be above the warning threshold (3), or the lock arrives without the warning ever being shown. warning, which carries the entered values in parentheses, is displayed.

INFO

Lockout Duration Required Default: 30 minutes

The duration of the first lockout; a value and a unit (seconds, minutes or hours) are entered, and a duration between 30 seconds and 24 hours is accepted. On repeated lockouts the duration is multiplied (see Operating Mechanism).

INFO

Escalate Repeated Lockouts Default: Enabled

Whether the lock duration is increased when the same source is locked out again and again is selected. In the Enabled position the duration doubles on every repeated lockout and grows up to the Maximum Lockout Duration value; in the Disabled position every lockout lasts as long as Lockout Duration.

INFO

Maximum Lockout Duration Default: 24 hours

It is displayed in the form while Escalate Repeated Lockouts is on. The ceiling the doubling lock duration can reach; a value and a unit (minutes, hours or days) are entered, and a duration between 1 minute and 365 days is accepted. The ceiling cannot be shorter than the Lockout Duration value; if a shorter value is entered, the save is rejected with the "Maximum lockout duration (<ceiling>) cannot be shorter than the lockout duration (<duration>)." error.

INFO

Attempt Tracking Window Required Default: 24 hours

The time window in which the failed attempts are counted; a value and a unit (minutes, hours or days) are entered, and a duration between 5 minutes and 365 days is accepted. The attempts older than the window are not counted.

INFO

Add

The profile is added by clicking the Add button; the tab closes and the profile is displayed in the list.

Operating Mechanism

INFO

• Distribution. The policies are transferred to the AGS access engine; the counting and the locking are performed on the engine side.
• The effective policy set. In the authentication provider step, according to the Lockout Behavior setting of the provider, the vService defaults are used (Use Gateway Defaults), are replaced with the list of the provider (Replace Defaults), are added to (Add to Defaults) or the lockout is turned off (No Lockout). In the MFA step this behavior option is not evaluated; only the own policy list of the MFA profile is applied and the vService defaults do not flow into this step.
• The multiplication of the lock duration. On repeated lockouts the duration doubles each time and reaches the ceiling in the policy record (the default 24 hours; 1 hour for the built-in Default IP Lockout); if there is no new lockout during one tracking window, the multiplication level is reset. The doubling is switched off with the Escalate Repeated Lockouts switch in the form and the ceiling is set in the Maximum Lockout Duration field; the summary sentence appears on the vService settings canvas in the form Repeat lockouts double, up to <ceiling>.
• The CAPTCHA chain. The providers of the policies with the CAPTCHA on are written into the vService; the verification requests of the external providers go out from the route table in the provider profile.
• The condition and the components. The Policy Condition and the Custom Combination components are evaluated per request in the vService configuration and their results are carried to the access engine.
• The statistics. The created and blocked lock counters on a scope basis and the number of active locks are monitored on the Live Stats tab of the vService. On these screens the scope names are displayed in the Username, IP Address and Composite form; they are not exactly the same as the option names in the form.
• Cluster. The profiles are synchronized between the devices with the LB configuration.
• Logs. Adding, editing and deleting are monitored on the User Logs screen as the lockout policy object.

Scope and Limits

INFO

• License. The screen depends on the AGS license; for the details the Products & Licensing page must be consulted.
• Permission. The AGS screens depend on the Load Balancer permission area; for a user who does not have the permission the You don't have access to this page card is displayed instead of the page.
• The name is unique. A second profile carrying the same name is not saved. The check is performed only among the profiles listed on this screen; the names of the built-in profiles do not enter the check.
• The built-in profiles are not listed, they are not edited or deleted from this screen.
• The threshold order is checked during saving.
• The vService defaults do not reach the MFA step. The Default Lockout Policies list is evaluated only in the authentication provider steps; on a vService that has no provider step in its flow this list produces no result.
• There is no device scope. The scope options are the username, the IP and a custom combination.
• Deleting does not perform a reference check; a profile in use is deleted as well.
• The record limit of the lock duration is wider than the form. While the form accepts at most 24 hours with the second, minute and hour units, the record accepts the day unit and durations up to 365 days as well; a policy saved with a longer duration cannot be saved again from the form.

Usage Locations

Usage location	Field	Purpose
A vService with AGS enabled → AGS Management	Default Lockout Policies (multiple selection)	The default policies valid in the authentication provider steps; Default Username Lockout and Default IP Lockout on a new vService
Authentication Providers	Lockout Behavior and Lockout Policies	Using, replacing, adding to or turning off the defaults on a provider basis
Multi-Factor Authentication (MFA)	There is no lockout field in the form	The policy set specific to the MFA step; the built-in MFA profiles come with Default MFA Lockout
A vService with AGS enabled → the Lockout tab	The lock and attempt list	The monitoring of the active locks and the counters on a policy basis; Clear Lockouts and Reset Failures