public abstract class

AbstractPreAuthenticatedProcessingFilter

extends GenericFilterBean
implements ApplicationEventPublisherAware
java.lang.Object
   ↳ org.springframework.web.filter.GenericFilterBean
     ↳ org.springframework.security.web.authentication.preauth.AbstractPreAuthenticatedProcessingFilter
Known Direct Subclasses

Class Overview

Base class for processing filters that handle pre-authenticated authentication requests, where it is assumed that the principal has already been authenticated by an external system.

The purpose is then only to extract the necessary information on the principal from the incoming request, rather than to authenticate them. External authentication systems may provide this information via request data such as headers or cookies which the pre-authentication system can extract. It is assumed that the external system is responsible for the accuracy of the data and preventing the submission of forged values. Subclasses must implement the getPreAuthenticatedPrincipal() and getPreAuthenticatedCredentials() methods. Subclasses of this filter are typically used in combination with a PreAuthenticatedAuthenticationProvider, which is used to load additional data for the user. This provider will reject null credentials, so the getPreAuthenticatedCredentials(HttpServletRequest) method should not return null for a valid principal.

If the security context already contains an Authentication object (either from a invocation of the filter or because of some other authentication mechanism), the filter will do nothing by default. You can force it to check for a change in the principal by setting the checkForPrincipalChanges property.

By default, the filter chain will proceed when an authentication attempt fails in order to allow other authentication mechanisms to process the request. To reject the credentials immediately, set the continueFilterChainOnUnsuccessfulAuthentication flag to false. The exception raised by the AuthenticationManager will the be re-thrown. Note that this will not affect cases where the principal returned by getPreAuthenticatedPrincipal(HttpServletRequest) is null, when the chain will still proceed as normal.

Summary

[Expand]
Inherited Fields
From class org.springframework.web.filter.GenericFilterBean
Public Constructors
AbstractPreAuthenticatedProcessingFilter()
Public Methods
void afterPropertiesSet()
Check whether all required properties have been set.
void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
Try to authenticate a pre-authenticated user with Spring Security if the user has not yet been authenticated.
void setApplicationEventPublisher(ApplicationEventPublisher anApplicationEventPublisher)
void setAuthenticationDetailsSource(AuthenticationDetailsSource<HttpServletRequest, ?> authenticationDetailsSource)
void setAuthenticationManager(AuthenticationManager authenticationManager)
void setCheckForPrincipalChanges(boolean checkForPrincipalChanges)
If set, the pre-authenticated principal will be checked on each request and compared against the name of the current Authentication object.
void setContinueFilterChainOnUnsuccessfulAuthentication(boolean shouldContinue)
If set to true, any AuthenticationException raised by the AuthenticationManager will be swallowed, and the request will be allowed to proceed, potentially using alternative authentication mechanisms.
void setInvalidateSessionOnPrincipalChange(boolean invalidateSessionOnPrincipalChange)
If checkForPrincipalChanges is set, and a change of principal is detected, determines whether any existing session should be invalidated before proceeding to authenticate the new principal.
Protected Methods
AuthenticationDetailsSource<HttpServletRequest, ?> getAuthenticationDetailsSource()
abstract Object getPreAuthenticatedCredentials(HttpServletRequest request)
Override to extract the credentials (if applicable) from the current request.
abstract Object getPreAuthenticatedPrincipal(HttpServletRequest request)
Override to extract the principal information from the current request
void successfulAuthentication(HttpServletRequest request, HttpServletResponse response, Authentication authResult)
Puts the Authentication instance returned by the authentication manager into the secure context.
void unsuccessfulAuthentication(HttpServletRequest request, HttpServletResponse response, AuthenticationException failed)
Ensures the authentication object in the secure context is set to null when authentication fails.
[Expand]
Inherited Methods
From class org.springframework.web.filter.GenericFilterBean
From class java.lang.Object
From interface javax.servlet.Filter
From interface org.springframework.beans.factory.BeanNameAware
From interface org.springframework.beans.factory.DisposableBean
From interface org.springframework.beans.factory.InitializingBean
From interface org.springframework.context.ApplicationEventPublisherAware
From interface org.springframework.web.context.ServletContextAware

Public Constructors

public AbstractPreAuthenticatedProcessingFilter ()

Public Methods

public void afterPropertiesSet ()

Check whether all required properties have been set.

public void doFilter (ServletRequest request, ServletResponse response, FilterChain chain)

Try to authenticate a pre-authenticated user with Spring Security if the user has not yet been authenticated.

Throws
IOException
ServletException

public void setApplicationEventPublisher (ApplicationEventPublisher anApplicationEventPublisher)

Parameters
anApplicationEventPublisher The ApplicationEventPublisher to use

public void setAuthenticationDetailsSource (AuthenticationDetailsSource<HttpServletRequest, ?> authenticationDetailsSource)

Parameters
authenticationDetailsSource The AuthenticationDetailsSource to use

public void setAuthenticationManager (AuthenticationManager authenticationManager)

Parameters
authenticationManager The AuthenticationManager to use

public void setCheckForPrincipalChanges (boolean checkForPrincipalChanges)

If set, the pre-authenticated principal will be checked on each request and compared against the name of the current Authentication object. If a change is detected, the user will be reauthenticated.

public void setContinueFilterChainOnUnsuccessfulAuthentication (boolean shouldContinue)

If set to true, any AuthenticationException raised by the AuthenticationManager will be swallowed, and the request will be allowed to proceed, potentially using alternative authentication mechanisms. If false (the default), authentication failure will result in an immediate exception.

Parameters
shouldContinue set to true to allow the request to proceed after a failed authentication.

public void setInvalidateSessionOnPrincipalChange (boolean invalidateSessionOnPrincipalChange)

If checkForPrincipalChanges is set, and a change of principal is detected, determines whether any existing session should be invalidated before proceeding to authenticate the new principal.

Parameters
invalidateSessionOnPrincipalChange false to retain the existing session. Defaults to true.

Protected Methods

protected AuthenticationDetailsSource<HttpServletRequest, ?> getAuthenticationDetailsSource ()

protected abstract Object getPreAuthenticatedCredentials (HttpServletRequest request)

Override to extract the credentials (if applicable) from the current request. Should not return null for a valid principal, though some implementations may return a dummy value.

protected abstract Object getPreAuthenticatedPrincipal (HttpServletRequest request)

Override to extract the principal information from the current request

protected void successfulAuthentication (HttpServletRequest request, HttpServletResponse response, Authentication authResult)

Puts the Authentication instance returned by the authentication manager into the secure context.

protected void unsuccessfulAuthentication (HttpServletRequest request, HttpServletResponse response, AuthenticationException failed)

Ensures the authentication object in the secure context is set to null when authentication fails.

Caches the failure exception as a request attribute