org.apache.catalina.authenticator
Class AuthenticatorBase

java.lang.Object
  org.apache.catalina.valves.ValveBase
      org.apache.catalina.authenticator.AuthenticatorBase

All Implemented Interfaces:

Authenticator, Contained, Lifecycle, Valve

Direct Known 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: 684900 $ $Date: 2008-08-11 21:16:02 +0100 (Mon, 11 Aug 2008) $

Author:

Craig R. McClanahan

Field Summary

protected java.lang.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 static java.lang.String	DEFAULT_ALGORITHM The default message digest algorithm to use if we cannot use the requested one.
protected java.security.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 java.lang.String	entropy A String initialization parameter used to increase the entropy of the initialization of our random number generator.
protected static java.lang.String	info Descriptive information about this implementation.
protected LifecycleSupport	lifecycle The lifecycle event support for this component.
protected java.util.Random	random A random number generator to use when generating session identifiers.
protected java.lang.String	randomClass The Java class name of the random number generator class to be used when generating session identifiers.
protected static int	SESSION_ID_BYTES The number of random bytes to include when generating a session identifier.
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

Fields inherited from interface org.apache.catalina.Lifecycle

AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, START_EVENT, STOP_EVENT

Constructor Summary

AuthenticatorBase()

Method Summary

protected boolean	accessControl(HttpRequest request, HttpResponse response, SecurityConstraint constraint) Perform access control based on the specified authorization constraint.
void	addLifecycleListener(LifecycleListener listener) Add a lifecycle event listener to this component.
protected void	associate(java.lang.String ssoId, Session session) Associate the specified single sign on identifier with the specified Session.
protected abstract boolean	authenticate(HttpRequest request, HttpResponse response, LoginConfig config) Authenticate the user making this request, based on the specified login configuration.
protected boolean	checkUserData(HttpRequest request, HttpResponse response, SecurityConstraint constraint) Enforce any user data constraint required by the security constraint guarding this request URI.
protected SecurityConstraint	findConstraint(HttpRequest request) Return the SecurityConstraint configured to guard the request URI for this request, or null if there is no such constraint.
LifecycleListener[]	findLifecycleListeners() Get the lifecycle listeners associated with this lifecycle.
protected java.lang.String	generateSessionId() Generate and return a new session identifier for the cookie that identifies an SSO principal.
java.lang.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 java.security.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.
java.lang.String	getEntropy() Return the entropy increaser value, or compute a semi-useful value if this String has not yet been set.
java.lang.String	getInfo() Return descriptive information about this Valve implementation.
protected java.util.Random	getRandom() Return the random number generator instance we should use for generating session identifiers.
java.lang.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(java.lang.String message) Log a message on the Logger associated with our Container (if any).
protected void	log(java.lang.String message, java.lang.Throwable throwable) Log a message on the Logger associated with our Container (if any).
protected boolean	reauthenticateFromSSO(java.lang.String ssoId, HttpRequest request) Attempts reauthentication to the Realm using the credentials included in argument entry.
protected void	register(HttpRequest request, HttpResponse response, java.security.Principal principal, java.lang.String authType, java.lang.String username, java.lang.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(java.lang.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(java.lang.String entropy) Set the entropy increaser value.
void	setRandomClass(java.lang.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 java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_ALGORITHM

protected static final java.lang.String DEFAULT_ALGORITHM

The default message digest algorithm to use if we cannot use the requested one.

See Also:

Constant Field Values

SESSION_ID_BYTES

protected static final int SESSION_ID_BYTES

The number of random bytes to include when generating a session identifier.

See Also:

Constant Field Values

algorithm

protected java.lang.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 java.security.MessageDigest digest

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

entropy

protected java.lang.String entropy

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

info

protected static final java.lang.String info

Descriptive information about this implementation.

See Also:

Constant Field Values

disableProxyCaching

protected boolean disableProxyCaching

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

lifecycle

protected LifecycleSupport lifecycle

The lifecycle event support for this component.

random

protected java.util.Random random

A random number generator to use when generating session identifiers.

randomClass

protected java.lang.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?

Constructor Detail

AuthenticatorBase

public AuthenticatorBase()

Method Detail

getAlgorithm

public java.lang.String getAlgorithm()

Return the message digest algorithm for this Manager.

setAlgorithm

public void setAlgorithm(java.lang.String algorithm)

Set the message digest algorithm for this Manager.

Parameters:

algorithm - The new message digest algorithm

getCache

public boolean getCache()

Return the cache authenticated Principals flag.

setCache

public void setCache(boolean cache)

Set the cache authenticated Principals flag.

Parameters:

cache - The new cache flag

getContainer

public Container getContainer()

Return the Container to which this Valve is attached.

Specified by:

getContainer in interface Contained

Overrides:

getContainer in class ValveBase

setContainer

public void setContainer(Container container)

Set the Container to which this Valve is attached.

Specified by:

setContainer in interface Contained

Overrides:

setContainer in class ValveBase

Parameters:

container - The container to which we are attached

getDebug

public int getDebug()

Return the debugging detail level for this component.

Overrides:

getDebug in class ValveBase

setDebug

public void setDebug(int debug)

Set the debugging detail level for this component.

Overrides:

setDebug in class ValveBase

Parameters:

debug - The new debugging detail level

getEntropy

public java.lang.String getEntropy()

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

setEntropy

public void setEntropy(java.lang.String entropy)

Set the entropy increaser value.

Parameters:

entropy - The new entropy increaser value

getInfo

public java.lang.String getInfo()

Return descriptive information about this Valve implementation.

Specified by:

getInfo in interface Valve

Overrides:

getInfo in class ValveBase

getRandomClass

public java.lang.String getRandomClass()

Return the random number generator class name.

setRandomClass

public void setRandomClass(java.lang.String randomClass)

Set the random number generator class name.

Parameters:

randomClass - The new random number generator class name

getDisableProxyCaching

public boolean getDisableProxyCaching()

Return the flag that states if we add headers to disable caching by proxies.

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.

invoke

public void invoke(Request request,
                   Response response,
                   ValveContext context)
            throws java.io.IOException,
                   javax.servlet.ServletException

Enforce the security restrictions in the web application deployment descriptor of our associated Context.

Specified by:

invoke in interface Valve

Specified by:

invoke in class 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

Throws:

java.io.IOException - if an input/output error occurs

javax.servlet.ServletException - if thrown by a processing element

accessControl

protected boolean accessControl(HttpRequest request,
                                HttpResponse response,
                                SecurityConstraint constraint)
                         throws java.io.IOException

Perform access control based on the specified authorization constraint. Return true if this constraint is satisfied and processing should continue, or false otherwise.

Parameters:

request - Request we are processing

response - Response we are creating

constraint - Security constraint we are enforcing

Throws:

java.io.IOException - if an input/output error occurs

associate

protected void associate(java.lang.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 abstract boolean authenticate(HttpRequest request,
                                        HttpResponse response,
                                        LoginConfig config)
                                 throws java.io.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

Throws:

java.io.IOException - if an input/output error occurs

checkUserData

protected boolean checkUserData(HttpRequest request,
                                HttpResponse response,
                                SecurityConstraint constraint)
                         throws java.io.IOException

Enforce any user data constraint required by the security constraint guarding this request URI. Return true if this constraint was not violated and processing should continue, or false if we have created a response already.

Parameters:

request - Request we are processing

response - Response we are creating

constraint - Security constraint being checked

Throws:

java.io.IOException - if an input/output error occurs

findConstraint

protected SecurityConstraint findConstraint(HttpRequest request)

Return the SecurityConstraint configured to guard the request URI for this request, or null if there is no such constraint.

Parameters:

request - Request we are processing

generateSessionId

protected java.lang.String generateSessionId()

Generate and return a new session identifier for the cookie that identifies an SSO principal.

getDigest

protected java.security.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.

getRandom

protected java.util.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.

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?

log

protected void log(java.lang.String message)

Log a message on the Logger associated with our Container (if any).

Parameters:

message - Message to be logged

log

protected void log(java.lang.String message,
                   java.lang.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(java.lang.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,
                        java.security.Principal principal,
                        java.lang.String authType,
                        java.lang.String username,
                        java.lang.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)

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

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

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

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