org.apache.catalina.authenticator

Class AuthenticatorBase

Implemented Interfaces:
Authenticator, Contained, Lifecycle, MBeanRegistration, Valve
Known Direct Subclasses:
BasicAuthenticator, DigestAuthenticator, FormAuthenticator, NonLoginAuthenticator, SSLAuthenticator

public abstract class AuthenticatorBase
extends ValveBase
implements Authenticator, Lifecycle

Basic implementation of the Valve interface that enforces the <security-constraint> elements in the web application deployment descriptor. This functionality is implemented as a Valve so that it can be ommitted in environments that do not require these features. Individual implementations of each supported authentication method can subclass this base class as required.

USAGE CONSTRAINT: When this class is utilized, the Context to which it is attached (or a parent Container in a hierarchy) must have an associated Realm that can be used for authenticating users and enumerating the roles to which they have been assigned.

USAGE CONSTRAINT: This Valve is only useful when processing HTTP requests. Requests of any other type will simply be passed through.

Version:
$Revision: 1.19 $ $Date: 2004/04/26 21:54:15 $

Author:
Craig R. McClanahan

Field Summary

protected static String
DEFAULT_ALGORITHM
The default message digest algorithm to use if we cannot use the requested one.
protected static int
SESSION_ID_BYTES
The number of random bytes to include when generating a session identifier.
protected String
algorithm
The message digest algorithm to be used when generating session identifiers.
protected boolean
cache
Should we cache authenticated Principals if the request is part of an HTTP session?
protected Context
context
The Context to which this Valve is attached.
protected int
debug
The debugging detail level for this component.
protected MessageDigest
digest
Return the MessageDigest implementation to be used when creating session identifiers.
protected boolean
disableProxyCaching
Flag to determine if we disable proxy caching, or leave the issue up to the webapp developer.
protected String
entropy
A String initialization parameter used to increase the entropy of the initialization of our random number generator.
protected static String
info
Descriptive information about this implementation.
protected LifecycleSupport
lifecycle
The lifecycle event support for this component.
protected Random
random
A random number generator to use when generating session identifiers.
protected String
randomClass
The Java class name of the random number generator class to be used when generating session identifiers.
protected static StringManager
sm
The string manager for this package.
protected SingleSignOn
sso
The SingleSignOn implementation in our request processing chain, if there is one.
protected boolean
started
Has this component been started?

Fields inherited from class org.apache.catalina.valves.ValveBase

container, controller, debug, domain, info, mserver, oname, sm

Fields inherited from interface org.apache.catalina.Lifecycle

AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, START_EVENT, STOP_EVENT

Method Summary

void
addLifecycleListener(LifecycleListener listener)
Add a lifecycle event listener to this component.
protected void
associate(String ssoId, Session session)
Associate the specified single sign on identifier with the specified Session.
protected boolean
authenticate(HttpRequest request, HttpResponse response, LoginConfig config)
Authenticate the user making this request, based on the specified login configuration.
LifecycleListener[]
findLifecycleListeners()
Get the lifecycle listeners associated with this lifecycle.
protected String
generateSessionId()
Generate and return a new session identifier for the cookie that identifies an SSO principal.
String
getAlgorithm()
Return the message digest algorithm for this Manager.
boolean
getCache()
Return the cache authenticated Principals flag.
Container
getContainer()
Return the Container to which this Valve is attached.
int
getDebug()
Return the debugging detail level for this component.
protected MessageDigest
getDigest()
Return the MessageDigest object to be used for calculating session identifiers.
boolean
getDisableProxyCaching()
Return the flag that states if we add headers to disable caching by proxies.
String
getEntropy()
Return the entropy increaser value, or compute a semi-useful value if this String has not yet been set.
String
getInfo()
Return descriptive information about this Valve implementation.
protected Random
getRandom()
Return the random number generator instance we should use for generating session identifiers.
String
getRandomClass()
Return the random number generator class name.
protected Session
getSession(HttpRequest request)
Return the internal Session that is associated with this HttpRequest, or null if there is no such Session.
protected Session
getSession(HttpRequest request, boolean create)
Return the internal Session that is associated with this HttpRequest, possibly creating a new one if necessary, or null if there is no such session and we did not create one.
void
invoke(Request request, Response response, ValveContext context)
Enforce the security restrictions in the web application deployment descriptor of our associated Context.
protected void
log(String message)
Log a message on the Logger associated with our Container (if any).
protected void
log(String message, Throwable throwable)
Log a message on the Logger associated with our Container (if any).
protected boolean
reauthenticateFromSSO(String ssoId, HttpRequest request)
Attempts reauthentication to the Realm using the credentials included in argument entry.
protected void
register(HttpRequest request, HttpResponse response, Principal principal, String authType, String username, String password)
Register an authenticated Principal and authentication type in our request, in the current session (if there is one), and with our SingleSignOn valve, if there is one.
void
removeLifecycleListener(LifecycleListener listener)
Remove a lifecycle event listener from this component.
void
setAlgorithm(String algorithm)
Set the message digest algorithm for this Manager.
void
setCache(boolean cache)
Set the cache authenticated Principals flag.
void
setContainer(Container container)
Set the Container to which this Valve is attached.
void
setDebug(int debug)
Set the debugging detail level for this component.
void
setDisableProxyCaching(boolean nocache)
Set the value of the flag that states if we add headers to disable caching by proxies.
void
setEntropy(String entropy)
Set the entropy increaser value.
void
setRandomClass(String randomClass)
Set the random number generator class name.
void
start()
Prepare for the beginning of active use of the public methods of this component.
void
stop()
Gracefully terminate the active use of the public methods of this component.

