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:

javax.management.MBeanRegistration, RegistrationListener, 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.

Author:

Craig R. McClanahan, Remy Maucherat

Nested Class Summary

Nested classes/interfaces inherited from class org.apache.catalina.authenticator.AuthenticatorBase

AuthenticatorBase.AllowCorsPreflight

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

Lifecycle.SingleUse

Field Summary

Fields

Modifier and Type	Field and Description
protected int	authenticationSessionTimeout If the authentication process creates a session, this is the maximum session timeout (in seconds) during the authentication process.
protected java.lang.String	characterEncoding Character encoding to use to read the username and password parameters from the request.
protected java.lang.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, jaspicCallbackHandlerClass, REALM_NAME, securePagesWithPragma, secureRandomAlgorithm, secureRandomClass, secureRandomProvider, sendAuthInfoResponseHeaders, 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

Modifier and Type	Method and 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 java.lang.String	getAuthMethod() Return the authentication method, which is vendor-specific and not defined by HttpServletRequest.
java.lang.String	getCharacterEncoding() Return the character encoding to use to read the user name and password.
java.lang.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) 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, java.security.Principal principal, java.lang.String authType, java.lang.String username, java.lang.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 java.lang.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(java.lang.String encoding) Set the character encoding to be used to read the user name and password.
void	setLandingPage(java.lang.String landingPage) Set the landing page to use when the FORM auth is mis-used.

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

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

Methods inherited from class org.apache.catalina.valves.ValveBase

backgroundProcess, 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, unregister

Methods inherited from class org.apache.catalina.util.LifecycleBase

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

Methods inherited from class java.lang.Object

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

Field Detail

characterEncoding

protected java.lang.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 java.lang.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 Detail

FormAuthenticator

public FormAuthenticator()

Method Detail

getCharacterEncoding

public java.lang.String getCharacterEncoding()

Return the character encoding to use to read the user name and password.

Returns:

The name of the character encoding

setCharacterEncoding

public void setCharacterEncoding(java.lang.String encoding)

Set the character encoding to be used to read the user name and password.

Parameters:

encoding - The name of the encoding to use

getLandingPage

public java.lang.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(java.lang.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 duriing authentication if the authentication process creates a session

doAuthenticate

protected boolean doAuthenticate(Request request,
                                 HttpServletResponse response)
                          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.

Specified by:

doAuthenticate in class AuthenticatorBase

Parameters:

request - Request we are processing

response - Response we are creating

Returns:

true if the the user was authenticated, otherwise false, in which case an authentication challenge will have been written to the response

Throws:

java.io.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 java.lang.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,
                        java.security.Principal principal,
                        java.lang.String authType,
                        java.lang.String username,
                        java.lang.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 java.io.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:

java.io.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 java.io.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:

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

Returns:

true if the requests matched the saved one

restoreRequest

protected boolean restoreRequest(Request request,
                                 Session session)
                          throws java.io.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:

java.io.IOException - if an IO error occurred during the process

saveRequest

protected void saveRequest(Request request,
                           Session session)
                    throws java.io.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:

java.io.IOException - if an IO error occurred during the process

savedRequestURL

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