org.apache.catalina.authenticator
Class AuthenticatorBase

java.lang.Object
  extended byorg.apache.catalina.valves.ValveBase
      extended byorg.apache.catalina.authenticator.AuthenticatorBase
All Implemented Interfaces:
Authenticator, Contained, Lifecycle, javax.management.MBeanRegistration, 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:
$Id: AuthenticatorBase.java 992373 2010-09-03 16:56:30Z markt $
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  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 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 java.lang.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.
protected  boolean started
          Has this component been started?
 
Fields inherited from class org.apache.catalina.valves.ValveBase
container, containerLog, controller, domain, mserver, next, oname
 
Fields inherited from interface org.apache.catalina.Lifecycle
AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, DESTROY_EVENT, INIT_EVENT, PERIODIC_EVENT, START_EVENT, STOP_EVENT
 
Constructor Summary
AuthenticatorBase()
           
 
Method Summary
 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(Request request, Response 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  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.
 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  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.
 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.
protected  boolean reauthenticateFromSSO(java.lang.String ssoId, Request request)
          Attempts reauthentication to the Realm using the credentials included in argument entry.
protected  void register(Request request, Response 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 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(java.lang.String entropy)
          Set the entropy increaser value.
 void setRandomClass(java.lang.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.
 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
backgroundProcess, createObjectName, getContainerName, getController, getDomain, getNext, getObjectName, getParentName, postDeregister, postRegister, preDeregister, preRegister, setController, setNext, setObjectName, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, 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

REALM_NAME

protected static final java.lang.String REALM_NAME
Default authentication realm name.

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?


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


securePagesWithPragma

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


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

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.

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 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
Throws:
java.io.IOException - if an input/output error occurs
javax.servlet.ServletException - if thrown by a processing element

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(Request request,
                                        Response 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

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.


reauthenticateFromSSO

protected boolean reauthenticateFromSSO(java.lang.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

protected void register(Request request,
                        Response 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


Copyright © 2000-2012 Apache Software Foundation. All Rights Reserved.