Top Description Inners Fields Constructors Methods
org.apache.catalina.realm

public Class LockOutRealm

extends CombinedRealm
Class Inheritance
Imports
java.security.Principal, java.security.cert.X509Certificate, java.util.LinkedHashMap, .Map, java.util.concurrent.atomic.AtomicInteger, org.apache.catalina.LifecycleException, org.apache.juli.logging.Log, .LogFactory, org.ietf.jgss.GSSContext, .GSSCredential, .GSSException, .GSSName
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 and Inner Type Summary

Modifier and TypeClass and Description
protected static class
LockOutRealm.LockRecord

Field Summary

Modifier and TypeField 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.

private static final Log
log

Hides org.apache.catalina.realm.CombinedRealm.log.

Inherited from org.apache.catalina.realm.CombinedRealm:
realms

Constructor Summary

AccessConstructor and Description
public
LockOutRealm()

Method Summary

Modifier and TypeMethod and Description
public Principal
authenticate(String
Username of the Principal to look up
username, String
Digest which has been submitted by the client
clientDigest, String
Unique (or supposedly unique) token which has been used for this request
nonce, String
the nonce counter
nc, String
the client chosen nonce
cnonce, String
the "quality of protection" (nc and cnonce will only be used, if qop is not null).
qop, String
Realm name
realmName, String
Second digest calculated as digest(Method + ":" + uri)
digestA2, String
The message digest algorithm to use
algorithm)

Overrides org.apache.catalina.realm.CombinedRealm.authenticate.

Overrides default org.apache.catalina.Realm.authenticate.

Try to authenticate with the specified username, which matches the digest calculated using the given parameters using the method described in RFC 7616.

public Principal
authenticate(String
Username of the Principal to look up
username, String
Password or other credentials to use in authenticating this username
credentials)

Overrides org.apache.catalina.realm.CombinedRealm.authenticate.

Implements org.apache.catalina.Realm.authenticate.

Try to authenticate using the specified username and credentials.

public Principal
authenticate(X509Certificate[]
Array of client certificates, with the first one in the array being the certificate of the client itself.
certs)

Overrides org.apache.catalina.realm.CombinedRealm.authenticate.

Implements org.apache.catalina.Realm.authenticate.

Try to authenticate using a chain of X509Certificates.

public Principal
authenticate(GSSContext
The gssContext processed by the Authenticator.
gssContext, boolean
Should the realm attempt to store the delegated credentials in the returned Principal?
storeCreds)

Overrides org.apache.catalina.realm.CombinedRealm.authenticate.

Implements org.apache.catalina.Realm.authenticate.

Try to authenticate using a GSSContext.

public Principal
authenticate(GSSName
The GSSName of the principal to look up
gssName, GSSCredential
The GSSCredential of the principal, may be null
gssCredential)

Overrides org.apache.catalina.realm.CombinedRealm.authenticate.

Implements org.apache.catalina.Realm.authenticate.

Try to authenticate using a GSSName.

private Principal
filterLockedAccounts(String username, Principal authenticatedUser)

public int

Returns:

the cacheRemovalWarningTime
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.

public int

Returns:

the cacheSize
getCacheSize()

Get the maximum number of users for which authentication failure will be kept in the cache.

public int

Returns:

the failureCount
getFailureCount()

Get the number of failed authentication attempts required to lock the user account.

public int

Returns:

the lockOutTime
getLockOutTime()

Get the period for which an account will be locked.

public boolean
isLocked(String username)

private void
registerAuthFailure(String username)

private synchronized void
registerAuthSuccess(String username)

public void
setCacheRemovalWarningTime(int
the cacheRemovalWarningTime to set
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.

public void
setCacheSize(int
the cacheSize to set
cacheSize)

Set the maximum number of users for which authentication failure will be kept in the cache.

public void
setFailureCount(int
the failureCount to set
failureCount)

Set the number of failed authentication attempts required to lock the user account.

public void
setLockOutTime(int
the lockOutTime to set
lockOutTime)

Set the period for which an account will be locked.

protected void
startInternal()

Overrides org.apache.catalina.realm.CombinedRealm.startInternal.

Prepare for the beginning of active use of the public methods of this component and implement the requirements of org.apache.catalina.util.LifecycleBase#startInternal().

public void
unlock(String
The user to unlock
username)

Unlock the specified username.

Inherited from org.apache.catalina.realm.CombinedRealm:
addRealmauthenticatebackgroundProcessdestroyInternalgetNestedRealmsgetPasswordgetPrincipalgetRealmshasRoleisAvailablesetContainersetCredentialHandlerstopInternal

Field Detail

cacheRemovalWarningTimeback to summary
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).

cacheSizeback to summary
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.

failedUsersback to summary
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.

failureCountback to summary
protected int failureCount

The number of times in a row a user has to fail authentication to be locked out. Defaults to 5.

lockOutTimeback to summary
protected int lockOutTime

The time (in seconds) a user is locked out for after too many authentication failures. Defaults to 300 (5 minutes).

logback to summary
private static final Log log

Hides org.apache.catalina.realm.CombinedRealm.log.

Constructor Detail

LockOutRealmback to summary
public LockOutRealm()

Method Detail

authenticateback to summary
public Principal authenticate(String username, String clientDigest, String nonce, String nc, String cnonce, String qop, String realmName, String digestA2, String algorithm)

Overrides org.apache.catalina.realm.CombinedRealm.authenticate.

Overrides default org.apache.catalina.Realm.authenticate.

Doc from org.apache.catalina.Realm.authenticate.

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

Parameters
username:String

