SEC-1171: Documentation of changes related to use of multiple <http> elements.

docs/manual/src/docbook/appendix-namespace.xml

@@ -19,14 +19,15 @@
             >schema file</link> directly.</para>
     <section xml:id="nsa-http">
         <title>Web Application Security - the <literal>&lt;http&gt;</literal> Element</title>
-        <para> The <literal>&lt;http&gt;</literal> element encapsulates the security configuration
+        <para> If you use an <literal>&lt;http&gt;</literal> element within your application,
-            for the web layer of your application. It creates a
+            a <classname>FilterChainProxy</classname> bean named "springSecurityFilterChain" is created and
-                <classname>FilterChainProxy</classname> bean named "springSecurityFilterChain" which
+            the configuration within the element is used to build a filter chain within
-            maintains the stack of security filters which make up the web security configuration <footnote>
+            <classname>FilterChainProxy</classname>. As of Spring Security 3.1, additional
+            <literal>http</literal> elements can be used to add extra filter chains <footnote>
                 <para>See the <link xlink:href="#ns-web-xml"> introductory chapter</link> for how to
                     set up the mapping from your <literal>web.xml</literal></para>
-            </footnote>. Some core filters are always created and others will be added to the stack
+            </footnote>. Some core filters are always created in a filter chain and others will be added
-            depending on the attributes child elements which are present. The positions of the
+            to the stack depending on the attributes and child elements which are present. The positions of the
             standard filters are fixed (see <link xlink:href="#filter-stack">the filter order
                 table</link> 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 <link
                 xlink:href="#ns-auth-manager"> introductory chapter</link> for more on the
                 <interfacename>AuthenticationManager</interfacename>). </para>
-        <para> The <literal>&lt;http&gt;</literal> namespace block always creates an
+        <para> Each <literal>&lt;http&gt;</literal> namespace block always creates an
-                <classname>HttpSessionContextIntegrationFilter</classname>, an
+                <classname>SecurityContextPersistenceFilter</classname>, an
                 <classname>ExceptionTranslationFilter</classname> and a
                 <classname>FilterSecurityInterceptor</classname>. These are fixed and cannot be
             replaced with alternatives. </para>
         <section xml:id="nsa-http-attributes">
             <title><literal>&lt;http&gt;</literal> Attributes</title>
             <para> The attributes on the <literal>&lt;http&gt;</literal> element control some of the
-                properties on the core filters. </para>
+            properties on the core filters. </para>
+            <section xml:id="nsa-http-pattern">
+                <title><literal>pattern</literal></title>
+                <para>Defining a pattern for the <literal>http</literal> element controls
+                the requests which will be filtered through the list of filters which it defines. The
+                interpretation is dependent on the configured <link xlink:href="#nsa-path-type">request-matcher</link>.
+                 If no pattern is defined, all requests will be matched, so the most specific patterns should be
+                 declared first.
+                </para>
+            </section>
+            <section xml:id="nsa-http-secured">
+                <title><literal>secured</literal></title>
+                <para>A request pattern can be mapped to an empty filter chain, by setting
+                this attribute to <literal>false</literal>. No security will be applied and
+                none of Spring Security's features will be available.
+                </para>
+            </section>
             <section xml:id="nsa-servlet-api-provision">
                 <title><literal>servlet-api-provision</literal></title>
                 <para> Provides versions of <literal>HttpServletRequest</literal> security methods
                     such as <literal>isUserInRole()</literal> and <literal>getPrincipal()</literal>
                     which are implemented by adding a
                         <classname>SecurityContextHolderAwareRequestFilter</classname> bean to the
-                    stack. Defaults to "true". </para>
+                    stack. Defaults to "true".</para>
             </section>
             <section xml:id="nsa-path-type">
                 <title><literal>request-matcher</literal></title>
@@ -142,9 +159,7 @@
             <para> 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 <interfacename>FilterInvocationSecurityMetadataSource</interfacename> used by
-                the <classname>FilterSecurityInterceptor</classname> and to exclude particular
+                the <classname>FilterSecurityInterceptor</classname>. It is also responsible for configuring a
-                patterns from the filter chain entirely (by setting the attribute
-                    <literal>filters="none"</literal>). It is also responsible for configuring a
                     <classname>ChannelAuthenticationFilter</classname> 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

docs/manual/src/docbook/namespace-config.xml

@@ -241,8 +241,10 @@
                             default <literal>&lt;http></literal> configuration, so the
                                 <literal>&lt;anonymous /></literal> element is added regardless of
                             whether <literal>auto-config</literal> is enabled.</para>
-                    </footnote> . They each have attributes which can be used to alter their
+                    </footnote>. They each have attributes which can be used to alter their
-                    behaviour. </para>
+                    behaviour. In anything other than very basic scenarios, it is probably better
+                to omit the <literal>auto-config</literal> attribute and configure what you require
+                    explicitly in the interest of clarity.</para>
             </section>
         </section>
         <section xml:id="ns-form-and-basic">
