diff --git a/docs/manual/src/docbook/core-filters.xml b/docs/manual/src/docbook/core-filters.xml index b74ab3f5e1..75d93f7095 100644 --- a/docs/manual/src/docbook/core-filters.xml +++ b/docs/manual/src/docbook/core-filters.xml @@ -2,13 +2,14 @@ xmlns:xlink="http://www.w3.org/1999/xlink"> 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 them - 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. + 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.
<classname>FilterSecurityInterceptor</classname> We've already seen FilterSecurityInterceptor briefly when - discussing access-control in general, and we've already used it with the namespace where the + discussing access-control in + general, and we've already used it with the namespace where the <intercept-url> elements are combined to configure it internally. Now we'll see how to explicitly configure it for use with a FilterChainProxy, along with its companion filter @@ -30,7 +31,8 @@ AuthenticationManager and an AccessDecisionManager. It is also supplied with configuration attributes that apply to different HTTP URL requests. Refer back to the original discussion on these in the technical introduction. + xlink:href="#tech-intro-config-attributes">the original discussion on these + in the technical introduction. The FilterSecurityInterceptor can be configured with configuration attributes in two ways. The first, which is shown above, is using the <filter-security-metadata-source> namespace element. This @@ -155,159 +157,147 @@ 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 - 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. + forwards the request to 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 - the namespace appendix for more details. + namespace to configure your application. See the namespace appendix for more + details.
-
- <classname>SecurityContextPersistenceFilter</classname> - We covered the purpose of this all-important filter in 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 +
+ <classname>SecurityContextPersistenceFilter</classname> + We covered the purpose of this all-important filter in 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 - ]]> 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. -
- <interfacename>SecurityContextRepository</interfacename> - From Spring Security 3.0, the job of loading and storing the security context - is now delegated to a separate strategy interface: - +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. +
+ <interfacename>SecurityContextRepository</interfacename> + From Spring Security 3.0, the job of loading and storing the security context is + now delegated to a separate strategy interface: + public interface SecurityContextRepository { - SecurityContext loadContext(HttpRequestResponseHolder requestResponseHolder); - void saveContext(SecurityContext context, HttpServletRequest request, HttpServletResponse response); +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 - 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: 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 + 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: - - - - - +class="org.springframework.security.web.context.SecurityContextPersistenceFilter"> + + + - ]]> Alternatively you could provide a null implementation of the - SecurityContextRepository interface. -
+ + +]]> Alternatively you could provide a null implementation of the + SecurityContextRepository interface.
-
- <classname>UsernamePasswordAuthenticationProcessingFilter</classname> - 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 - 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 - UsernamePasswordAuthenticationProcessingFilter - 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 j_username and - j_password input fields, and posts to the URL that is - monitored by the filter (by default this is - /j_spring_security_check). The basic filter configuration - looks something like this: +
+ <classname>UsernamePasswordAuthenticationProcessingFilter</classname> + 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 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 + UsernamePasswordAuthenticationProcessingFilter in + the application contextAdd the filter bean + to your filter chain proxy (making sure you pay attention to the order). + The login form simply + contains j_username and j_password input fields, + and posts to the URL that is monitored by the filter (by default this is + /j_spring_security_check). The basic filter configuration looks + something like this: ]]> - -
- 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 - 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 and - ExceptionMappingAuthenticationFailureHandler. Have a - look at the Javadoc for these classes to see how they work. - 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 approprate 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. - 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. - -
+ +
+ 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 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 and + ExceptionMappingAuthenticationFailureHandler. Have a look + at the Javadoc for these classes to see how they work. + 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 approprate 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. 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. +