Methods inherited from class org.apache.catalina.valves.ValveBase

createObjectName, getContainer, getContainerName, getController, getDebug, getDomain, getInfo, getObjectName, getParentName, invoke, postDeregister, postRegister, preDeregister, preRegister, setContainer, setController, setDebug, setObjectName

Field Details

DEFAULT_ALGORITHM

protected static final String DEFAULT_ALGORITHM
The default message digest algorithm to use if we cannot use the requested one.


SESSION_ID_BYTES

protected static final int SESSION_ID_BYTES
The number of random bytes to include when generating a session identifier.

Field Value:
16


algorithm

protected String algorithm
The message digest algorithm to be used when generating session identifiers. This must be an algorithm supported by the java.security.MessageDigest class on your platform.


cache

protected boolean cache
Should we cache authenticated Principals if the request is part of an HTTP session?


context

protected Context context
The Context to which this Valve is attached.


debug

protected int debug
The debugging detail level for this component.


digest

protected MessageDigest digest
Return the MessageDigest implementation to be used when creating session identifiers.


disableProxyCaching

protected boolean disableProxyCaching
Flag to determine if we disable proxy caching, or leave the issue up to the webapp developer.


entropy

protected String entropy
A String initialization parameter used to increase the entropy of the initialization of our random number generator.


info

protected static final String info
Descriptive information about this implementation.


lifecycle

protected LifecycleSupport lifecycle
The lifecycle event support for this component.


random

protected Random random
A random number generator to use when generating session identifiers.


randomClass

protected String randomClass
The Java class name of the random number generator class to be used when generating session identifiers.


sm

protected static final StringManager sm
The string manager for this package.


sso

protected SingleSignOn sso
The SingleSignOn implementation in our request processing chain, if there is one.


started

protected boolean started
Has this component been started?

Method Details

addLifecycleListener

public void addLifecycleListener(LifecycleListener listener)
Add a lifecycle event listener to this component.
Specified by:
addLifecycleListener in interface Lifecycle

Parameters:
listener - The listener to add


associate

protected void associate(String ssoId,
                         Session session)
Associate the specified single sign on identifier with the specified Session.

Parameters:
ssoId - Single sign on identifier
session - Session to be associated


authenticate

protected boolean authenticate(HttpRequest request,
                               HttpResponse response,
                               LoginConfig config)
            throws IOException
Authenticate the user making this request, based on the specified login configuration. Return true if any specified constraint has been satisfied, or false if we have created a response challenge already.

Parameters:
request - Request we are processing
response - Response we are creating
config - Login configuration describing how authentication should be performed


findLifecycleListeners

public LifecycleListener[] findLifecycleListeners()
Get the lifecycle listeners associated with this lifecycle. If this Lifecycle has no listeners registered, a zero-length array is returned.
Specified by:
findLifecycleListeners in interface Lifecycle


generateSessionId

protected String generateSessionId()
Generate and return a new session identifier for the cookie that identifies an SSO principal.


getAlgorithm

public String getAlgorithm()
Return the message digest algorithm for this Manager.


getCache

public boolean getCache()
Return the cache authenticated Principals flag.


getContainer

public Container getContainer()
Return the Container to which this Valve is attached.
Specified by:
getContainer in interface Contained
Overrides:
getContainer in interface ValveBase


getDebug

public int getDebug()
Return the debugging detail level for this component.
Overrides:
getDebug in interface ValveBase


getDigest

protected MessageDigest getDigest()
Return the MessageDigest object to be used for calculating session identifiers. If none has been created yet, initialize one the first time this method is called.


getDisableProxyCaching

