Package 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:
- javax.management.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 SummaryNested Classes Modifier and Type Class Description protected static classLockOutRealm.LockRecord- 
Nested classes/interfaces inherited from class org.apache.catalina.realm.RealmBaseRealmBase.AllRolesMode
 - 
Nested classes/interfaces inherited from interface org.apache.catalina.LifecycleLifecycle.SingleUse
 
- 
 - 
Field SummaryFields Modifier and Type Field Description protected intcacheRemovalWarningTimeIf 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 intcacheSizeNumber of users that have failed authentication to keep in cache.protected java.util.Map<java.lang.String,LockOutRealm.LockRecord>failedUsersUsers whose last authentication attempt failed.protected intfailureCountThe number of times in a row a user has to fail authentication to be locked out.protected intlockOutTimeThe time (in seconds) a user is locked out for after too many authentication failures.- 
Fields inherited from class org.apache.catalina.realm.CombinedRealmrealms
 - 
Fields inherited from class org.apache.catalina.realm.RealmBaseallRolesMode, container, containerLog, realmPath, sm, stripRealmForGss, support, USER_ATTRIBUTES_DELIMITER, USER_ATTRIBUTES_WILDCARD, userAttributes, userAttributesList, validate, x509UsernameRetriever, x509UsernameRetrieverClassName
 - 
Fields inherited from class org.apache.catalina.util.LifecycleMBeanBasemserver
 - 
Fields inherited from interface org.apache.catalina.LifecycleAFTER_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 SummaryConstructors Constructor Description LockOutRealm()
 - 
