[[core-web-filters]]
== Core Security Filters
There are some key filters which will always be used in a web application which uses Spring Security, so we'll look at these and their supporting classes and interfaces first.
We won't cover every feature, so be sure to look at the Javadoc for them if you want to get the complete picture.


[[access-denied-handler]]
=== AccessDeniedHandler
What happens if a user is already authenticated and they try to access a protected resource? In normal usage, this shouldn't happen because the application workflow should be restricted to operations to which a user has access.
For example, an HTML link to an administration page might be hidden from users who do not have an admin role.
You can't rely on hiding links for security though, as there's always a possibility that a user will just enter the URL directly in an attempt to bypass the restrictions.
Or they might modify a RESTful URL to change some of the argument values.
Your application must be protected against these scenarios or it will definitely be insecure.
You will typically use simple web layer security to apply constraints to basic URLs and use more specific method-based security on your service layer interfaces to really nail down what is permissible.

If an `AccessDeniedException` is thrown and a user has already been authenticated, then this means that an operation has been attempted for which they don't have enough permissions.
In this case, `ExceptionTranslationFilter` will invoke a second strategy, the `AccessDeniedHandler`.
By default, an `AccessDeniedHandlerImpl` is used, which just sends a 403 (Forbidden) response to the client.
Alternatively you can configure an instance explicitly (as in the above example) and set an error page URL which it will forwards the request to footnote:[
We use a forward so that the SecurityContextHolder still contains details of the principal, which may be useful for displaying to the user.
In old releases of Spring Security we relied upon the servlet container to handle a 403 error message, which lacked this useful contextual information.
].
This can be a simple "access denied" page, such as a JSP, or it could be a more complex handler such as an MVC controller.
And of course, you can implement the interface yourself and use your own implementation.

It's also possible to supply a custom `AccessDeniedHandler` when you're using the namespace to configure your application.
See <<nsa-access-denied-handler,the namespace appendix>> for more details.


[[request-caching]]
=== SavedRequest s and the RequestCache Interface
Another responsibility of `ExceptionTranslationFilter` responsibilities is to save the current request before invoking the `AuthenticationEntryPoint`.
This allows the request to be restored after the user has authenticated (see previous overview of <<tech-intro-web-authentication,web authentication>>).
A typical example would be where the user logs in with a form, and is then redirected to the original URL by the default `SavedRequestAwareAuthenticationSuccessHandler` (see <<form-login-flow-handling,below>>).

The `RequestCache` encapsulates the functionality required for storing and retrieving `HttpServletRequest` instances.
By default the `HttpSessionRequestCache` is used, which stores the request in the `HttpSession`.
The `RequestCacheFilter` has the job of actually restoring the saved request from the cache when the user is redirected to the original URL.

Under normal circumstances, you shouldn't need to modify any of this functionality, but the saved-request handling is a "best-effort" approach and there may be situations which the default configuration isn't able to handle.
The use of these interfaces makes it fully pluggable from Spring Security 3.0 onwards.


[[security-context-persistence-filter]]
=== SecurityContextPersistenceFilter
We covered the purpose of this all-important filter in the <<tech-intro-sec-context-persistence,Technical Overview>> chapter so you might want to re-read that section at this point.
Let's first take a look at how you would configure it for use with a `FilterChainProxy`.
A basic configuration only requires the bean itself

[source,xml]
----
<bean id="securityContextPersistenceFilter"
class="org.springframework.security.web.context.SecurityContextPersistenceFilter"/>
----

As we saw previously, this filter has two main tasks.
It is responsible for storage of the `SecurityContext` contents between HTTP requests and for clearing the `SecurityContextHolder` when a request is completed.
Clearing the `ThreadLocal` in which the context is stored is essential, as it might otherwise be possible for a thread to be replaced into the servlet container's thread pool, with the security context for a particular user still attached.
This thread might then be used at a later stage, performing operations with the wrong credentials.


[[security-context-repository]]
==== SecurityContextRepository
From Spring Security 3.0, the job of loading and storing the security context is now delegated to a separate strategy interface:

[source,java]
----
public interface SecurityContextRepository {

SecurityContext loadContext(HttpRequestResponseHolder requestResponseHolder);

void saveContext(SecurityContext context, HttpServletRequest request,
		HttpServletResponse response);
}
----

The `HttpRequestResponseHolder` is simply a container for the incoming request and response objects, allowing the implementation to replace these with wrapper classes.
The returned contents will be passed to the filter chain.

