From 0d94e75a936d456bb9b8bc4a3a087779a42db72a Mon Sep 17 00:00:00 2001 From: Luke Taylor Date: Sat, 5 Jun 2010 17:12:33 +0100 Subject: [PATCH] SEC-1171: Documentation of changes related to use of multiple elements. --- .../manual/src/docbook/appendix-namespace.xml | 41 +++++++++++++------ docs/manual/src/docbook/namespace-config.xml | 37 +++++++++++++---- .../src/docbook/security-filter-chain.xml | 38 +++++++++++++++-- 3 files changed, 90 insertions(+), 26 deletions(-) diff --git a/docs/manual/src/docbook/appendix-namespace.xml b/docs/manual/src/docbook/appendix-namespace.xml index 53a5cbf81d..9365eca0c2 100644 --- a/docs/manual/src/docbook/appendix-namespace.xml +++ b/docs/manual/src/docbook/appendix-namespace.xml @@ -19,14 +19,15 @@ >schema file directly.
Web Application Security - the <literal><http></literal> Element - The <http> element encapsulates the security configuration - for the web layer of your application. It creates a - FilterChainProxy bean named "springSecurityFilterChain" which - maintains the stack of security filters which make up the web security configuration + If you use an <http> element within your application, + a FilterChainProxy bean named "springSecurityFilterChain" is created and + the configuration within the element is used to build a filter chain within + FilterChainProxy. As of Spring Security 3.1, additional + http elements can be used to add extra filter chains See the introductory chapter for how to set up the mapping from your web.xml - . Some core filters are always created and others will be added to the stack - depending on the attributes child elements which are present. The positions of the + . Some core filters are always created in a filter chain and others will be added + to the stack depending on the attributes and child elements which are present. The positions of the standard filters are fixed (see the filter order table in the namespace introduction), removing a common source of errors with previous versions of the framework when users had to configure the filter chain @@ -37,22 +38,38 @@ with the internal instance created by the namespace configuration (see the introductory chapter for more on the AuthenticationManager). - The <http> namespace block always creates an - HttpSessionContextIntegrationFilter, an + Each <http> namespace block always creates an + SecurityContextPersistenceFilter, an ExceptionTranslationFilter and a FilterSecurityInterceptor. These are fixed and cannot be replaced with alternatives.
<literal><http></literal> Attributes The attributes on the <http> element control some of the - properties on the core filters. + properties on the core filters. +
+ <literal>pattern</literal> + Defining a pattern for the http element controls + the requests which will be filtered through the list of filters which it defines. The + interpretation is dependent on the configured request-matcher. + If no pattern is defined, all requests will be matched, so the most specific patterns should be + declared first. + +
+
+ <literal>secured</literal> + A request pattern can be mapped to an empty filter chain, by setting + this attribute to false. No security will be applied and + none of Spring Security's features will be available. + +
<literal>servlet-api-provision</literal> Provides versions of HttpServletRequest security methods such as isUserInRole() and getPrincipal() which are implemented by adding a SecurityContextHolderAwareRequestFilter bean to the - stack. Defaults to "true". + stack. Defaults to "true".
<literal>request-matcher</literal> @@ -142,9 +159,7 @@ This element is used to define the set of URL patterns that the application is interested in and to configure how they should be handled. It is used to construct the FilterInvocationSecurityMetadataSource used by - the FilterSecurityInterceptor and to exclude particular - patterns from the filter chain entirely (by setting the attribute - filters="none"). It is also responsible for configuring a + the FilterSecurityInterceptor. It is also responsible for configuring a ChannelAuthenticationFilter if particular URLs need to be accessed by HTTPS, for example. When matching the specified patterns against an incoming request, the matching is done in the order in which the elements are diff --git a/docs/manual/src/docbook/namespace-config.xml b/docs/manual/src/docbook/namespace-config.xml index 43f58081ef..24ebff704e 100644 --- a/docs/manual/src/docbook/namespace-config.xml +++ b/docs/manual/src/docbook/namespace-config.xml @@ -241,8 +241,10 @@ default <http> configuration, so the <anonymous /> element is added regardless of whether auto-config is enabled. - . They each have attributes which can be used to alter their - behaviour. + . They each have attributes which can be used to alter their + behaviour. In anything other than very basic scenarios, it is probably better + to omit the auto-config attribute and configure what you require + explicitly in the interest of clarity.
@@ -275,16 +277,33 @@ itself! This is a common configuration error and will result in an infinite loop in the application. Spring Security will emit a warning in the log if your login page appears to be secured. It is also possible to have all requests matching a - particular pattern bypass the security filter chain completely: http element for the pattern like this: + + - - ]]> - It's important to realise that these requests will be completely - oblivious to any further Spring Security web-related configuration or additional + + From Spring Security 3.1 it is now possible to use multiple http + elements to define separate security filter chain configurations for different + request patterns. If the pattern attribute is omitted from an + http element, it matches all requests. Creating an unsecured + pattern is a simple example of this syntax, where the pattern is mapped to an empty filter chain + The use of multiple <http> elements is an + important feature, allowing the namespace to simultaneously support both stateful and stateless + paths within the same application, for example. The previous syntax, using the attribute + filters="none" on an intercept-url element + is incompatible with this change and is no longer supported in 3.1.. + We'll look at this new syntax in more detail in the chapter on the + Security Filter Chain. + + + It's important to realise that these unsecured requests will be completely + oblivious to any Spring Security web-related configuration or additional attributes such as requires-channel, so you will not be able to access information on the current user or call secured methods during the request. Use access='IS_AUTHENTICATED_ANONYMOUSLY' as an alternative if @@ -311,8 +330,8 @@ always-use-default-target attribute to "true". This is useful if your application always requires that the user starts at a "home" page, for example: - @@ -573,7 +592,7 @@ are returned as part of the authentication process and can be accessed afterwards using the following code: -OpenIDAuthenticationToken token = +OpenIDAuthenticationToken token = (OpenIDAuthenticationToken)SecurityContextHolder.getContext().getAuthentication(); List<OpenIDAttribute> attributes = token.getAttributes();The OpenIDAttribute contains the attribute type and the diff --git a/docs/manual/src/docbook/security-filter-chain.xml b/docs/manual/src/docbook/security-filter-chain.xml index d0a25c9f7b..e6be055bb0 100644 --- a/docs/manual/src/docbook/security-filter-chain.xml +++ b/docs/manual/src/docbook/security-filter-chain.xml @@ -62,7 +62,7 @@ context with the same bean name. Here's an example: - as an alternative to supplying a filter bean list. This will omit the request pattern from the security filter chain entirely. Note that anything matching this path will then have no authentication or authorization services @@ -184,6 +184,36 @@ other filters. Examples are the use of SiteMesh to decorate your web pages or a web framework like Wicket which uses a filter to handle its requests.
+
+ Advanced Namespace Configuration + As we saw earlier in the namespace chapter, it's possible to use multiple http + elements to define different security configurations for different URL patterns. + Each element creates a filter chain within the internal FilterChainProxy and the + URL pattern that should be mapped to it. The elements will be added in the order they are declared, so the + most specific patterns must again be declared first. Here's another example, for a similar situation to + that above, where the application supports both a stateless RESTful API and also a normal web application + which users log into using a form. + + + + + + + + + + + + + + + + + ]]> + + +