Package org.springframework.security.web.authentication.preauth

# Class AbstractPreAuthenticatedProcessingFilter

java.lang.Object
org.springframework.web.filter.GenericFilterBean
org.springframework.security.web.authentication.preauth.AbstractPreAuthenticatedProcessingFilter

All Implemented Interfaces:
  `jakarta.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.core.env.EnvironmentCapable`, `org.springframework.web.context.ServletContextAware`

Direct Known Subclasses:
  `J2eePreAuthenticatedProcessingFilter`, `RequestAttributeAuthenticationFilter`, `RequestHeaderAuthenticationFilter`, `WebSpherePreAuthenticatedProcessingFilter`, `X509AuthenticationFilter`

public abstract class AbstractPreAuthenticatedProcessingFilter extends org.springframework.web.filter.GenericFilterBean implements org.springframework.context.ApplicationEventPublisherAware
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(jakarta.servlet.http.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(jakarta.servlet.http.HttpServletRequest)` is null, when the chain will still proceed as normal.

The filter saves the `SecurityContext` using the configured `SecurityContextRepository`, which can be set via `setSecurityContextRepository(org.springframework.security.web.context.SecurityContextRepository)`.

Since:
  2.0

## Field Summary

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

`logger`

## Constructor Summary

Constructors
Constructor
Description
`AbstractPreAuthenticatedProcessingFilter()`

## Method Summary

Modifier and Type
Method
Description
`void`
`afterPropertiesSet()`
Check whether all required properties have been set.
`void`
`doFilter(jakarta.servlet.ServletRequest request, jakarta.servlet.ServletResponse response, jakarta.servlet.FilterChain chain)`
Try to authenticate a pre-authenticated user with Spring Security if the user has not yet been authenticated.
`protected org.springframework.security.authentication.AuthenticationDetailsSource<jakarta.servlet.http.HttpServletRequest,?>`
`getAuthenticationDetailsSource()`
`protected abstract Object`
`getPreAuthenticatedCredentials(jakarta.servlet.http.HttpServletRequest request)`
Override to extract the credentials (if applicable) from the current request.
`protected abstract Object`
`getPreAuthenticatedPrincipal(jakarta.servlet.http.HttpServletRequest request)`
Override to extract the principal information from the current request
`protected boolean`
`principalChanged(jakarta.servlet.http.HttpServletRequest request, org.springframework.security.core.Authentication currentAuthentication)`
Determines if the current principal has changed.
`void`
`setApplicationEventPublisher(org.springframework.context.ApplicationEventPublisher anApplicationEventPublisher)`
`void`
`setAuthenticationDetailsSource(org.springframework.security.authentication.AuthenticationDetailsSource<jakarta.servlet.http.HttpServletRequest,?> authenticationDetailsSource)`
`void`
`setAuthenticationFailureHandler(AuthenticationFailureHandler authenticationFailureHandler)`
Sets the strategy used to handle a failed authentication.
`void`
`setAuthenticationManager(org.springframework.security.authentication.AuthenticationManager authenticationManager)`
`void`
`setAuthenticationSuccessHandler(AuthenticationSuccessHandler authenticationSuccessHandler)`
Sets the strategy used to handle a successful authentication.
`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` (the default), 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.
`void`
`setRequiresAuthenticationRequestMatcher(RequestMatcher requiresAuthenticationRequestMatcher)`
Sets the request matcher to check whether to proceed the request further.
`void`
`setSecurityContextHolderStrategy(org.springframework.security.core.context.SecurityContextHolderStrategy securityContextHolderStrategy)`
Sets the `SecurityContextHolderStrategy` to use.
`void`
`setSecurityContextRepository(SecurityContextRepository securityContextRepository)`
Sets the `SecurityContextRepository` to save the `SecurityContext` on authentication success.
`protected void`
`successfulAuthentication(jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response, org.springframework.security.core.Authentication authResult)`
Puts the `Authentication` instance returned by the authentication manager into the secure context.
`protected void`
`unsuccessfulAuthentication(jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response, org.springframework.security.core.AuthenticationException failed)`
Ensures the authentication object in the secure context is set to null when authentication fails.

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

## Constructor Details

### AbstractPreAuthenticatedProcessingFilter

public AbstractPreAuthenticatedProcessingFilter()

## Method Details

### afterPropertiesSet

public void afterPropertiesSet()
Check whether all required properties have been set.

Specified by:
  `afterPropertiesSet` in interface `org.springframework.beans.factory.InitializingBean`
Overrides:
  `afterPropertiesSet` in class `org.springframework.web.filter.GenericFilterBean`

### doFilter

public void doFilter(jakarta.servlet.ServletRequest request, jakarta.servlet.ServletResponse response, jakarta.servlet.FilterChain chain) throws IOException, jakarta.servlet.ServletException
Try to authenticate a pre-authenticated user with Spring Security if the user has not yet been authenticated.

Specified by:
  `doFilter` in interface `jakarta.servlet.Filter`
Throws:
  `IOException`
  `jakarta.servlet.ServletException`

### principalChanged

protected boolean principalChanged(jakarta.servlet.http.HttpServletRequest request, org.springframework.security.core.Authentication currentAuthentication)
Determines if the current principal has changed. The default implementation tries

- If the `getPreAuthenticatedPrincipal(HttpServletRequest)` is a String, the `Principal.getName()` is compared against the pre authenticated principal
- Otherwise, the `getPreAuthenticatedPrincipal(HttpServletRequest)` is compared against the `Authentication.getPrincipal()`

Subclasses can override this method to determine when a principal has changed.

Parameters:
  `request` -
  `currentAuthentication` -
Returns:
  true if the principal has changed, else false

### successfulAuthentication

protected void successfulAuthentication(jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response, org.springframework.security.core.Authentication authResult) throws IOException, jakarta.servlet.ServletException
Puts the `Authentication` instance returned by the authentication manager into the secure context.

Throws:
  `IOException`
  `jakarta.servlet.ServletException`

### unsuccessfulAuthentication

protected void unsuccessfulAuthentication(jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response, org.springframework.security.core.AuthenticationException failed) throws IOException, jakarta.servlet.ServletException
Ensures the authentication object in the secure context is set to null when authentication fails.

Caches the failure exception as a request attribute

Throws:
  `IOException`
  `jakarta.servlet.ServletException`

### setApplicationEventPublisher

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

Specified by:
  `setApplicationEventPublisher` in interface `org.springframework.context.ApplicationEventPublisherAware`
Parameters:
  `anApplicationEventPublisher` - The ApplicationEventPublisher to use

### setSecurityContextRepository

public void setSecurityContextRepository(SecurityContextRepository securityContextRepository)
Sets the `SecurityContextRepository` to save the `SecurityContext` on authentication success. The default action is to save the `SecurityContext` in `HttpSession` using `HttpSessionSecurityContextRepository`.

Parameters:
  `securityContextRepository` - the `SecurityContextRepository` to use. Cannot be null.

### setAuthenticationDetailsSource

public void setAuthenticationDetailsSource(org.springframework.security.authentication.AuthenticationDetailsSource<jakarta.servlet.http.HttpServletRequest,?> authenticationDetailsSource)

Parameters:
  `authenticationDetailsSource` - The AuthenticationDetailsSource to use

### getAuthenticationDetailsSource

protected org.springframework.security.authentication.AuthenticationDetailsSource<jakarta.servlet.http.HttpServletRequest,?> getAuthenticationDetailsSource()

### setAuthenticationManager

public void setAuthenticationManager(org.springframework.security.authentication.AuthenticationManager authenticationManager)

Parameters:
  `authenticationManager` - The AuthenticationManager to use

### setContinueFilterChainOnUnsuccessfulAuthentication

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

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

### setCheckForPrincipalChanges

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. A check to determine if `Authentication.getPrincipal()` is equal to the principal will also be performed. If a change is detected, the user will be reauthenticated.

Parameters:
  `checkForPrincipalChanges` -

### setInvalidateSessionOnPrincipalChange

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

### setAuthenticationSuccessHandler

public void setAuthenticationSuccessHandler(AuthenticationSuccessHandler authenticationSuccessHandler)
Sets the strategy used to handle a successful authentication.

### setAuthenticationFailureHandler

public void setAuthenticationFailureHandler(AuthenticationFailureHandler authenticationFailureHandler)
Sets the strategy used to handle a failed authentication.

### setRequiresAuthenticationRequestMatcher

public void setRequiresAuthenticationRequestMatcher(RequestMatcher requiresAuthenticationRequestMatcher)
Sets the request matcher to check whether to proceed the request further.

### setSecurityContextHolderStrategy

public void setSecurityContextHolderStrategy(org.springframework.security.core.context.SecurityContextHolderStrategy securityContextHolderStrategy)
Sets the `SecurityContextHolderStrategy` to use. The default action is to use the `SecurityContextHolderStrategy` stored in `SecurityContextHolder`.

Since:
  5.8

### getPreAuthenticatedPrincipal

protected abstract Object getPreAuthenticatedPrincipal(jakarta.servlet.http.HttpServletRequest request)
Override to extract the principal information from the current request

### getPreAuthenticatedCredentials

protected abstract Object getPreAuthenticatedCredentials(jakarta.servlet.http.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.