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
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/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
Modifier and TypeFieldDescriptionprotected int
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
Number of users that have failed authentication to keep in cache.protected Map
<String, LockOutRealm.LockRecord> Users whose last authentication attempt failed.protected int
The number of times in a row a user has to fail authentication to be locked out.protected int
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, USER_ATTRIBUTES_DELIMITER, USER_ATTRIBUTES_WILDCARD, userAttributes, userAttributesList, validate, x509UsernameRetriever, x509UsernameRetrieverClassName
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
-
Method Summary
Modifier and TypeMethodDescriptionauthenticate
(String username, String credentials) Try to authenticate using the specified username and credentials.authenticate
(String username, String clientDigest, String nonce, String nc, String cnonce, String qop, String realmName, String digestA2, String algorithm) Try to authenticate with the specified username, which matches the digest calculated using the given parameters using the method described in RFC 7616.authenticate
(X509Certificate[] certs) Try to authenticate using a chain ofX509Certificate
s.authenticate
(GSSContext gssContext, boolean storeCreds) Try to authenticate using aGSSContext
.authenticate
(GSSName gssName, GSSCredential gssCredential) Try to authenticate using aGSSName
.int
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
Get the maximum number of users for which authentication failure will be kept in the cache.int
Get the number of failed authentication attempts required to lock the user account.int
Get the period for which an account will be locked.boolean
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
Prepare for the beginning of active use of the public methods of this component and implement the requirements ofLifecycleBase.startInternal()
.void
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, authenticate, findSecurityConstraints, getAllRolesMode, getContainer, getCredentialHandler, getDigest, getDigest, getDomainInternal, getObjectNameKeyProperties, getPrincipal, getPrincipal, getPrincipal, getRealmPath, getRealmSuffix, getServer, getTransportGuaranteeRedirectStatus, getUserAttributes, getValidate, getX509UsernameRetrieverClassName, hasMessageDigest, hasResourcePermission, hasRoleInternal, hasUserDataPermission, initInternal, isStripRealmForGss, main, parseUserAttributes, removePropertyChangeListener, setAllRolesMode, setRealmPath, setStripRealmForGss, setTransportGuaranteeRedirectStatus, setUserAttributes, 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
-
Field Details
-
failureCount
protected int failureCountThe number of times in a row a user has to fail authentication to be locked out. Defaults to 5. -
lockOutTime
protected int lockOutTimeThe time (in seconds) a user is locked out for after too many authentication failures. Defaults to 300 (5 minutes). -
cacheSize
protected int cacheSizeNumber 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 cacheRemovalWarningTimeIf 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
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
Description copied from class:RealmBase
Prepare for the beginning of active use of the public methods of this component and implement the requirements ofLifecycleBase.startInternal()
.- Overrides:
startInternal
in classCombinedRealm
- 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 interfaceRealm
- Overrides:
authenticate
in classCombinedRealm
- Parameters:
username
- Username of the Principal to look upclientDigest
- Digest which has been submitted by the clientnonce
- Unique (or supposedly unique) token which has been used for this requestnc
- the nonce countercnonce
- the client chosen nonceqop
- the "quality of protection" (nc
andcnonce
will only be used, ifqop
is notnull
).realmName
- Realm namedigestA2
- 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
Description copied from interface:Realm
Try to authenticate using the specified username and credentials.- Specified by:
authenticate
in interfaceRealm
- Overrides:
authenticate
in classCombinedRealm
- Parameters:
username
- Username of the Principal to look upcredentials
- Password or other credentials to use in authenticating this username- Returns:
- the associated principal, or
null
if there is none
-
authenticate
Description copied from interface:Realm
Try to authenticate using a chain ofX509Certificate
s.- Specified by:
authenticate
in interfaceRealm
- Overrides:
authenticate
in classCombinedRealm
- 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
Description copied from interface:Realm
Try to authenticate using aGSSContext
.- Specified by:
authenticate
in interfaceRealm
- Overrides:
authenticate
in classCombinedRealm
- Parameters:
gssContext
- The gssContext processed by theAuthenticator
.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
Description copied from interface:Realm
Try to authenticate using aGSSName
.- Specified by:
authenticate
in interfaceRealm
- Overrides:
authenticate
in classCombinedRealm
- Parameters:
gssName
- TheGSSName
of the principal to look upgssCredential
- TheGSSCredential
of the principal, may benull
- Returns:
- the associated principal, or
null
if there is none
-
unlock
Unlock the specified username. This will remove all records of authentication failures for this user.- Parameters:
username
- The user to unlock
-
isLocked
-
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
-