LockOutRealm (Apache Tomcat 7.0.109 API Documentation)

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, GSSRealm, 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

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

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.
`protected static String`	`name` Descriptive information about this Realm implementation.

Fields inherited from class org.apache.catalina.realm.CombinedRealm
realms

Fields inherited from class org.apache.catalina.realm.RealmBase
allRolesMode, container, containerLog, digest, digestEncoding, info, md, md5Encoder, md5Helper, 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()

Constructors
Constructor and Description
`LockOutRealm()`

Method Summary

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`
`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.
`protected String`	`getName()` Return a short name for this Realm implementation, for use in log messages.
`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, getPassword, getPrincipal, getRealms, hasRole, setContainer, stopInternal

Methods inherited from class org.apache.catalina.util.LifecycleMBeanBase
getDomain, getObjectName, postDeregister, postRegister, preDeregister, preRegister, register, setDomain, 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
  - name
```
protected static final String name
```
    Descriptive information about this Realm implementation.
    
    See Also:
    Constant Field Values
  - 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
    
    Specified by:
    
    authenticate in interface GSSRealm
    
    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
  - 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
  - getName
```
protected String getName()
```
    Description copied from class: RealmBase
    
    Return a short name for this Realm implementation, for use in log messages.
    
    Overrides:
    
    getName in class CombinedRealm
  - 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

Class LockOutRealm

Nested Class Summary

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

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

Field Summary

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

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

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

Fields inherited from interface org.apache.catalina.Lifecycle

Constructor Summary

Method Summary

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

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

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

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

Methods inherited from class java.lang.Object

Field Detail

name

failureCount

lockOutTime

cacheSize

cacheRemovalWarningTime

failedUsers

Constructor Detail

LockOutRealm

Method Detail

startInternal

authenticate

authenticate

authenticate

authenticate

authenticate

unlock

getFailureCount

setFailureCount

getLockOutTime

getName

setLockOutTime

getCacheSize

setCacheSize

getCacheRemovalWarningTime

setCacheRemovalWarningTime