The default implementation is `HttpSessionSecurityContextRepository`, which stores the security context as an `HttpSession` attribute footnote:[In Spring Security 2.0 and earlier, this filter was called `HttpSessionContextIntegrationFilter` and performed all the work of storing the context was performed by the filter itself.
If you were familiar with this class, then most of the configuration options which were available can now be found on `HttpSessionSecurityContextRepository`.].
The most important configuration parameter for this implementation is the `allowSessionCreation` property, which defaults to `true`, thus allowing the class to create a session if it needs one to store the security context for an authenticated user (it won't create one unless authentication has taken place and the contents of the security context have changed).
If you don't want a session to be created, then you can set this property to `false`:

[source,xml]
----
<bean id="securityContextPersistenceFilter"
	class="org.springframework.security.web.context.SecurityContextPersistenceFilter">
<property name='securityContextRepository'>
	<bean class='org.springframework.security.web.context.HttpSessionSecurityContextRepository'>
	<property name='allowSessionCreation' value='false' />
	</bean>
</property>
</bean>
----

Alternatively you could provide an instance of `NullSecurityContextRepository`, a https://en.wikipedia.org/wiki/Null_Object_pattern[null object] implementation, which will prevent the security context from being stored, even if a session has already been created during the request.


[[form-login-filter]]
=== UsernamePasswordAuthenticationFilter
We've now seen the three main filters which are always present in a Spring Security web configuration.
These are also the three which are automatically created by the namespace `<http>` element and cannot be substituted with alternatives.
The only thing that's missing now is an actual authentication mechanism, something that will allow a user to authenticate.
This filter is the most commonly used authentication filter and the one that is most often customized footnote:[For historical reasons, prior to Spring Security 3.0, this filter was called `AuthenticationProcessingFilter` and the entry point was called `AuthenticationProcessingFilterEntryPoint`.
Since the framework now supports many different forms of authentication, they have both been given more specific names in 3.0.].
It also provides the implementation used by the `<form-login>` element from the namespace.
There are three stages required to configure it.

* Configure a `LoginUrlAuthenticationEntryPoint` with the URL of the login page, just as we did above, and set it on the `ExceptionTranslationFilter`.
* Implement the login page (using a JSP or MVC controller).
* Configure an instance of `UsernamePasswordAuthenticationFilter` in the application context
* Add the filter bean to your filter chain proxy (making sure you pay attention to the order).

The login form simply contains `username` and `password` input fields, and posts to the URL that is monitored by the filter (by default this is `/login`).
The basic filter configuration looks something like this:

[source,xml]
----
<bean id="authenticationFilter" class=
"org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter">
<property name="authenticationManager" ref="authenticationManager"/>
</bean>
----

[[form-login-flow-handling]]
==== Application Flow on Authentication Success and Failure
The filter calls the configured `AuthenticationManager` to process each authentication request.
The destination following a successful authentication or an authentication failure is controlled by the `AuthenticationSuccessHandler` and `AuthenticationFailureHandler` strategy interfaces, respectively.
The filter has properties which allow you to set these so you can customize the behaviour completely footnote:[In versions prior to 3.0, the application flow at this point had evolved to a stage was controlled by a mix of properties on this class and strategy plugins.
The decision was made for 3.0 to refactor the code to make these two strategies entirely responsible.].
Some standard implementations are supplied such as `SimpleUrlAuthenticationSuccessHandler`, `SavedRequestAwareAuthenticationSuccessHandler`, `SimpleUrlAuthenticationFailureHandler`, `ExceptionMappingAuthenticationFailureHandler` and `DelegatingAuthenticationFailureHandler`.
Have a look at the Javadoc for these classes and also for `AbstractAuthenticationProcessingFilter` to get an overview of how they work and the supported features.

If authentication is successful, the resulting `Authentication` object will be placed into the `SecurityContextHolder`.
The configured `AuthenticationSuccessHandler` will then be called to either redirect or forward the user to the appropriate destination.
By default a `SavedRequestAwareAuthenticationSuccessHandler` is used, which means that the user will be redirected to the original destination they requested before they were asked to login.

[NOTE]
====
The `ExceptionTranslationFilter` caches the original request a user makes.
When the user authenticates, the request handler makes use of this cached request to obtain the original URL and redirect to it.
The original request is then rebuilt and used as an alternative.
====

If authentication fails, the configured `AuthenticationFailureHandler` will be invoked.
