org.apache.catalina.authenticator
Class AuthenticatorBase

java.lang.Object
  org.apache.catalina.util.LifecycleBase
      org.apache.catalina.util.LifecycleMBeanBase
          org.apache.catalina.valves.ValveBase
              org.apache.catalina.authenticator.AuthenticatorBase

All Implemented Interfaces:

MBeanRegistration, Authenticator, Contained, Lifecycle, Valve

Direct Known Subclasses:

BasicAuthenticator, DigestAuthenticator, FormAuthenticator, NonLoginAuthenticator, SSLAuthenticator

public abstract class AuthenticatorBase
extends ValveBase
implements Authenticator

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 omitted 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:

$Id: AuthenticatorBase.java 1005834 2010-10-08 14:02:05Z markt $

Author:

Craig R. McClanahan

Field Summary

protected String	algorithm The message digest algorithm to be used when generating session identifiers.
protected static String	AUTH_HEADER_NAME Authentication header
protected boolean	cache Should we cache authenticated Principals if the request is part of an HTTP session?
protected boolean	changeSessionIdOnAuthentication Should the session ID, if any, be changed upon a successful authentication to prevent a session fixation attack?
protected Context	context The Context to which this Valve is attached.
protected static String	DEFAULT_ALGORITHM The default message digest algorithm to use if we cannot use the requested one.
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 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 String	REALM_NAME Default authentication realm name.
protected boolean	securePagesWithPragma Flag to determine if we disable proxy caching with headers incompatible with IE
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.

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

asyncSupported, container, containerLog, next

Fields inherited from class org.apache.catalina.util.LifecycleMBeanBase

mserver

Fields inherited from interface org.apache.catalina.Lifecycle

AFTER_INIT_EVENT, AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_INIT_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, CONFIGURE_START_EVENT, CONFIGURE_STOP_EVENT, DESTROY_EVENT, PERIODIC_EVENT, START_EVENT, STOP_EVENT

Constructor Summary

AuthenticatorBase()

Method Summary