Username of the Principal to look up

clientDigest:String

Digest which has been submitted by the client

nonce:String

Unique (or supposedly unique) token which has been used for this request

nc:String

the nonce counter

cnonce:String

the client chosen nonce

qop:String

the "quality of protection" (nc and cnonce will only be used, if qop is not null).

realmName:String

Realm name

digestA2:String

Second digest calculated as digest(Method + ":" + uri)

algorithm:String

The message digest algorithm to use

Returns:Principal

the associated principal, or null if there is none.

Annotations
@Override
authenticateback to summary
public Principal authenticate(String username, String credentials)

Overrides org.apache.catalina.realm.CombinedRealm.authenticate.

Implements org.apache.catalina.Realm.authenticate.

Doc from org.apache.catalina.Realm.authenticate.

Try to authenticate using the specified username and credentials.

Parameters
username:String

Username of the Principal to look up

credentials:String

Password or other credentials to use in authenticating this username

Returns:Principal

the associated principal, or null if there is none

Annotations
@Override
authenticateback to summary
public Principal authenticate(X509Certificate[] certs)

Overrides org.apache.catalina.realm.CombinedRealm.authenticate.

Implements org.apache.catalina.Realm.authenticate.

Doc from org.apache.catalina.Realm.authenticate.

Try to authenticate using a chain of X509Certificates.

Parameters
certs:X509Certificate[]

Array of client certificates, with the first one in the array being the certificate of the client itself.

Returns:Principal

the associated principal, or null if there is none

Annotations
@Override
authenticateback to summary
public Principal authenticate(GSSContext gssContext, boolean storeCreds)

Overrides org.apache.catalina.realm.CombinedRealm.authenticate.

Implements org.apache.catalina.Realm.authenticate.

Doc from org.apache.catalina.Realm.authenticate.

Try to authenticate using a GSSContext.

Parameters
gssContext:GSSContext

The gssContext processed by the Authenticator.

storeCreds:boolean

Should the realm attempt to store the delegated credentials in the returned Principal?

Returns:Principal

the associated principal, or null if there is none

Annotations
@Override
authenticateback to summary
public Principal authenticate(GSSName gssName, GSSCredential gssCredential)

Overrides org.apache.catalina.realm.CombinedRealm.authenticate.

Implements org.apache.catalina.Realm.authenticate.

Doc from org.apache.catalina.Realm.authenticate.

Try to authenticate using a GSSName.

Parameters
gssName:GSSName

The GSSName of the principal to look up

gssCredential:GSSCredential

The GSSCredential of the principal, may be null

Returns:Principal

the associated principal, or null if there is none

Annotations
@Override
filterLockedAccountsback to summary
private Principal filterLockedAccounts(String username, Principal authenticatedUser)
getCacheRemovalWarningTimeback to summary
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:int

the cacheRemovalWarningTime

getCacheSizeback to summary
public int getCacheSize()

Get the maximum number of users for which authentication failure will be kept in the cache.

Returns:int

the cacheSize

getFailureCountback to summary
public int getFailureCount()

Get the number of failed authentication attempts required to lock the user account.

Returns:int

the failureCount

getLockOutTimeback to summary
public int getLockOutTime()

Get the period for which an account will be locked.

Returns:int

the lockOutTime

isLockedback to summary
public boolean isLocked(String username)
registerAuthFailureback to summary
private void registerAuthFailure(String username)
registerAuthSuccessback to summary
private synchronized void registerAuthSuccess(String username)
setCacheRemovalWarningTimeback to summary
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:int

the cacheRemovalWarningTime to set

setCacheSizeback to summary
public void setCacheSize(int cacheSize)

Set the maximum number of users for which authentication failure will be kept in the cache.

Parameters
cacheSize:int

the cacheSize to set

setFailureCountback to summary
public void setFailureCount(int failureCount)

Set the number of failed authentication attempts required to lock the user account.

Parameters
failureCount:int

the failureCount to set

setLockOutTimeback to summary
public void setLockOutTime(int lockOutTime)

Set the period for which an account will be locked.

Parameters
lockOutTime:int

the lockOutTime to set

startInternalback to summary
protected void startInternal() throws LifecycleException

Overrides org.apache.catalina.realm.CombinedRealm.startInternal.

Doc from org.apache.catalina.realm.RealmBase.startInternal.

Prepare for the beginning of active use of the public methods of this component and implement the requirements of org.apache.catalina.util.LifecycleBase#startInternal().

Annotations
@Override
Exceptions
LifecycleException:
if this component detects a fatal error that prevents this component from being used
unlockback to summary
public void unlock(String username)

Unlock the specified username. This will remove all records of authentication failures for this user.

Parameters
username:String

The user to unlock

org.apache.catalina.realm back to summary

protected Class LockOutRealm.LockRecord

extends Object
Class Inheritance

Field Summary

Modifier and TypeField and Description
private final AtomicInteger
failures

private long
lastFailureTime

Constructor Summary

AccessConstructor and Description
protected
LockRecord()

Method Summary

Modifier and TypeMethod and Description
public int
getFailures()

public long
getLastFailureTime()

public void
registerFailure()

public void
setFailures(int theFailures)

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

failuresback to summary
private final AtomicInteger failures
lastFailureTimeback to summary
private long lastFailureTime

Constructor Detail

LockRecordback to summary
protected LockRecord()

Method Detail

getFailuresback to summary
public int getFailures()
getLastFailureTimeback to summary
public long getLastFailureTime()
registerFailureback to summary
public void registerFailure()
setFailuresback to summary
public void setFailures(int theFailures)