org.springframework.security.web.authentication

Class AbstractAuthenticationProcessingFilter

java.lang.Object

org.springframework.web.filter.GenericFilterBean

org.springframework.security.web.authentication.AbstractAuthenticationProcessingFilter

All Implemented Interfaces:

javax.servlet.Filter, org.springframework.beans.factory.Aware, org.springframework.beans.factory.BeanNameAware, org.springframework.beans.factory.DisposableBean, org.springframework.beans.factory.InitializingBean, org.springframework.context.ApplicationEventPublisherAware, org.springframework.context.EnvironmentAware, org.springframework.context.MessageSourceAware, org.springframework.core.env.EnvironmentCapable, org.springframework.web.context.ServletContextAware

Direct Known Subclasses:

CasAuthenticationFilter, OAuth2LoginAuthenticationFilter, OpenIDAuthenticationFilter, UsernamePasswordAuthenticationFilter

public abstract class AbstractAuthenticationProcessingFilter
extends org.springframework.web.filter.GenericFilterBean
implements org.springframework.context.ApplicationEventPublisherAware, org.springframework.context.MessageSourceAware

Abstract processor of browser-based HTTP-based authentication requests.

Authentication Process

The filter requires that you set the authenticationManager property. An AuthenticationManager is required to process the authentication request tokens created by implementing classes.

This filter will intercept a request and attempt to perform authentication from that request if the request matches the setRequiresAuthenticationRequestMatcher(RequestMatcher).

Authentication is performed by the attemptAuthentication method, which must be implemented by subclasses.

Authentication Success

If authentication is successful, the resulting Authentication object will be placed into the SecurityContext for the current thread, which is guaranteed to have already been created by an earlier filter.

The configured AuthenticationSuccessHandler will then be called to take the redirect to the appropriate destination after a successful login. The default behaviour is implemented in a SavedRequestAwareAuthenticationSuccessHandler which will make use of any DefaultSavedRequest set by the ExceptionTranslationFilter and redirect the user to the URL contained therein. Otherwise it will redirect to the webapp root "/". You can customize this behaviour by injecting a differently configured instance of this class, or by using a different implementation.

See the successfulAuthentication(HttpServletRequest, HttpServletResponse, FilterChain, Authentication) method for more information.

Authentication Failure

If authentication fails, it will delegate to the configured AuthenticationFailureHandler to allow the failure information to be conveyed to the client. The default implementation is SimpleUrlAuthenticationFailureHandler , which sends a 401 error code to the client. It may also be configured with a failure URL as an alternative. Again you can inject whatever behaviour you require here.

Event Publication

If authentication is successful, an InteractiveAuthenticationSuccessEvent will be published via the application context. No events will be published if authentication was unsuccessful, because this would generally be recorded via an AuthenticationManager-specific application event.

Session Authentication

The class has an optional SessionAuthenticationStrategy which will be invoked immediately after a successful call to attemptAuthentication(). Different implementations can be injected to enable things like session-fixation attack prevention or to control the number of simultaneous sessions a principal may have.

Field Summary

Fields

Modifier and Type	Field and Description
protected AuthenticationDetailsSource<javax.servlet.http.HttpServletRequest,?>	authenticationDetailsSource
protected org.springframework.context.ApplicationEventPublisher	eventPublisher
protected org.springframework.context.support.MessageSourceAccessor	messages

Fields inherited from class org.springframework.web.filter.GenericFilterBean

logger

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractAuthenticationProcessingFilter(RequestMatcher requiresAuthenticationRequestMatcher) Creates a new instance
protected	AbstractAuthenticationProcessingFilter(java.lang.String defaultFilterProcessesUrl)

Method Summary