@@ -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: <programlisting language="xml"><![CDATA[
+                particular pattern bypass the security filter chain completely, by defining a separate
+                <literal>http</literal> element for the pattern like this: <programlisting language="xml"><![CDATA[
+  <http pattern="/css/**" secured="false"/>
+  <http pattern="/login.jsp*" secured="false"/>
+
   <http auto-config='true'>
-    <intercept-url pattern="/css/**" filters="none"/>
-    <intercept-url pattern="/login.jsp*" filters="none"/>
     <intercept-url pattern="/**" access="ROLE_USER" />
     <form-login login-page='/login.jsp'/>
   </http>
   ]]>
-      </programlisting>It's important to realise that these requests will be completely
+                </programlisting>
-                oblivious to any further Spring Security web-related configuration or additional
+                From Spring Security 3.1 it is now possible to use multiple <literal>http</literal>
+                elements to define separate security filter chain configurations for different
+                request patterns. If the <literal>pattern</literal> attribute is omitted from an
+                <literal>http</literal> 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
+                <footnote><para>The use of multiple <literal>&lt;http&gt;</literal> 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
+                <literal>filters="none"</literal> on an <literal>intercept-url</literal> element
+                is incompatible with this change and is no longer supported in 3.1.</para></footnote>.
+                We'll look at this new syntax in more detail in the chapter on the
+                <link xlink:href="#filter-chains-with-ns">Security Filter Chain</link>.
+            </para>
+            <para>
+                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 <literal>requires-channel</literal>, so you will not be able to
                 access information on the current user or call secured methods during the request.
                 Use <literal>access='IS_AUTHENTICATED_ANONYMOUSLY'</literal> as an alternative if
@@ -311,8 +330,8 @@
                         <literal>always-use-default-target</literal> attribute to "true". This is
                     useful if your application always requires that the user starts at a "home"
                     page, for example: <programlisting language="xml"><![CDATA[
+  <http pattern="/login.htm*" secured="false"/>
   <http>
-    <intercept-url pattern='/login.htm*' filters='none'/>
     <intercept-url pattern='/**' access='ROLE_USER' />
     <form-login login-page='/login.htm' default-target-url='/home.htm'
             always-use-default-target='true' />

docs/manual/src/docbook/security-filter-chain.xml

@@ -62,7 +62,7 @@
             context with the same bean name. Here's an example: <programlisting language="xml"><![CDATA[
 <bean id="filterChainProxy" class="org.springframework.security.web.FilterChainProxy">
   <sec:filter-chain-map path-type="ant">
-     <sec:filter-chain pattern="/webServices/**" filters="
+     <sec:filter-chain pattern="/restful/**" filters="
            securityContextPersistenceFilterWithASCFalse,
            basicAuthenticationFilter,
            exceptionTranslationFilter,
@@ -75,8 +75,8 @@
   </sec:filter-chain-map>
 </bean>
 ]]>
-    </programlisting> The namespace element <literal>filter-chain-map</literal> is used to set
+            </programlisting> The namespace element <literal>filter-chain-map</literal> is used for convenience
-            up the security filter chain(s) which are required within the application<footnote>
+            to set up the security filter chain(s) which are required within the application<footnote>
             <para>Note that you'll need to include the security namespace in your application
                 context XML file in order to use this syntax.</para>
             </footnote>. It maps a particular URL pattern to a chain of filters built up from the
@@ -105,7 +105,7 @@
             namespace. </para>
         <section>
             <title>Bypassing the Filter Chain</title>
-            <para> As with the namespace, you can use the attribute <literal>filters =
+            <para> You can use the attribute <literal>filters =
                 "none"</literal> 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. </para>
     </section>
+    <section xml:id="filter-chains-with-ns">
+        <title>Advanced Namespace Configuration</title>
+        <para>As we saw earlier in the namespace chapter, it's possible to use multiple <literal>http</literal>
+        elements to define different security configurations for different URL patterns.
+        Each element creates a filter chain within the internal <classname>FilterChainProxy</classname> 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.
+<programlisting>
+<![CDATA[
+  <!-- Stateless RESTful service using Basic authentication -->
+  <http pattern="/restful/**" create-session="stateless">
+    <intercept-url pattern='/**' access='ROLE_REMOTE' />
+    <http-basic />
+  </http>
+
+  <!-- Empty filter chain for the login page -->
+  <http pattern="/login.htm*" secured="false"/>
+
+  <!-- Additional filter chain for normal users, matching all other requests -->
+  <http>
+    <intercept-url pattern='/**' access='ROLE_USER' />
+    <form-login login-page='/login.htm' default-target-url="/home.htm"/>
+    <logout />
+  </http>
+  ]]>
+</programlisting>
+        </para>
+    </section>
     <!--
   <section xml:id="taglib">
     <info>