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:
RegistrationListener, MBeanRegistration, Authenticator, Contained, JmxEnabled, Lifecycle, Valve
Direct Known Subclasses:
BasicAuthenticator, DigestAuthenticator, FormAuthenticator, NonLoginAuthenticator, SpnegoAuthenticator, SSLAuthenticator
public abstract class AuthenticatorBase extends ValveBase implements Authenticator, RegistrationListener
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 Details

    • sm

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

    • AUTH_HEADER_NAME

      protected static final String AUTH_HEADER_NAME
      Authentication header
      See Also:

    • REALM_NAME

      protected static final String REALM_NAME
      Default authentication realm name.
      See Also:

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

    • 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. If SHA1PRNG is not available, the platform default will be 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 provider is specified the platform 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.

    • jaspicCallbackHandlerClass

      protected String jaspicCallbackHandlerClass
      The name of the JASPIC callback handler class. If none is specified the default CallbackHandlerImpl will be used.

    • sendAuthInfoResponseHeaders

      protected boolean sendAuthInfoResponseHeaders
      Should the auth information (remote user and auth type) be returned as response headers for a forwarded/proxied request? When the RemoteIpValve or RemoteIpFilter mark a forwarded request with the Globals.REQUEST_FORWARDED_ATTRIBUTE this authenticator can return the values of HttpServletRequest.getRemoteUser() and HttpServletRequest.getAuthType() as response headers remote-user and auth-type to a reverse proxy. This is useful, e.g., for access log consistency or other decisions to make.

    • sessionIdGenerator

      protected SessionIdGeneratorBase sessionIdGenerator

    • sso

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

  • Constructor Details

    • AuthenticatorBase

      public AuthenticatorBase()

  • Method Details

    • getRealmName

      protected static String getRealmName(Context context)

    • getAllowCorsPreflight

      public String getAllowCorsPreflight()

    • setAllowCorsPreflight

      public void setAllowCorsPreflight(String allowCorsPreflight)

    • getAlwaysUseSession

      public boolean getAlwaysUseSession()

    • setAlwaysUseSession

      public void setAlwaysUseSession(boolean alwaysUseSession)

    • getCache

      public boolean getCache()
      Return the cache authenticated Principals flag.
      Returns:
      true if authenticated Principals will be cached, otherwise false

    • setCache

      public void setCache(boolean cache)
      Set the cache authenticated Principals flag.
      Parameters:
      cache - The new cache flag

    • getContainer

      public Container getContainer()
      Description copied from interface: Contained
      Get the Container with which this instance is associated.
      Specified by:
      getContainer in interface Contained
      Overrides:
      getContainer in class ValveBase
      Returns:
      The Container with which this instance is associated or null if not associated with a Container

    • setContainer

      public void setContainer(Container container)
      Description copied from interface: Contained
      Set the Container with which this instance is associated.
      Specified by:
      setContainer in interface Contained
      Overrides:
      setContainer in class ValveBase
      Parameters:
      container - The Container instance with which this instance is to be associated, or null to disassociate this instance from any Container

    • getDisableProxyCaching

      public boolean getDisableProxyCaching()
      Return the flag that states if we add headers to disable caching by proxies.
      Returns:
      true if the headers will be added, otherwise false

    • 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.
      Returns:
      true if a Pragma header should be used, otherwise false

    • 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.
      Returns:
      The fully qualified name of the SecureRandom implementation to use

    • 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.
      Returns:
      The name of the SecureRandom algorithm used

    • 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.
      Returns:
      The name of the SecureRandom provider

    • setSecureRandomProvider

      public void setSecureRandomProvider(String secureRandomProvider)
      Set the secure random number generator provider name.
      Parameters:
      secureRandomProvider - The new secure random number generator provider name

    • getJaspicCallbackHandlerClass

      public String getJaspicCallbackHandlerClass()
      Return the JASPIC callback handler class name
      Returns:
      The name of the JASPIC callback handler

    • setJaspicCallbackHandlerClass

      public void setJaspicCallbackHandlerClass(String jaspicCallbackHandlerClass)
      Set the JASPIC callback handler class name
      Parameters:
      jaspicCallbackHandlerClass - The new JASPIC callback handler class name

    • isSendAuthInfoResponseHeaders

      public boolean isSendAuthInfoResponseHeaders()
      Returns the flag whether authentication information will be sent to a reverse proxy on a forwarded request.
      Returns:
      true if response headers shall be sent, false otherwise

    • setSendAuthInfoResponseHeaders

      public void setSendAuthInfoResponseHeaders(boolean sendAuthInfoResponseHeaders)
      Sets the flag whether authentication information will be sent to a reverse proxy on a forwarded request.
      Parameters:
      sendAuthInfoResponseHeaders - true if response headers shall be sent, false otherwise

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

    • allowCorsPreflightBypass

      protected boolean allowCorsPreflightBypass(Request request)

    • authenticate

      public boolean authenticate(Request request, HttpServletResponse httpResponse) throws IOException
      Description copied from interface: Authenticator
      Authenticate the user making this request, based on the login configuration of the Context with which this Authenticator is associated.
      Specified by:
      authenticate in interface Authenticator
      Parameters:
      request - Request we are processing
      httpResponse - Response we are populating
      Returns:
      true if any specified constraints have been satisfied, or false if one more constraints were not satisfied (in which case an authentication challenge will have been written to the response).
      Throws:
      IOException - if an input/output error occurs

    • doAuthenticate

      protected abstract boolean doAuthenticate(Request request, HttpServletResponse response) throws IOException
      Provided for subclasses to implement their specific authentication mechanism.
      Parameters:
      request - The request that triggered the authentication
      response - The response associated with the request
      Returns:
      true if the user was authenticated, otherwise false, in which case an authentication challenge will have been written to the response
      Throws:
      IOException - If an I/O problem occurred during the authentication process

    • isContinuationRequired

      protected boolean isContinuationRequired(Request request)
      Does this authenticator require that authenticate(Request, HttpServletResponse) is called to continue an authentication process that started in a previous request?
      Parameters:
      request - The request currently being processed
      Returns:
      true if authenticate() must be called, otherwise false

    • 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

    • checkForCachedAuthentication

      protected boolean checkForCachedAuthentication(Request request, HttpServletResponse response, boolean useSSO)
      Check to see if the user has already been authenticated earlier in the processing chain or if there is enough information available to authenticate the user without requiring further user interaction.
      Parameters:
      request - The current request
      response - The current response
      useSSO - Should information available from SSO be used to attempt to authenticate the current user?
      Returns:
      true if the user was authenticated via the cache, otherwise false

    • 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
      Returns:
      true if the reauthentication from SSL occurred

    • 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)

    • register

      protected void register(Request request, HttpServletResponse response, Principal principal, String authType, String username, String password, boolean alwaysUseSession, boolean cache)
      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)
      alwaysUseSession - Should a session always be used once a user is authenticated?
      cache - Should we cache authenticated Principals if the request is part of an HTTP session?

    • changeSessionID

      protected String changeSessionID(Request request, Session session)

    • 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()
      Return the authentication method, which is vendor-specific and not defined by HttpServletRequest.
      Returns:
      the authentication method, which is vendor-specific and not defined by HttpServletRequest.

    • 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 - No principal was authenticated with the specified credentials

    • logout

      public void logout(Request request)
      Specified by:
      logout in interface Authenticator

    • startInternal

      protected void startInternal() throws LifecycleException
      Description copied from class: ValveBase
      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
      Description copied from class: ValveBase
      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

    • isPreemptiveAuthPossible

      protected boolean isPreemptiveAuthPossible(Request request)
      Can the authenticator perform preemptive authentication for the given request?
      Parameters:
      request - The request to check for credentials
      Returns:
      true if preemptive authentication is possible, otherwise false

    • notify

      public void notify(String layer, String appContext)
      Specified by:
      notify in interface RegistrationListener