Method SummaryAll Methods Instance Methods Concrete Methods Modifier and Type Method Description java.security.Principalauthenticate(java.lang.String username, java.lang.String credentials)Try to authenticate using the specified username and credentials.java.security.Principalauthenticate(java.lang.String username, java.lang.String clientDigest, java.lang.String nonce, java.lang.String nc, java.lang.String cnonce, java.lang.String qop, java.lang.String realmName, java.lang.String digestA2, java.lang.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.java.security.Principalauthenticate(java.security.cert.X509Certificate[] certs)Try to authenticate using a chain ofX509Certificates.java.security.Principalauthenticate(org.ietf.jgss.GSSContext gssContext, boolean storeCreds)Try to authenticate using aGSSContext.java.security.Principalauthenticate(org.ietf.jgss.GSSName gssName, org.ietf.jgss.GSSCredential gssCredential)Try to authenticate using aGSSName.intgetCacheRemovalWarningTime()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.intgetCacheSize()Get the maximum number of users for which authentication failure will be kept in the cache.intgetFailureCount()Get the number of failed authentication attempts required to lock the user account.intgetLockOutTime()Get the period for which an account will be locked.booleanisLocked(java.lang.String username)voidsetCacheRemovalWarningTime(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.voidsetCacheSize(int cacheSize)Set the maximum number of users for which authentication failure will be kept in the cache.voidsetFailureCount(int failureCount)Set the number of failed authentication attempts required to lock the user account.voidsetLockOutTime(int lockOutTime)Set the period for which an account will be locked.protected voidstartInternal()Prepare for the beginning of active use of the public methods of this component and implement the requirements ofLifecycleBase.startInternal().voidunlock(java.lang.String username)Unlock the specified username.- 
Methods inherited from class org.apache.catalina.realm.CombinedRealmaddRealm, authenticate, backgroundProcess, destroyInternal, getNestedRealms, getPassword, getPrincipal, getRealms, hasRole, isAvailable, setContainer, setCredentialHandler, stopInternal
 - 
Methods inherited from class org.apache.catalina.realm.RealmBaseaddPropertyChangeListener, authenticate, findSecurityConstraints, getAllRolesMode, getContainer, getCredentialHandler, getDigest, getDigest, getDomainInternal, getObjectNameKeyProperties, getPrincipal, getPrincipal, getPrincipal, getRealmPath, getRealmSuffix, getRoles, 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.LifecycleMBeanBasegetDomain, getObjectName, postDeregister, postRegister, preDeregister, preRegister, register, setDomain, unregister, unregister
 - 
Methods inherited from class org.apache.catalina.util.LifecycleBaseaddLifecycleListener, destroy, findLifecycleListeners, fireLifecycleEvent, getState, getStateName, getThrowOnFailure, init, removeLifecycleListener, setState, setState, setThrowOnFailure, start, stop
 
- 
 
- 
- 
- 
Field Detail- 
failureCountprotected int failureCount The number of times in a row a user has to fail authentication to be locked out. Defaults to 5.
 - 
lockOutTimeprotected int lockOutTime The time (in seconds) a user is locked out for after too many authentication failures. Defaults to 300 (5 minutes).
 - 
cacheSizeprotected 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.
 - 
cacheRemovalWarningTimeprotected 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).
 - 
failedUsersprotected java.util.Map<java.lang.String,LockOutRealm.LockRecord> failedUsers Users whose last authentication attempt failed. Entries will be ordered in access order from least recent to most recent.
 
- 
 - 
Method Detail- 
startInternalprotected void startInternal() throws LifecycleExceptionDescription copied from class:RealmBasePrepare for the beginning of active use of the public methods of this component and implement the requirements ofLifecycleBase.startInternal().- Overrides:
- startInternalin class- CombinedRealm
- Throws:
- LifecycleException- if this component detects a fatal error that prevents this component from being used
 
 - 
authenticatepublic java.security.Principal authenticate(java.lang.String username, java.lang.String clientDigest, java.lang.String nonce, java.lang.String nc, java.lang.String cnonce, java.lang.String qop, java.lang.String realmName, java.lang.String digestA2, java.lang.String algorithm)Description copied from interface:RealmTry 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:
- authenticatein interface- Realm
- Overrides:
- authenticatein 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" (- ncand- cnoncewill only be used, if- qopis 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 nullif there is none.
 
 - 
authenticatepublic java.security.Principal authenticate(java.lang.String username, java.lang.String credentials)Description copied from interface:RealmTry to authenticate using the specified username and credentials.- Specified by:
- authenticatein interface- Realm
- Overrides:
- authenticatein 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 nullif there is none
 
 - 
authenticatepublic java.security.Principal authenticate(java.security.cert.X509Certificate[] certs) Description copied from interface:RealmTry to authenticate using a chain ofX509Certificates.- Specified by:
- authenticatein interface- Realm
- Overrides:
- authenticatein 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 nullif there is none
 
 - 
authenticatepublic java.security.Principal authenticate(org.ietf.jgss.GSSContext gssContext, boolean storeCreds)Description copied from interface:RealmTry to authenticate using aGSSContext.- Specified by:
- authenticatein interface- Realm
- Overrides:
- authenticatein 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 nullif there is none
 
 - 
authenticatepublic java.security.Principal authenticate(org.ietf.jgss.GSSName gssName, org.ietf.jgss.GSSCredential gssCredential)Description copied from interface:RealmTry to authenticate using aGSSName. Note that this default method will be turned into an abstract one in Tomcat 10.- Specified by:
- authenticatein interface- Realm
- Overrides:
- authenticatein class- CombinedRealm
- Parameters:
- gssName- The- GSSNameof the principal to look up
- gssCredential- The- GSSCredentialof the principal, may be- null
- Returns:
- the associated principal, or nullif there is none
 
 - 
unlockpublic void unlock(java.lang.String username) Unlock the specified username. This will remove all records of authentication failures for this user.- Parameters:
- username- The user to unlock
 
 - 
isLockedpublic boolean isLocked(java.lang.String username) 
 - 
getFailureCountpublic int getFailureCount() Get the number of failed authentication attempts required to lock the user account.- Returns:
- the failureCount
 
 - 
setFailureCountpublic void setFailureCount(int failureCount) Set the number of failed authentication attempts required to lock the user account.- Parameters:
- failureCount- the failureCount to set
 
 - 
getLockOutTimepublic int getLockOutTime() Get the period for which an account will be locked.- Returns:
- the lockOutTime
 
 - 
setLockOutTimepublic void setLockOutTime(int lockOutTime) Set the period for which an account will be locked.- Parameters:
- lockOutTime- the lockOutTime to set
 
 - 
getCacheSizepublic int getCacheSize() Get the maximum number of users for which authentication failure will be kept in the cache.- Returns:
- the cacheSize
 
 - 
setCacheSizepublic 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
 
 - 
getCacheRemovalWarningTimepublic 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
 
 - 
setCacheRemovalWarningTimepublic 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
 
 
- 
 
-