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

Modifier and Type	Method and Description
Principal	authenticate(GSSContext gssContext, boolean storeCreds) Try to authenticate using a GSSContext
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()
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, setContainer, stopInternal

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

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

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, init, removeLifecycleListener, setState, setState, 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

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

Overrides:

getName in class CombinedRealm

Returns:

a short name for this Realm implementation, for use in log messages.

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