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

Author:
  Craig R. McClanahan

### Field Summary

Fields
`protected boolean` `alwaysUseSession` Should a session always be used once a user is authenticated?
`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 boolean` `disableProxyCaching` Flag to determine if we disable proxy caching, or leave the issue up to the webapp developer.
`protected static String` `info` Descriptive information about this implementation.
`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 String` `secureRandomAlgorithm` The name of the algorithm to use to create instances of `SecureRandom` which are used to generate SSO session IDs.
`protected String` `secureRandomClass` The Java class name of the secure random number generator class to be used when generating SSO session identifiers.
`protected String` `secureRandomProvider` The name of the provider to use to create instances of `SecureRandom` which are used to generate session SSO IDs.
`protected SessionIdGenerator` `sessionIdGenerator`
`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_DESTROY_EVENT, AFTER_INIT_EVENT, AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_DESTROY_EVENT, BEFORE_INIT_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, CONFIGURE_START_EVENT, CONFIGURE_STOP_EVENT, PERIODIC_EVENT, START_EVENT, STOP_EVENT`

### Constructor Summary

Constructors
Constructor and Description
`AuthenticatorBase()`

### Method Summary

Methods
`protected void` `associate(String ssoId, Session session)` Associate the specified single sign on identifier with the specified Session.
`boolean` `authenticate(Request request, HttpServletResponse response)` Authenticate the user making this request, based on the login configuration of the `Context` with which this Authenticator is associated.
`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)` Process the login request.
`boolean` `getAlwaysUseSession()`
`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.
`boolean` `getDisableProxyCaching()` Return the flag that states if we add headers to disable caching by proxies.
`String` `getInfo()` Return descriptive information about this Valve implementation.
`boolean` `getSecurePagesWithPragma()` Return the flag that states, if proxy caching is disabled, what headers we add to disable the caching.
`String` `getSecureRandomAlgorithm()` Return the secure random number generator algorithm name.
`String` `getSecureRandomClass()` Return the secure random number generator class name.
`String` `getSecureRandomProvider()` Return the secure random number generator provider name.
`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` `setAlwaysUseSession(boolean alwaysUseSession)`
`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` `setSecurePagesWithPragma(boolean securePagesWithPragma)` Set the value of the flag that states what headers we add to disable proxy caching.
`void` `setSecureRandomAlgorithm(String secureRandomAlgorithm)` Set the secure random number generator algorithm name.
`void` `setSecureRandomClass(String secureRandomClass)` Set the secure random number generator class name.
`void` `setSecureRandomProvider(String secureRandomProvider)` Set the secure random number generator provider name.
`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

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

#### alwaysUseSession

    protected boolean alwaysUseSession

Should a session always be used once a user is authenticated? This may offer some performance benefits since the session can then be used to cache the authenticated Principal, hence removing the need to authenticate the user via the Realm on every request. This may be of help for combinations such as BASIC authentication used with the JNDIRealm or DataSourceRealms. However there will also be the performance cost of creating and GC'ing the session. By default, a session will not be created.

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

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

#### secureRandomClass

    protected String secureRandomClass

The Java class name of the secure random number generator class to be used when generating SSO session identifiers. The random number generator class must be self-seeding and have a zero-argument constructor. If not specified, an instance of `SecureRandom` will be generated.

#### secureRandomAlgorithm

    protected String secureRandomAlgorithm

The name of the algorithm to use to create instances of `SecureRandom` which are used to generate SSO session IDs. If no algorithm is specified, SHA1PRNG is used. To use the platform default (which may be SHA1PRNG), specify the empty string. If an invalid algorithm and/or provider is specified the SecureRandom instances will be created using the defaults. If that fails, the SecureRandom instances will be created using platform defaults.

#### secureRandomProvider

    protected String secureRandomProvider

The name of the provider to use to create instances of `SecureRandom` which are used to generate session SSO IDs. If no algorithm is specified the of SHA1PRNG default is used. If an invalid algorithm and/or provider is specified the SecureRandom instances will be created using the defaults. If that fails, the SecureRandom instances will be created using platform defaults.

#### sessionIdGenerator

    protected SessionIdGenerator sessionIdGenerator

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

#### getAlwaysUseSession

    public boolean getAlwaysUseSession()

#### setAlwaysUseSession

    public void setAlwaysUseSession(boolean alwaysUseSession)

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

#### getInfo

    public String getInfo()

Return descriptive information about this Valve implementation.

Specified by:
  `getInfo` in interface `Valve`
Overrides:
  `getInfo` in class `ValveBase`

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

#### getSecureRandomClass

    public String getSecureRandomClass()

Return the secure random number generator class name.

#### setSecureRandomClass

    public void setSecureRandomClass(String secureRandomClass)

Set the secure random number generator class name.

Parameters:
  `secureRandomClass` - The new secure random number generator class name

#### getSecureRandomAlgorithm

    public String getSecureRandomAlgorithm()

Return the secure random number generator algorithm name.

#### setSecureRandomAlgorithm

    public void setSecureRandomAlgorithm(String secureRandomAlgorithm)

Set the secure random number generator algorithm name.

Parameters:
  `secureRandomAlgorithm` - The new secure random number generator algorithm name

#### getSecureRandomProvider

    public String getSecureRandomProvider()

Return the secure random number generator provider name.

#### setSecureRandomProvider

    public void setSecureRandomProvider(String secureRandomProvider)

Set the secure random number generator provider name.

Parameters:
  `secureRandomProvider` - The new secure random number generator provider name

#### 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 boolean authenticate(Request request,
                       HttpServletResponse response)
                         throws IOException

Authenticate the user making this request, based on the login configuration of the `Context` with which this Authenticator is associated. 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
Throws:
  `IOException` - if an input/output error occurs

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

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

Process the login request.

Parameters:
  `request` - Associated request
  `username` - The user
  `password` - The password
Returns:
  The authenticated Principal
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