protected void	associate(String ssoId, Session session) Associate the specified single sign on identifier with the specified Session.
abstract boolean	authenticate(Request request, HttpServletResponse response, LoginConfig config) Authenticate the user making this request, based on the specified login configuration.
protected Principal	doLogin(Request request, String username, String password)
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.
protected abstract String	getAuthMethod()
boolean	getCache() Return the cache authenticated Principals flag.
boolean	getChangeSessionIdOnAuthentication() Return the flag that states if we should change the session ID of an existing session upon successful authentication.
Container	getContainer() Return the Container to which this Valve is attached.
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.
boolean	getSecurePagesWithPragma() Return the flag that states, if proxy caching is disabled, what headers we add to disable the caching.
void	invoke(Request request, Response response) Enforce the security restrictions in the web application deployment descriptor of our associated Context.
void	login(String username, String password, Request request)
void	logout(Request request)
protected boolean	reauthenticateFromSSO(String ssoId, Request request) Attempts reauthentication to the Realm using the credentials included in argument entry.
void	register(Request request, HttpServletResponse 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	setAlgorithm(String algorithm) Set the message digest algorithm for this Manager.
void	setCache(boolean cache) Set the cache authenticated Principals flag.
void	setChangeSessionIdOnAuthentication(boolean changeSessionIdOnAuthentication) Set the value of the flag that states if we should change the session ID of an existing session upon successful authentication.
void	setContainer(Container container) Set the Container to which this Valve is attached.
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	setSecurePagesWithPragma(boolean securePagesWithPragma) Set the value of the flag that states what headers we add to disable proxy caching.
protected void	startInternal() Start this component and implement the requirements of LifecycleBase.startInternal().
protected void	stopInternal() Stop this component and implement the requirements of LifecycleBase.stopInternal().

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

backgroundProcess, event, getDomainInternal, getNext, getObjectNameKeyProperties, initInternal, isAsyncSupported, setAsyncSupported, setNext, toString

Methods inherited from class org.apache.catalina.util.LifecycleMBeanBase

destroyInternal, getDomain, getObjectName, postDeregister, postRegister, preDeregister, preRegister, register, setDomain, unregister

Methods inherited from class org.apache.catalina.util.LifecycleBase

addLifecycleListener, destroy, findLifecycleListeners, fireLifecycleEvent, getState, getStateName, init, removeLifecycleListener, setState, setState, start, stop

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_ALGORITHM

protected static final 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

AUTH_HEADER_NAME

protected static final String AUTH_HEADER_NAME

Authentication header

See Also:

Constant Field Values

REALM_NAME

protected static final String REALM_NAME

Default authentication realm name.

See Also:

Constant Field Values

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?

changeSessionIdOnAuthentication

protected boolean changeSessionIdOnAuthentication

Should the session ID, if any, be changed upon a successful authentication to prevent a session fixation attack?

context

protected Context context

The Context to which this Valve is attached.

digest

protected MessageDigest digest

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

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.

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.

securePagesWithPragma

protected boolean securePagesWithPragma

Flag to determine if we disable proxy caching with headers incompatible with IE

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.

Constructor Detail

AuthenticatorBase

public AuthenticatorBase()

Method Detail

getAlgorithm

public String getAlgorithm()

Return the message digest algorithm for this Manager.

setAlgorithm

public void setAlgorithm(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

getEntropy

public 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(String entropy)

Set the entropy increaser value.

Parameters:

entropy - The new entropy increaser value

getInfo

public String getInfo()

Return descriptive information about this Valve implementation.

Specified by:

getInfo in interface Valve

Overrides:

getInfo in class ValveBase

getRandomClass

public String getRandomClass()

Return the random number generator class name.

setRandomClass

public void setRandomClass(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.

getSecurePagesWithPragma

public boolean getSecurePagesWithPragma()

Return the flag that states, if proxy caching is disabled, what headers we add to disable the caching.

setSecurePagesWithPragma

public void setSecurePagesWithPragma(boolean securePagesWithPragma)

Set the value of the flag that states what headers we add to disable proxy caching.

Parameters:

securePagesWithPragma - true if we add headers which are incompatible with downloading office documents in IE under SSL but which fix a caching problem in Mozilla.

getChangeSessionIdOnAuthentication

public boolean getChangeSessionIdOnAuthentication()

Return the flag that states if we should change the session ID of an existing session upon successful authentication.

Returns:

true to change session ID upon successful authentication, false to do not perform the change.

setChangeSessionIdOnAuthentication

public void setChangeSessionIdOnAuthentication(boolean changeSessionIdOnAuthentication)

Set the value of the flag that states if we should change the session ID of an existing session upon successful authentication.

Parameters:

changeSessionIdOnAuthentication - true to change session ID upon successful authentication, false to do not perform the change.

invoke

public void invoke(Request request,
                   Response response)
            throws IOException,
                   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

Throws:

IOException - if an input/output error occurs

ServletException - if thrown by a processing element

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

public abstract boolean authenticate(Request request,
                                     HttpServletResponse 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.

Specified by:

authenticate in interface Authenticator

Parameters:

request - Request we are processing

response - Response we are populating

config - Login configuration describing how authentication should be performed

Throws:

IOException - if an input/output error occurs

generateSessionId

protected String generateSessionId()

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

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.

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.

reauthenticateFromSSO

protected boolean reauthenticateFromSSO(String ssoId,
                                        Request 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

public void register(Request request,
                     HttpServletResponse 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)

login

public void login(String username,
                  String password,
                  Request request)
           throws ServletException

Specified by:

login in interface Authenticator

Throws:

ServletException

getAuthMethod

protected abstract String getAuthMethod()

doLogin

protected Principal doLogin(Request request,
                            String username,
                            String password)
                     throws ServletException

Throws:

ServletException

logout

public void logout(Request request)
            throws ServletException

Specified by:

logout in interface Authenticator

Throws:

ServletException

startInternal

protected void startInternal()
                      throws LifecycleException

Start this component and implement the requirements of LifecycleBase.startInternal().

Overrides:

startInternal in class ValveBase

Throws:

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

stopInternal

protected void stopInternal()
                     throws LifecycleException

Stop this component and implement the requirements of LifecycleBase.stopInternal().

Overrides:

stopInternal in class ValveBase

Throws:

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