Class LockOutRealm

java.lang.Object
org.apache.catalina.util.LifecycleBase
org.apache.catalina.util.LifecycleMBeanBase
org.apache.catalina.realm.RealmBase
org.apache.catalina.realm.CombinedRealm
org.apache.catalina.realm.LockOutRealm
All Implemented Interfaces:
MBeanRegistration, Contained, JmxEnabled, Lifecycle, Realm
public class LockOutRealm extends CombinedRealm
This class extends the CombinedRealm (hence it can wrap other Realms) to provide a user lock out mechanism if there are too many failed authentication attempts in a given period of time. To ensure correct operation, there is a reasonable degree of synchronisation in this Realm. This Realm does not require modification to the underlying Realms or the associated user storage mechanisms. It achieves this by recording all failed logins, including those for users that do not exist. To prevent a DOS by deliberating making requests with invalid users (and hence causing this cache to grow) the size of the list of users that have failed authentication is limited.

  • Field Details

    • failureCount

      protected int failureCount
      The number of times in a row a user has to fail authentication to be locked out. Defaults to 5.

    • lockOutTime

      protected int lockOutTime
      The time (in seconds) a user is locked out for after too many authentication failures. Defaults to 300 (5 minutes).

    • cacheSize

      protected int cacheSize
      Number of users that have failed authentication to keep in cache. Over time the cache will grow to this size and may not shrink. Defaults to 1000.

    • cacheRemovalWarningTime

      protected int cacheRemovalWarningTime
      If a failed user is removed from the cache because the cache is too big before it has been in the cache for at least this period of time (in seconds) a warning message will be logged. Defaults to 3600 (1 hour).

    • failedUsers

      protected Map<String,LockOutRealm.LockRecord> failedUsers
      Users whose last authentication attempt failed. Entries will be ordered in access order from least recent to most recent.

  • Constructor Details

    • LockOutRealm

      public LockOutRealm()

  • Method Details

    • startInternal

      protected void startInternal() throws LifecycleException
      Description copied from class: RealmBase
      Prepare for the beginning of active use of the public methods of this component and implement the requirements of LifecycleBase.startInternal().
      Overrides:
      startInternal in class CombinedRealm
      Throws:
      LifecycleException - if this component detects a fatal error that prevents this component from being used

    • authenticate

      public Principal authenticate(String username, String clientDigest, String nonce, String nc, String cnonce, String qop, String realmName, String digestA2, String algorithm)
      Description copied from interface: Realm
      Try to authenticate with the specified username, which matches the digest calculated using the given parameters using the method described in RFC 7616.

      The default implementation calls Realm.authenticate(String, String, String, String, String, String, String, String) for backwards compatibility which effectively forces the use of MD5 regardless of the algorithm specified in the call to this method.

      Implementations are expected to override the default implementation and take account of the algorithm parameter.

      Specified by:
      authenticate in interface Realm
      Overrides:
      authenticate in class CombinedRealm
      Parameters:
      username - Username of the Principal to look up
      clientDigest - Digest which has been submitted by the client
      nonce - Unique (or supposedly unique) token which has been used for this request
      nc - the nonce counter
      cnonce - the client chosen nonce
      qop - the "quality of protection" (nc and cnonce will only be used, if qop is not null).
      realmName - Realm name
      digestA2 - Second digest calculated as digest(Method + ":" + uri)
      algorithm - The message digest algorithm to use
      Returns:
      the associated principal, or null if there is none.

    • authenticate

      public Principal authenticate(String username, String credentials)
      Description copied from interface: Realm
      Try to authenticate using the specified username and credentials.
      Specified by:
      authenticate in interface Realm
      Overrides:
      authenticate in class CombinedRealm
      Parameters:
      username - Username of the Principal to look up
      credentials - Password or other credentials to use in authenticating this username
      Returns:
      the associated principal, or null if there is none

    • authenticate

      public Principal authenticate(X509Certificate[] certs)
      Description copied from interface: Realm
      Try to authenticate using a chain of X509Certificates.
      Specified by:
      authenticate in interface Realm
      Overrides:
      authenticate in class CombinedRealm
      Parameters:
      certs - Array of client certificates, with the first one in the array being the certificate of the client itself.
      Returns:
      the associated principal, or null if there is none

    • authenticate

      public Principal authenticate(GSSContext gssContext, boolean storeCreds)
      Description copied from interface: Realm
      Try to authenticate using a GSSContext.
      Specified by:
      authenticate in interface Realm
      Overrides:
      authenticate in class CombinedRealm
      Parameters:
      gssContext - The gssContext processed by the Authenticator.
      storeCreds - Should the realm attempt to store the delegated credentials in the returned Principal?
      Returns:
      the associated principal, or null if there is none

    • authenticate

      public Principal authenticate(GSSName gssName, GSSCredential gssCredential)
      Description copied from interface: Realm
      Try to authenticate using a GSSName.
      Specified by:
      authenticate in interface Realm
      Overrides:
      authenticate in class CombinedRealm
      Parameters:
      gssName - The GSSName of the principal to look up
      gssCredential - The GSSCredential of the principal, may be null
      Returns:
      the associated principal, or null if there is none

    • unlock

      public void unlock(String username)
      Unlock the specified username. This will remove all records of authentication failures for this user.
      Parameters:
      username - The user to unlock

    • isLocked

      public boolean isLocked(String username)

    • getFailureCount

      public int getFailureCount()
      Get the number of failed authentication attempts required to lock the user account.
      Returns:
      the failureCount

    • setFailureCount

      public void setFailureCount(int failureCount)
      Set the number of failed authentication attempts required to lock the user account.
      Parameters:
      failureCount - the failureCount to set

    • getLockOutTime

      public int getLockOutTime()
      Get the period for which an account will be locked.
      Returns:
      the lockOutTime

    • setLockOutTime

      public void setLockOutTime(int lockOutTime)
      Set the period for which an account will be locked.
      Parameters:
      lockOutTime - the lockOutTime to set

    • getCacheSize

      public int getCacheSize()
      Get the maximum number of users for which authentication failure will be kept in the cache.
      Returns:
      the cacheSize

    • setCacheSize

      public void setCacheSize(int cacheSize)
      Set the maximum number of users for which authentication failure will be kept in the cache.
      Parameters:
      cacheSize - the cacheSize to set

    • getCacheRemovalWarningTime

      public int getCacheRemovalWarningTime()
      Get the minimum period a failed authentication must remain in the cache to avoid generating a warning if it is removed from the cache to make space for a new entry.
      Returns:
      the cacheRemovalWarningTime

    • setCacheRemovalWarningTime

      public void setCacheRemovalWarningTime(int cacheRemovalWarningTime)
      Set the minimum period a failed authentication must remain in the cache to avoid generating a warning if it is removed from the cache to make space for a new entry.
      Parameters:
      cacheRemovalWarningTime - the cacheRemovalWarningTime to set