FormAuthenticator (Apache Tomcat 10.1.55 API Documentation)
Description: declaration: package: org.apache.catalina.authenticator, class: FormAuthenticator

# 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:
  `RegistrationListener, MBeanRegistration, Authenticator, Contained, JmxEnabled, Lifecycle, Valve`

public class FormAuthenticator extends AuthenticatorBase
An Authenticator and Valve implementation of FORM BASED Authentication, as described in the Servlet API Specification.

- ## Nested Class Summary

  ### Nested classes/interfaces inherited from class AuthenticatorBase

  `AuthenticatorBase.AllowCorsPreflight, AuthenticatorBase.SsoReauthenticationMode`

  ### Nested classes/interfaces inherited from interface Lifecycle

  `Lifecycle.SingleUse`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected int`
  `authenticationSessionTimeout`
  If the authentication process creates a session, this is the maximum session timeout (in seconds) during the authentication process.
  `protected String`
  `characterEncoding`
  Character encoding to use to read the username and password parameters from the request.
  `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 AuthenticatorBase

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

  ### Fields inherited from class ValveBase

  `asyncSupported, container, containerLog, next`

  ### Fields inherited from interface 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
  Description
  `FormAuthenticator()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected boolean`
  `doAuthenticate(Request request, HttpServletResponse response)`
  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
  `int`
  `getAuthenticationSessionTimeout()`
  Returns the maximum session timeout to be used during authentication if the authentication process creates a session.
  `protected String`
  `getAuthMethod()`
  Return the authentication method, which is vendor-specific and not defined by HttpServletRequest.
  `String`
  `getCharacterEncoding()`
  Return the character encoding to use to read the username and password.
  `String`
  `getLandingPage()`
  Return the landing page to use when FORM auth is mis-used.
  `protected boolean`
  `isContinuationRequired(Request request)`
  Does this authenticator require that `AuthenticatorBase.authenticate(Request, HttpServletResponse)` is called to continue an authentication process that started in a previous request?
  `protected boolean`
  `matchRequest(Request request)`
  `protected boolean`
  `matchRequest(Request request, boolean strict)`
  Does this request match the saved one (so that it must be the redirect we signaled after successful authentication?)
  `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.
  `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`
  `setAuthenticationSessionTimeout(int authenticationSessionTimeout)`
  Configures the maximum session timeout to be used during authentication if the authentication process creates a 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 AuthenticatorBase

  `allowCorsPreflightBypass, associate, authenticate, changeSessionID, checkForCachedAuthentication, doLogin, getAllowCorsPreflight, getAlwaysUseSession, getCache, getChangeSessionIdOnAuthentication, getContainer, getDisableProxyCaching, getJaspicCallbackHandlerClass, getRealmName, getSecurePagesWithPragma, getSecureRandomAlgorithm, getSecureRandomClass, getSecureRandomProvider, getSsoReauthenticationMode, invoke, isPreemptiveAuthPossible, isSendAuthInfoResponseHeaders, login, logout, notify, reauthenticateFromSSO, register, setAllowCorsPreflight, setAlwaysUseSession, setCache, setChangeSessionIdOnAuthentication, setContainer, setDisableProxyCaching, setJaspicCallbackHandlerClass, setSecurePagesWithPragma, setSecureRandomAlgorithm, setSecureRandomClass, setSecureRandomProvider, setSendAuthInfoResponseHeaders, setSsoReauthenticationMode, startInternal, stopInternal`

  ### Methods inherited from class ValveBase

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

  ### Methods inherited from class LifecycleMBeanBase

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

  ### Methods inherited from class LifecycleBase

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

  ### Methods inherited from class Object

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

- ## Field Details

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

  - ### authenticationSessionTimeout

    protected int authenticationSessionTimeout
    If the authentication process creates a session, this is the maximum session timeout (in seconds) during the authentication process. Once authentication is complete, the default session timeout will apply. Sessions that exist before the authentication process starts will retain their original session timeout throughout.

- ## Constructor Details

  - ### FormAuthenticator

    public FormAuthenticator()

- ## Method Details

  - ### getCharacterEncoding

    public String getCharacterEncoding()
    Return the character encoding to use to read the username and password.
    Returns:
      The name of the character encoding

  - ### setCharacterEncoding

    public void setCharacterEncoding(String encoding)
    Set the character encoding to be used to read the username and password.
    Parameters:
      `encoding` - The name of the encoding to use

  - ### getLandingPage

    public String getLandingPage()
    Return the landing page to use when FORM auth is mis-used.
    Returns:
      The path to the landing page relative to the web application root

  - ### setLandingPage

    public void setLandingPage(String landingPage)
    Set the landing page to use when the FORM auth is mis-used.
    Parameters:
      `landingPage` - The path to the landing page relative to the web application root

  - ### getAuthenticationSessionTimeout

    public int getAuthenticationSessionTimeout()
    Returns the maximum session timeout to be used during authentication if the authentication process creates a session.
    Returns:
      the maximum session timeout to be used during authentication if the authentication process creates a session

  - ### setAuthenticationSessionTimeout

    public void setAuthenticationSessionTimeout(int authenticationSessionTimeout)
    Configures the maximum session timeout to be used during authentication if the authentication process creates a session.
    Parameters:
      `authenticationSessionTimeout` - The maximum session timeout to use during authentication if the authentication process creates a session

  - ### doAuthenticate

    protected boolean doAuthenticate(Request request, HttpServletResponse response) 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:
      `doAuthenticate` in class `AuthenticatorBase`
    Parameters:
      `request` - Request we are processing
      `response` - Response we are creating
    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 input/output error occurs

  - ### isContinuationRequired

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

  - ### getAuthMethod

    protected String getAuthMethod()
    Description copied from class: `AuthenticatorBase`
    Return the authentication method, which is vendor-specific and not defined by HttpServletRequest.
    Specified by:
      `getAuthMethod` in class `AuthenticatorBase`
    Returns:
      the authentication method, which is vendor-specific and not defined by HttpServletRequest.

  - ### register

    protected void register(Request request, HttpServletResponse response, Principal principal, String authType, String username, String password, boolean alwaysUseSession, boolean cache)
    Description copied from class: `AuthenticatorBase`
    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.
    Overrides:
      `register` in class `AuthenticatorBase`
    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?

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

  - ### matchRequest

    protected boolean matchRequest(Request request, boolean strict)
    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
      `strict` - `true` to check for a valid Principal and valid Session ID, `false` to only check for a valid saved request and matching URI
    Returns:
      `true` if the requests matched the saved one

  - ### 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
    Returns:
      `true` if the request was successfully restored
    Throws:
      `IOException` - if an IO error occurred during the process

  - ### 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` - if an IO error occurred during the process

  - ### 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
    Returns:
      the original request URL