public boolean getDisableProxyCaching()
Return the flag that states if we add headers to disable caching by proxies.


getEntropy

public String getEntropy()
Return the entropy increaser value, or compute a semi-useful value if this String has not yet been set.


getInfo

public String getInfo()
Return descriptive information about this Valve implementation.
Specified by:
getInfo in interface Valve
Overrides:
getInfo in interface ValveBase


getRandom

protected Random getRandom()
Return the random number generator instance we should use for generating session identifiers. If there is no such generator currently defined, construct and seed a new one.


getRandomClass

public String getRandomClass()
Return the random number generator class name.


getSession

protected Session getSession(HttpRequest request)
Return the internal Session that is associated with this HttpRequest, or null if there is no such Session.

Parameters:
request - The HttpRequest we are processing


getSession

protected Session getSession(HttpRequest request,
                             boolean create)
Return the internal Session that is associated with this HttpRequest, possibly creating a new one if necessary, or null if there is no such session and we did not create one.

Parameters:
request - The HttpRequest we are processing
create - Should we create a session if needed?


invoke

public void invoke(Request request,
                   Response response,
                   ValveContext context)
            throws IOException,
                   ServletException
Enforce the security restrictions in the web application deployment descriptor of our associated Context.
Specified by:
invoke in interface Valve
Overrides:
invoke in interface ValveBase

Parameters:
request - Request to be processed
response - Response to be processed
context - The valve context used to invoke the next valve in the current processing pipeline


log

protected void log(String message)
Log a message on the Logger associated with our Container (if any).

Parameters:
message - Message to be logged


log

protected void log(String message,
                   Throwable throwable)
Log a message on the Logger associated with our Container (if any).

Parameters:
message - Message to be logged
throwable - Associated exception


reauthenticateFromSSO

protected boolean reauthenticateFromSSO(String ssoId,
                                        HttpRequest request)
Attempts reauthentication to the Realm using the credentials included in argument entry.

Parameters:
ssoId - identifier of SingleSignOn session with which the caller is associated
request - the request that needs to be authenticated


register

protected void register(HttpRequest request,
                        HttpResponse response,
                        Principal principal,
                        String authType,
                        String username,
                        String password)
Register an authenticated Principal and authentication type in our request, in the current session (if there is one), and with our SingleSignOn valve, if there is one. Set the appropriate cookie to be returned.

Parameters:
request - The servlet request we are processing
response - The servlet response we are generating
principal - The authenticated Principal to be registered
authType - The authentication type to be registered
username - Username used to authenticate (if any)
password - Password used to authenticate (if any)


removeLifecycleListener

public void removeLifecycleListener(LifecycleListener listener)
Remove a lifecycle event listener from this component.
Specified by:
removeLifecycleListener in interface Lifecycle

Parameters:
listener - The listener to remove


setAlgorithm

public void setAlgorithm(String algorithm)
Set the message digest algorithm for this Manager.

Parameters:
algorithm - The new message digest algorithm


setCache

public void setCache(boolean cache)
Set the cache authenticated Principals flag.

Parameters:
cache - The new cache flag


setContainer

public void setContainer(Container container)
Set the Container to which this Valve is attached.
Specified by:
setContainer in interface Contained
Overrides:
setContainer in interface ValveBase

Parameters:
container - The container to which we are attached


setDebug

public void setDebug(int debug)
Set the debugging detail level for this component.
Overrides:
setDebug in interface ValveBase

Parameters:
debug - The new debugging detail level


setDisableProxyCaching

public void setDisableProxyCaching(boolean nocache)
Set the value of the flag that states if we add headers to disable caching by proxies.

Parameters:
nocache - true if we add headers to disable proxy caching, false if we leave the headers alone.


setEntropy

public void setEntropy(String entropy)
Set the entropy increaser value.

Parameters:
entropy - The new entropy increaser value


setRandomClass

public void setRandomClass(String randomClass)
Set the random number generator class name.

Parameters:
randomClass - The new random number generator class name


start

public void start()
            throws LifecycleException
Prepare for the beginning of active use of the public methods of this component. This method should be called after configure(), and before any of the public methods of the component are utilized.
Specified by:
start in interface Lifecycle

Throws:
LifecycleException - if this component detects a fatal error that prevents this component from being used


stop

public void stop()
            throws LifecycleException
Gracefully terminate the active use of the public methods of this component. This method should be the last one called on a given instance of this component.
Specified by:
stop in interface Lifecycle

Throws:
LifecycleException - if this component detects a fatal error that needs to be reported


Copyright B) 2000-2003 Apache Software Foundation. All Rights Reserved.