.. include:: /includes.rst.txt

.. comments - headings

   # with overline, for parts
   * with overline, for chapters
   = for sections
   - for subsections
   ^ for subsubsections
   " for paragraphs
   * for H5
   + for H6

.. _lockout:

Lockout Feature
===============

EDG has the ability to temporarily lock out a user account after too many 
failed login attempts.  It behaves similarly to the LockOutRealm feature of 
Tomcat.  It is enabled by default, and is configurable with settings in the 
EDG :ref:`setup file <setup_lockout>`.

.. note::
  This feature is not applicable for :ref:`saml_authentication` or 
  :ref:`oidc_authentication`.  For those login methods, the corresponding 
  IDP or Authorization Server handles incorrect login credentials.

After ``lockoutFailureCount`` failed login attempts (default 5) in a row, an 
account will be locked for ``lockoutDuration`` seconds (default 300, or 5
minutes).  Accounts with login failures will be kept in a cache until the 
user successfully logs in, the ``lockoutDuration`` expires, or until the
cache reaches ``lockoutCacheSize``.

If an account is locked, the corresponding user will not be able to login.  
They will be forwarded to an error page, indicating that the account is 
locked, and a warning will be logged in :ref:`edg_log`.

.. note::
  If you need to disable this feature for testing purposes, you can set 
  ``lockoutFailureCount`` to a number less than 1.  Remember to re-enable 
  it before deploying to production.

The cache of accounts with login failures is limited in size by 
the ``lockoutCacheSize`` setting (default 1000).  When the cache size 
limit has been reached, the oldest entry in the cache will be removed.  
This is to prevent a Denial of Service (DoS) attack, where requests are
made with deliberately invalid users, causing the list of locked out users 
to grow until it would otherwise begin to exhaust resources.  To help 
detect such an attack, EDG will log a warning in :ref:`edg_log` if the 
cache size limit has been reached, and entries are being removed prematurely.  
In this case, "premature" means that either the ``lockoutDuration`` has not 
yet expired, or that the account has been in the cache for less than
``lockoutCacheRemovalWarningDuration`` seconds (default 3600, or 1 hour).

.. note::
   If you are using :ref:`ldap_authentication`, your Active Directory server
   may have its own Account Lockout Policy enabled.  If so, TopQuadrant 
   recommends disabling the Lockout Feature, as it may lead to unexpected 
   results if both are enabled.