LockOutRealm (Apache Tomcat 9.0.37 API Documentation)

org.apache.catalina.realm

## 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.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `protected static class` | `LockOutRealm.LockRecord`

    - ### Nested classes/interfaces inherited from class org.apache.catalina.realm.RealmBase

      `RealmBase.AllRolesMode`

    - ### Nested classes/interfaces inherited from interface org.apache.catalina.Lifecycle

      `Lifecycle.SingleUse`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `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.
    `protected int` | `cacheSize` Number of users that have failed authentication to keep in cache.
    `protected Map<String,LockOutRealm.LockRecord>` | `failedUsers` Users whose last authentication attempt failed.
    `protected int` | `failureCount` The number of times in a row a user has to fail authentication to be locked out.
    `protected int` | `lockOutTime` The time (in seconds) a user is locked out for after too many authentication failures.

    - ### Fields inherited from class org.apache.catalina.realm.CombinedRealm

      `realms`

    - ### Fields inherited from class org.apache.catalina.realm.RealmBase

      `allRolesMode, container, containerLog, realmPath, sm, stripRealmForGss, support, validate, x509UsernameRetriever, x509UsernameRetrieverClassName`

    - ### Fields inherited from class org.apache.catalina.util.LifecycleMBeanBase

      `mserver`

    - ### Fields inherited from interface org.apache.catalina.Lifecycle

      `AFTER_DESTROY_EVENT, AFTER_INIT_EVENT, AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_DESTROY_EVENT, BEFORE_INIT_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, CONFIGURE_START_EVENT, CONFIGURE_STOP_EVENT, PERIODIC_EVENT, START_EVENT, STOP_EVENT`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `LockOutRealm()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `Principal` | `authenticate(GSSContext gssContext, boolean storeCreds)` Try to authenticate using a `GSSContext`
    `Principal` | `authenticate(GSSName gssName, GSSCredential gssCredential)` Try to authenticate using a `GSSName` Note that this default method will be turned into an abstract one in Tomcat 10.
    `Principal` | `authenticate(String username, String credentials)` Return the Principal associated with the specified username and credentials, if there is one; otherwise return `null`.
    `Principal` | `authenticate(String username, String clientDigest, String nonce, String nc, String cnonce, String qop, String realmName, String md5a2)` Return the Principal associated with the specified username, which matches the digest calculated using the given parameters using the method described in RFC 2069; otherwise return `null`.
    `Principal` | `authenticate(X509Certificate[] certs)` Return the Principal associated with the specified chain of X509 client certificates.
    `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.
    `int` | `getCacheSize()` Get the maximum number of users for which authentication failure will be kept in the cache.
    `int` | `getFailureCount()` Get the number of failed authentication attempts required to lock the user account.
    `int` | `getLockOutTime()` Get the period for which an account will be locked.
    `boolean` | `isLocked(String username)`
    `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.
    `void` | `setCacheSize(int cacheSize)` Set the maximum number of users for which authentication failure will be kept in the cache.
    `void` | `setFailureCount(int failureCount)` Set the number of failed authentication attempts required to lock the user account.
    `void` | `setLockOutTime(int lockOutTime)` Set the period for which an account will be locked.
    `protected void` | `startInternal()` Prepare for the beginning of active use of the public methods of this component and implement the requirements of `LifecycleBase.startInternal()`.
    `void` | `unlock(String username)` Unlock the specified username.

    - ### Methods inherited from class org.apache.catalina.realm.CombinedRealm

      `addRealm, authenticate, backgroundProcess, destroyInternal, getNestedRealms, getPassword, getPrincipal, getRealms, hasRole, isAvailable, setContainer, setCredentialHandler, stopInternal`

    - ### Methods inherited from class org.apache.catalina.realm.RealmBase

      `addPropertyChangeListener, findSecurityConstraints, getAllRolesMode, getContainer, getCredentialHandler, getDigest, getDomainInternal, getObjectNameKeyProperties, getPrincipal, getPrincipal, getPrincipal, getRealmPath, getRealmSuffix, getRoles, getServer, getTransportGuaranteeRedirectStatus, getValidate, getX509UsernameRetrieverClassName, hasMessageDigest, hasResourcePermission, hasRoleInternal, hasUserDataPermission, initInternal, isStripRealmForGss, main, removePropertyChangeListener, setAllRolesMode, setRealmPath, setStripRealmForGss, setTransportGuaranteeRedirectStatus, setValidate, setX509UsernameRetrieverClassName, toString`

    - ### Methods inherited from class org.apache.catalina.util.LifecycleMBeanBase

      `getDomain, getObjectName, postDeregister, postRegister, preDeregister, preRegister, register, setDomain, unregister, unregister`

    - ### Methods inherited from class org.apache.catalina.util.LifecycleBase

      `addLifecycleListener, destroy, findLifecycleListeners, fireLifecycleEvent, getState, getStateName, getThrowOnFailure, init, removeLifecycleListener, setState, setState, setThrowOnFailure, start, stop`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### 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 Detail

    - #### LockOutRealm

          public LockOutRealm()

  - ### Method Detail

    - #### startInternal

          protected void startInternal()
                                throws LifecycleException

      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 md5a2)

      Return the Principal associated with the specified username, which matches the digest calculated using the given parameters using the method described in RFC 2069; otherwise return `null`.
      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
        `realmName` - Realm name
        `md5a2` - Second MD5 digest used to calculate the digest : MD5(Method + ":" + uri)
        `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`).
      Returns:
        the associated principal, or `null` if there is none.

    - #### authenticate

          public Principal authenticate(String username,
                                        String credentials)

      Return the Principal associated with the specified username and credentials, if there is one; otherwise return `null`.
      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)

      Return the Principal associated with the specified chain of X509 client certificates. If there is none, return `null`.
      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)

      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)

      Try to authenticate using a `GSSName` Note that this default method will be turned into an abstract one in Tomcat 10.
      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

Copyright © 2000-2020 Apache Software Foundation. All Rights Reserved.