Modifier and Type	Method and Description
void	afterPropertiesSet()
abstract Authentication	attemptAuthentication(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Performs actual authentication.
void	doFilter(javax.servlet.ServletRequest req, javax.servlet.ServletResponse res, javax.servlet.FilterChain chain) Invokes the requiresAuthentication method to determine whether the request is for authentication and should be handled by this filter.
protected boolean	getAllowSessionCreation()
protected AuthenticationManager	getAuthenticationManager()
protected AuthenticationFailureHandler	getFailureHandler()
RememberMeServices	getRememberMeServices()
protected AuthenticationSuccessHandler	getSuccessHandler()
protected boolean	requiresAuthentication(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Indicates whether this filter should attempt to process a login request for the current invocation.
void	setAllowSessionCreation(boolean allowSessionCreation)
void	setApplicationEventPublisher(org.springframework.context.ApplicationEventPublisher eventPublisher)
void	setAuthenticationDetailsSource(AuthenticationDetailsSource<javax.servlet.http.HttpServletRequest,?> authenticationDetailsSource)
void	setAuthenticationFailureHandler(AuthenticationFailureHandler failureHandler)
void	setAuthenticationManager(AuthenticationManager authenticationManager)
void	setAuthenticationSuccessHandler(AuthenticationSuccessHandler successHandler) Sets the strategy used to handle a successful authentication.
void	setContinueChainBeforeSuccessfulAuthentication(boolean continueChainBeforeSuccessfulAuthentication) Indicates if the filter chain should be continued prior to delegation to successfulAuthentication(HttpServletRequest, HttpServletResponse, FilterChain, Authentication) , which may be useful in certain environment (such as Tapestry applications).
void	setFilterProcessesUrl(java.lang.String filterProcessesUrl) Sets the URL that determines if authentication is required
void	setMessageSource(org.springframework.context.MessageSource messageSource)
void	setRememberMeServices(RememberMeServices rememberMeServices)
void	setRequiresAuthenticationRequestMatcher(RequestMatcher requestMatcher)
void	setSessionAuthenticationStrategy(SessionAuthenticationStrategy sessionStrategy) The session handling strategy which will be invoked immediately after an authentication request is successfully processed by the AuthenticationManager.
protected void	successfulAuthentication(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, javax.servlet.FilterChain chain, Authentication authResult) Default behaviour for successful authentication.
protected void	unsuccessfulAuthentication(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, AuthenticationException failed) Default behaviour for unsuccessful authentication.

Methods inherited from class org.springframework.web.filter.GenericFilterBean

addRequiredProperty, createEnvironment, destroy, getEnvironment, getFilterConfig, getFilterName, getServletContext, init, initBeanWrapper, initFilterBean, setBeanName, setEnvironment, setServletContext

Methods inherited from class java.lang.Object

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

Field Detail

eventPublisher

protected org.springframework.context.ApplicationEventPublisher eventPublisher

authenticationDetailsSource

protected AuthenticationDetailsSource<javax.servlet.http.HttpServletRequest,?> authenticationDetailsSource

messages

protected org.springframework.context.support.MessageSourceAccessor messages

Constructor Detail

AbstractAuthenticationProcessingFilter

protected AbstractAuthenticationProcessingFilter(java.lang.String defaultFilterProcessesUrl)

Parameters:

defaultFilterProcessesUrl - the default value for filterProcessesUrl.

AbstractAuthenticationProcessingFilter

protected AbstractAuthenticationProcessingFilter(RequestMatcher requiresAuthenticationRequestMatcher)

Creates a new instance

Parameters:

requiresAuthenticationRequestMatcher - the RequestMatcher used to determine if authentication is required. Cannot be null.

Method Detail

afterPropertiesSet

public void afterPropertiesSet()

Specified by:

afterPropertiesSet in interface org.springframework.beans.factory.InitializingBean

Overrides:

afterPropertiesSet in class org.springframework.web.filter.GenericFilterBean

doFilter

public void doFilter(javax.servlet.ServletRequest req,
                     javax.servlet.ServletResponse res,
                     javax.servlet.FilterChain chain)
              throws java.io.IOException,
                     javax.servlet.ServletException

Invokes the requiresAuthentication method to determine whether the request is for authentication and should be handled by this filter. If it is an authentication request, the attemptAuthentication will be invoked to perform the authentication. There are then three possible outcomes:

1. An Authentication object is returned. The configured SessionAuthenticationStrategy will be invoked (to handle any session-related behaviour such as creating a new session to protect against session-fixation attacks) followed by the invocation of successfulAuthentication(HttpServletRequest, HttpServletResponse, FilterChain, Authentication) method
2. An AuthenticationException occurs during authentication. The unsuccessfulAuthentication method will be invoked
3. Null is returned, indicating that the authentication process is incomplete. The method will then return immediately, assuming that the subclass has done any necessary work (such as redirects) to continue the authentication process. The assumption is that a later request will be received by this method where the returned Authentication object is not null.

Specified by:

doFilter in interface javax.servlet.Filter

Throws:

java.io.IOException

javax.servlet.ServletException

requiresAuthentication

protected boolean requiresAuthentication(javax.servlet.http.HttpServletRequest request,
                                         javax.servlet.http.HttpServletResponse response)

Indicates whether this filter should attempt to process a login request for the current invocation.

It strips any parameters from the "path" section of the request URL (such as the jsessionid parameter in https://host/myapp/index.html;jsessionid=blah) before matching against the filterProcessesUrl property.

Subclasses may override for special requirements, such as Tapestry integration.

Returns:

true if the filter should attempt authentication, false otherwise.

attemptAuthentication

public abstract Authentication attemptAuthentication(javax.servlet.http.HttpServletRequest request,
                                                     javax.servlet.http.HttpServletResponse response)
                                              throws AuthenticationException,
                                                     java.io.IOException,
                                                     javax.servlet.ServletException

Performs actual authentication.

The implementation should do one of the following:

1. Return a populated authentication token for the authenticated user, indicating successful authentication
2. Return null, indicating that the authentication process is still in progress. Before returning, the implementation should perform any additional work required to complete the process.
3. Throw an AuthenticationException if the authentication process fails

Parameters:

request - from which to extract parameters and perform the authentication

response - the response, which may be needed if the implementation has to do a redirect as part of a multi-stage authentication process (such as OpenID).

Returns:

the authenticated user token, or null if authentication is incomplete.

Throws:

AuthenticationException - if authentication fails.

java.io.IOException

javax.servlet.ServletException

successfulAuthentication

protected void successfulAuthentication(javax.servlet.http.HttpServletRequest request,
                                        javax.servlet.http.HttpServletResponse response,
                                        javax.servlet.FilterChain chain,
                                        Authentication authResult)
                                 throws java.io.IOException,
                                        javax.servlet.ServletException

Default behaviour for successful authentication.

1. Sets the successful Authentication object on the SecurityContextHolder
2. Informs the configured RememberMeServices of the successful login
3. Fires an InteractiveAuthenticationSuccessEvent via the configured ApplicationEventPublisher
4. Delegates additional behaviour to the AuthenticationSuccessHandler.

Subclasses can override this method to continue the FilterChain after successful authentication.

Parameters:

request -

response -

chain -

authResult - the object returned from the attemptAuthentication method.

Throws:

java.io.IOException

javax.servlet.ServletException

unsuccessfulAuthentication

protected void unsuccessfulAuthentication(javax.servlet.http.HttpServletRequest request,
                                          javax.servlet.http.HttpServletResponse response,
                                          AuthenticationException failed)
                                   throws java.io.IOException,
                                          javax.servlet.ServletException

Default behaviour for unsuccessful authentication.

1. Clears the SecurityContextHolder
2. Stores the exception in the session (if it exists or allowSesssionCreation is set to true)
3. Informs the configured RememberMeServices of the failed login
4. Delegates additional behaviour to the AuthenticationFailureHandler.

Throws:

java.io.IOException

javax.servlet.ServletException

getAuthenticationManager

protected AuthenticationManager getAuthenticationManager()

setAuthenticationManager

public void setAuthenticationManager(AuthenticationManager authenticationManager)

setFilterProcessesUrl

public void setFilterProcessesUrl(java.lang.String filterProcessesUrl)

Sets the URL that determines if authentication is required

Parameters:

filterProcessesUrl -

setRequiresAuthenticationRequestMatcher

public final void setRequiresAuthenticationRequestMatcher(RequestMatcher requestMatcher)

getRememberMeServices

public RememberMeServices getRememberMeServices()

setRememberMeServices

public void setRememberMeServices(RememberMeServices rememberMeServices)

setContinueChainBeforeSuccessfulAuthentication

public void setContinueChainBeforeSuccessfulAuthentication(boolean continueChainBeforeSuccessfulAuthentication)

Indicates if the filter chain should be continued prior to delegation to successfulAuthentication(HttpServletRequest, HttpServletResponse, FilterChain, Authentication) , which may be useful in certain environment (such as Tapestry applications). Defaults to false.

setApplicationEventPublisher

public void setApplicationEventPublisher(org.springframework.context.ApplicationEventPublisher eventPublisher)

Specified by:

setApplicationEventPublisher in interface org.springframework.context.ApplicationEventPublisherAware

setAuthenticationDetailsSource

public void setAuthenticationDetailsSource(AuthenticationDetailsSource<javax.servlet.http.HttpServletRequest,?> authenticationDetailsSource)

setMessageSource

public void setMessageSource(org.springframework.context.MessageSource messageSource)

Specified by:

setMessageSource in interface org.springframework.context.MessageSourceAware

getAllowSessionCreation

protected boolean getAllowSessionCreation()

setAllowSessionCreation

public void setAllowSessionCreation(boolean allowSessionCreation)

setSessionAuthenticationStrategy

public void setSessionAuthenticationStrategy(SessionAuthenticationStrategy sessionStrategy)

The session handling strategy which will be invoked immediately after an authentication request is successfully processed by the AuthenticationManager. Used, for example, to handle changing of the session identifier to prevent session fixation attacks.

Parameters:

sessionStrategy - the implementation to use. If not set a null implementation is used.

setAuthenticationSuccessHandler

public void setAuthenticationSuccessHandler(AuthenticationSuccessHandler successHandler)

Sets the strategy used to handle a successful authentication. By default a SavedRequestAwareAuthenticationSuccessHandler is used.

setAuthenticationFailureHandler

public void setAuthenticationFailureHandler(AuthenticationFailureHandler failureHandler)

getSuccessHandler

protected AuthenticationSuccessHandler getSuccessHandler()

getFailureHandler

protected AuthenticationFailureHandler getFailureHandler()