FormAuthenticator (Apache Tomcat 7.0.81 API Documentation)

org.apache.catalina.authenticator

## Class FormAuthenticator

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

- All Implemented Interfaces:
    MBeanRegistration, Authenticator, Contained, Lifecycle, Valve

      public class FormAuthenticator
      extends AuthenticatorBase

  An Authenticator and Valve implementation of FORM BASED Authentication, as described in the Servlet API Specification, Version 2.2.
  Author:
    Craig R. McClanahan, Remy Maucherat

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from interface org.apache.catalina.Lifecycle

      `Lifecycle.SingleUse`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected String` | `characterEncoding` Character encoding to use to read the username and password parameters from the request.
    `protected static String` | `info` Descriptive information about this implementation.
    `protected String` | `landingPage` Landing page to use if a user tries to access the login page directly or if the session times out during login.

    - ### Fields inherited from class org.apache.catalina.authenticator.AuthenticatorBase

      `alwaysUseSession, AUTH_HEADER_NAME, cache, changeSessionIdOnAuthentication, context, disableProxyCaching, REALM_NAME, securePagesWithPragma, secureRandomAlgorithm, secureRandomClass, secureRandomProvider, sessionIdGenerator, sm, sso`

    - ### 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
    `FormAuthenticator()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `authenticate(Request request, HttpServletResponse response, LoginConfig config)` Authenticate the user making this request, based on the specified login configuration.
    `protected void` | `forwardToErrorPage(Request request, HttpServletResponse response, LoginConfig config)` Called to forward to the error page
    `protected void` | `forwardToLoginPage(Request request, HttpServletResponse response, LoginConfig config)` Called to forward to the login page
    `protected String` | `getAuthMethod()`
    `String` | `getCharacterEncoding()` Return the character encoding to use to read the username and password.
    `String` | `getInfo()` Return descriptive information about this Valve implementation.
    `String` | `getLandingPage()` Return the landing page to use when FORM auth is mis-used.
    `protected boolean` | `matchRequest(Request request)` Does this request match the saved one (so that it must be the redirect we signaled after successful authentication?
    `protected boolean` | `restoreRequest(Request request, Session session)` Restore the original request from information stored in our session.
    `protected String` | `savedRequestURL(Session session)` Return the request URI (with the corresponding query string, if any) from the saved request so that we can redirect to it.
    `protected void` | `saveRequest(Request request, Session session)` Save the original request information into our session.
    `void` | `setCharacterEncoding(String encoding)` Set the character encoding to be used to read the username and password.
    `void` | `setLandingPage(String landingPage)` Set the landing page to use when the FORM auth is mis-used.

    - ### Methods inherited from class org.apache.catalina.authenticator.AuthenticatorBase

      `associate, authenticate, checkForCachedAuthentication, doLogin, getAlwaysUseSession, getCache, getChangeSessionIdOnAuthentication, getContainer, getDisableProxyCaching, getRequestCertificates, getSecurePagesWithPragma, getSecureRandomAlgorithm, getSecureRandomClass, getSecureRandomProvider, invoke, login, logout, reauthenticateFromSSO, register, setAlwaysUseSession, setCache, setChangeSessionIdOnAuthentication, setContainer, setDisableProxyCaching, setSecurePagesWithPragma, setSecureRandomAlgorithm, setSecureRandomClass, setSecureRandomProvider, startInternal, 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

    - #### info

          protected static final String info

      Descriptive information about this implementation.
      See Also:
        Constant Field Values

    - #### characterEncoding

          protected String characterEncoding

      Character encoding to use to read the username and password parameters from the request. If not set, the encoding of the request body will be used.

    - #### landingPage

          protected String landingPage

      Landing page to use if a user tries to access the login page directly or if the session times out during login. If not set, error responses will be sent instead.

  - ### Constructor Detail

    - #### FormAuthenticator

          public FormAuthenticator()

  - ### Method Detail

    - #### getInfo

          public String getInfo()

      Return descriptive information about this Valve implementation.
      Specified by:
        `getInfo` in interface `Valve`
      Overrides:
        `getInfo` in class `AuthenticatorBase`

    - #### getCharacterEncoding

          public String getCharacterEncoding()

      Return the character encoding to use to read the username and password.

    - #### setCharacterEncoding

          public void setCharacterEncoding(String encoding)

      Set the character encoding to be used to read the username and password.

    - #### getLandingPage

          public String getLandingPage()

      Return the landing page to use when FORM auth is mis-used.

    - #### setLandingPage

          public void setLandingPage(String landingPage)

      Set the landing page to use when the FORM auth is mis-used.

    - #### authenticate

          public 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`
      Specified by:
        `authenticate` in class `AuthenticatorBase`
      Parameters:
        `request` - Request we are processing
        `response` - Response we are creating
        `config` - Login configuration describing how authentication should be performed
      Throws:
        `IOException` - if an input/output error occurs

    - #### getAuthMethod

          protected String getAuthMethod()

      Specified by:
        `getAuthMethod` in class `AuthenticatorBase`

    - #### forwardToLoginPage

          protected void forwardToLoginPage(Request request,
                                HttpServletResponse response,
                                LoginConfig config)
                                     throws IOException

      Called to forward to the login page
      Parameters:
        `request` - Request we are processing
        `response` - Response we are populating
        `config` - Login configuration describing how authentication should be performed
      Throws:
        `IOException` - If the forward to the login page fails and the call to `HttpServletResponse.sendError(int, String)` throws an `IOException`

    - #### forwardToErrorPage

          protected void forwardToErrorPage(Request request,
                                HttpServletResponse response,
                                LoginConfig config)
                                     throws IOException

      Called to forward to the error page
      Parameters:
        `request` - Request we are processing
        `response` - Response we are populating
        `config` - Login configuration describing how authentication should be performed
      Throws:
        `IOException` - If the forward to the error page fails and the call to `HttpServletResponse.sendError(int, String)` throws an `IOException`

    - #### matchRequest

          protected boolean matchRequest(Request request)

      Does this request match the saved one (so that it must be the redirect we signaled after successful authentication?
      Parameters:
        `request` - The request to be verified

    - #### restoreRequest

          protected boolean restoreRequest(Request request,
                               Session session)
                                    throws IOException

      Restore the original request from information stored in our session. If the original request is no longer present (because the session timed out), return `false`; otherwise, return `true`.
      Parameters:
        `request` - The request to be restored
        `session` - The session containing the saved information
      Throws:
        `IOException`

    - #### saveRequest

          protected void saveRequest(Request request,
                         Session session)
                              throws IOException

      Save the original request information into our session.
      Parameters:
        `request` - The request to be saved
        `session` - The session to contain the saved information
      Throws:
        `IOException`

    - #### savedRequestURL

          protected String savedRequestURL(Session session)

      Return the request URI (with the corresponding query string, if any) from the saved request so that we can redirect to it.
      Parameters:
        `session` - Our current session

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