Smarter by Design.Simpler for Business
TR7Enterprise Application Delivery & Security Platform
What is an Account Lockout Policy; how does account lockout work?
Short answer
An Account Lockout Policy is the profile that counts the failed login attempts in the AGS access flow in the selected scope (Policy Scope: Username Only, Username + IP, IP Address Only, Custom Combination) and applies three levels: a warning when the number of attempts reaches the Warning Threshold value, a CAPTCHA at the Captcha Threshold value and, at the Lockout Threshold value, a lock for the Lockout Duration. Attempts are counted within the Attempt Tracking Window; while Escalate Repeated Lockouts is on, the duration doubles on repeated locks. On the vService, the policies in the Default Lockout Policies list (when AGS is first enabled, the built-in Default Username Lockout and Default IP Lockout) are applied to the provider steps; each provider can change this with Lockout Behavior.
How Does It Work?
- Each failed authentication is counted for the policy's scope key (the username, the IP address, both together or the selected components). If a Policy Condition is defined, the policy is applied only on matching requests.
- As the counter reaches the thresholds, the warning, CAPTCHA (if Enable Captcha Protection is on, with the selected Captcha Provider) and lock levels come into effect.
- The lock lasts as long as Lockout Duration; on repeated locks the duration doubles each time and stops at the Maximum Lockout Duration value. If there is no new lock during one tracking window, the doubling level is reset.
- Multiple policies work together in the same step; for example, a username-scoped policy catches attempts against a single account, and an IP-scoped policy catches attempts against many accounts from a single source.
Account Lockout Policies in TR7
The policies are defined on the AGS → Protection Policies → Account Lockout Policies screen. In the form, the defaults are Warning Threshold 3, Captcha Threshold 4, Lockout Threshold 5, Lockout Duration 30 minutes (30 seconds–24 hours), Maximum Lockout Duration 24 hours and Attempt Tracking Window 24 hours; on save, it is verified that the thresholds follow the warning → CAPTCHA → lock order.
Which policies count in the provider step is determined by the provider's Lockout Behavior value: Use Gateway Defaults (default; the vService's Default Lockout Policies list), Replace Defaults (only the policies selected in the provider), Add to Defaults (both together) or No Lockout.
Built-in policies (built-in profiles):
| Policy | Policy Scope | Warning / CAPTCHA / lock | First / longest lock | Window |
|---|---|---|---|---|
| Default Username Lockout | Username Only | 3 / 3 / 5 | 5 minutes / 24 hours | 24 hours |
| Default IP Lockout | IP Address Only | 20 / 25 / 50 | 15 minutes / 1 hour | 1 hour |
| Default MFA Lockout | Username Only | 3 / - / 5 | 5 minutes / 24 hours | 24 hours |
| Default Username + IP Lockout | Username + IP | 3 / 3 / 5 | 5 minutes / 24 hours | 24 hours |
Active locks and attempt counters are monitored on the vService's Lockout tab; a user locked by mistake is released with Clear Lockouts, and the counter is reset with Reset Failures.
Common Misconceptions
- "Clear Lockouts also resets the counter." Clear Lockouts removes only the lock; the attempts in the window continue to be counted. To reset the counter, Reset Failures is applied separately.
- "TR7 lockout is also needed for external providers." In OAuth2, OpenID Connect and SAML 2.0, since the password is entered on the provider's page, the attempt limit is applied at the provider; for these providers, No Lockout can be selected in the Lockout Behavior field.
- "Locking by username alone is enough." The username scope does not catch attempts made against many accounts from a single source; for this reason, an IP-scoped policy is also bound together with it by default.
How it is done in the documentation
