Ref manual updates and correction

docs/manual/src/docbook/introduction.xml

@@ -17,16 +17,19 @@
             standards, it's important to recognise that they are not portable at a WAR or EAR level.
             Therefore, if you switch server environments, it is typically a lot of work to
             reconfigure your application's security in the new target environment. Using Spring
-            Security overcomes these problems, and also brings you dozens of other useful, entirely
+            Security overcomes these problems, and also brings you dozens of other useful,
             customisable security features.</para>
-        <para>As you probably know, security comprises two major operations. The first is known as
+        <para>As you probably know two major areas of application security are
-            "authentication", which is the process of establishing a principal is who they claim to
+                <quote>authentication</quote> and <quote>authorization</quote> (or
-            be. A "principal" generally means a user, device or some other system which can perform
+                <quote>access-control</quote>). These are the the two main areas that Spring
-            an action in your application. "Authorization" refers to the process of deciding whether
+            Security targets. <quote>Authentication</quote> is the process of establishing a
-            a principal is allowed to perform an action in your application. To arrive at the point
+            principal is who they claim to be (a <quote>principal</quote> generally means a user,
-            where an authorization decision is needed, the identity of the principal has already
+            device or some other system which can perform an action in your application).
-            been established by the authentication process. These concepts are common, and not at
+                <quote>Authorization</quote> refers to the process of deciding whether a principal
-            all specific to Spring Security.</para>
+            is allowed to perform an action within your application. To arrive at the point where an
+            authorization decision is needed, the identity of the principal has already been
+            established by the authentication process. These concepts are common, and not at all
+            specific to Spring Security. </para>
         <para>At an authentication level, Spring Security supports a wide range of authentication
             models. Most of these authentication models are either provided by third parties, or are
             developed by relevant standards bodies such as the Internet Engineering Task Force. In
@@ -54,7 +57,8 @@
                 <para>OpenID authentication</para>
             </listitem>
             <listitem>
-                <para>Computer Associates Siteminder</para>
+                <para>Authentication based on pre-established request headers (such as Computer
+                    Associates Siteminder)</para>
             </listitem>
             <listitem>
                 <para>JA-SIG Central Authentication Service (otherwise known as CAS, which is a
@@ -80,8 +84,11 @@
                 <para>Java Authentication and Authorization Service (JAAS)</para>
             </listitem>
             <listitem>
-                <para>Container integration with JBoss, Jetty, Resin and Tomcat (so you can still
+                <para>JEE container autentication (so you can still use Container Managed
-                    use Container Manager Authentication if desired)</para>
+                    Authentication if desired)</para>
+            </listitem>
+            <listitem>
+                <para>Kerberos</para>
             </listitem>
             <listitem>
                 <para>Java Open Source Single Sign On (JOSSO) *</para>
@@ -142,20 +149,18 @@
             differentiate security based on the way a principal is interacting with your
             application. For example, you might want to ensure requests only arrive over HTTPS, in
             order to protect passwords from eavesdropping or end users from man-in-the-middle
-            attacks. Or, you might want to ensure that an actual human being is making the requests
+            attacks. This is especially helpful to protect password recovery processes from brute
-            and not some robot or other automated process. This is especially helpful to protect
+            force attacks, or simply to make it harder for people to duplicate your application's
-            password recovery processes from brute force attacks, or simply to make it harder for
+            key content. To help you achieve these goals, Spring Security fully supports automatic
-            people to duplicate your application's key content. To help you achieve these goals,
+            "channel security", together with JCaptcha integration for human user detection.</para>
-            Spring Security fully supports automatic "channel security", together with JCaptcha
-            integration for human user detection.</para>
         <para>Irrespective of how authentication was undertaken, Spring Security provides a deep set
             of authorization capabilities. There are three main areas of interest in respect of
-            authorization, these being authorizing web requests, authorizing methods can be invoked,
+            authorization, these being authorizing web requests, authorizing whether methods can be
-            and authorizing access to individual domain object instances. To help you understand the
+            invoked, and authorizing access to individual domain object instances. To help you
-            differences, consider the authorization capabilities found in the Servlet Specification
+            understand the differences, consider the authorization capabilities found in the Servlet
-            web pattern security, EJB Container Managed Security and file system security
+            Specification web pattern security, EJB Container Managed Security and file system
-            respectively. Spring Security provides deep capabilities in all of these important
+            security respectively. Spring Security provides deep capabilities in all of these
-            areas, which we'll explore later in this reference guide.</para>
+            important areas, which we'll explore later in this reference guide.</para>
     </sect1>
     <sect1 xml:id="history">
         <title>History</title>

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

@@ -21,9 +21,9 @@
 ]]></programlisting> This is much simpler than wiring up the equivalent Apache Directory Server
       beans. The most common alternative configuration requirements are supported by attributes on
       the <literal>ldap-server</literal> element and the user is isolated from worrying about which
-      beans they need to be set on and what the bean property names are. <footnote><para>You can
+      beans they need create and what the bean property names are. <footnote><para>You can find out
-          find out more about the use of the <literal>ldap-server</literal> element in the chapter
+          more about the use of the <literal>ldap-server</literal> element in the chapter on <link
-          on <link xlink:href="#ldap">LDAP</link>.</para></footnote>. Use of a good XML editor while
+            xlink:href="#ldap">LDAP</link>.</para></footnote>. Use of a good XML editor while
       editing the application context file should provide information on the attributes and elements
       that are available. We would recommend that you try out the <link
         xlink:href="http://www.springsource.com/products/sts">SpringSource Tool Suite</link> as it
@@ -42,7 +42,7 @@
 </beans>
   ]]></programlisting> In many of the examples you will see (and in the sample) applications, we
       will often use "security" as the default namespace rather than "beans", which means we can
-      omit the prefix on all the security namespace elements, making the context easier to read. You
+      omit the prefix on all the security namespace elements, making the content easier to read. You
       may also want to do this if you have your application context divided up into separate files
       and have most of your security configuration in one of them. Your security application context
       file would then start like this <programlisting language="xml"><![CDATA[
@@ -155,20 +155,25 @@
           elements must be within the <literal>authentication-manager</literal> element, which
           creates a <classname>ProviderManager</classname> and registers the authentication
           providers with it. You can find more detailed information on the beans that are created in
-          the <link xlink:href="#appendix-namespace">namespace appendix</link>. </para>
+          the <link xlink:href="#appendix-namespace">namespace appendix</link>. It's worth
+          cross-checking this if you want to start understanding what the important classes in the
+          framework are and how they are used, particularly if you want to customise things
+          later.</para>
       </sidebar>
       <para> The configuration above defines two users, their passwords and their roles within the
         application (which will be used for access control). It is also possible to load user
         information from a standard properties file using the <literal>properties</literal>
         attribute on <literal>user-service</literal>. See the section on <link
           xlink:href="#core-services-in-memory-service">in-memory authentication</link> for more
-        details. Using the <literal>&lt;authentication-provider&gt;</literal> element means that the
+        details on the file format. Using the <literal>&lt;authentication-provider&gt;</literal>
-        user information will be used by the authentication manager to process authentication
+        element means that the user information will be used by the authentication manager to
-        requests. </para>
+        process authentication requests. You can have multiple
+          <literal>&lt;authentication-provider&gt;</literal> elements to define different
+        authentication sources and each will be consulted in turn.</para>
       <para> At this point you should be able to start up your application and you will be required
-        to log in to proceed. Try it out, or try experimenting with the "tutorial" sample
+        to log in to proceed. Try it out, or try experimenting with the <quote>tutorial</quote>
-        application that comes with the project. The above configuration actually adds quite a few
+        sample application that comes with the project. The above configuration actually adds quite
-        services to the application because we have used the <literal>auto-config</literal>
+        a few services to the application because we have used the <literal>auto-config</literal>
         attribute. For example, form-based login processing is automatically enabled. </para>
       <section xml:id="ns-auto-config">
         <title>What does <literal>auto-config</literal> Include?</title>
@@ -179,16 +184,15 @@
     <http-basic />
     <logout />
   </http>
-  ]]>
+  ]]></programlisting> These other elements are responsible for setting up form-login, basic
-          </programlisting> These other elements are responsible for setting up form-login,
+          authentication and logout handling services respectively <footnote><para>In versions prior
-          basic authentication and logout handling services respectively <footnote><para>In versions
+              to 3.0, this list also included remember-me functionality. This could cause some
-              prior to 3.0, this list also inluded remember-me functionality. This could cause some
               confusing errors with some configurations and was removed in 3.0. In 3.0, the addition
-              of an <classname>AnonymousProcessingFilter</classname> was made part of the default
+              of an <classname>AnonymousProcessingFilter</classname> is part of the default
                 <literal>&lt;http></literal> configuration, so the <literal>&lt;anonymous
-                /></literal> element is effectively added regardless of whether
+                /></literal> element is added regardless of whether <literal>auto-config</literal>
-                <literal>auto-config</literal> is enabled.</para></footnote> . They each have
+              is enabled.</para></footnote> . They each have attributes which can be used to alter
-          attributes which can be used to alter their behaviour. </para>
+          their behaviour. </para>
       </section>
       <section xml:id="ns-form-and-basic">
         <title>Form and Basic Login Options</title>
@@ -196,22 +200,39 @@
           in, since we made no mention of any HTML files or JSPs. In fact, since we didn't
           explicitly set a URL for the login page, Spring Security generates one automatically,
           based on the features that are enabled and using standard values for the URL which
-          processes the submitted login, the default target URL the user will be sent to and so on.
+          processes the submitted login, the default target URL the user will be sent to after
-          However, the namespace offers plenty of suppport to allow you to customize these options.
+          loggin in and so on. However, the namespace offers plenty of support to allow you to
-          For example, if you want to supply your own login page, you could use: <programlisting language="xml"><![CDATA[
+          customize these options. For example, if you want to supply your own login page, you could
+          use: <programlisting language="xml"><![CDATA[
   <http auto-config='true'>
-    <intercept-url pattern="/login.jsp*" filters="none"/>  
+    <intercept-url pattern="/login.jsp*" access="IS_AUTHENTICATED_ANONYMOUSLY"/>  
     <intercept-url pattern="/**" access="ROLE_USER" />
     <form-login login-page='/login.jsp'/>
   </http>
   ]]>
-        </programlisting> Note that you could still use <literal>auto-config</literal>. The
+        </programlisting> Note that you can still use <literal>auto-config</literal>. The
             <literal>form-login</literal> element just overrides the default settings. Also note
           that we've added an extra <literal>intercept-url</literal> element to say that any
-          requests for the login page should be excluded from processing by the security filters.
+          requests for the login page should be available to anonymous users <footnote><para>See the
-          Otherwise the request would be matched by the pattern <literal>/**</literal> and it
+              chapter on <link xlink:href="#anonymous">anonymous authentication</link> for more
-          wouldn't be possible to access the login page itself! If you want to use basic
+              details.</para></footnote>. Otherwise the request would be matched by the pattern
-          authentication instead of form login, then change the configuration to <programlisting language="xml"><![CDATA[
+            <literal>/**</literal> and it wouldn't be possible to access the login page 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[
+  <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> Note that these requests will be completely oblivious to Spring
+          Security, so you will not be able to access information on the current user or call
+          secured methods during the request. </para>
+        <para>If you want to use basic authentication instead of form login, then change the
+          configuration to <programlisting language="xml"><![CDATA[
   <http auto-config='true'>
     <intercept-url pattern="/**" access="ROLE_USER" />
     <http-basic />
@@ -501,7 +522,7 @@
           and remove any elements which create filters whose functionality you want to replace. </para>
         <para> Note that you can't replace filters which are created by the use of the
             <literal>&lt;http&gt;</literal> element itself -
-            <classname>HttpSessionContextIntegrationFilter</classname>,
+            <classname>SecurityContextPersistenceFilter</classname>,
             <classname>ExceptionTranslationFilter</classname> or
             <classname>FilterSecurityInterceptor</classname>. </para>
       </tip>

docs/manual/src/docbook/springsecurity.xml

@@ -1,14 +1,12 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <book version="5.0" xml:id="spring-security-reference-guide" xmlns="http://docbook.org/ns/docbook"
   xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
-  <info><title>Spring Security</title><subtitle>Reference Documentation</subtitle><authorgroup>
+  <info><title>Spring Security</title><subtitle>Reference
-      <author>
+        Documentation</subtitle><authorgroup><author>
         <personname>Ben Alex</personname>
-      </author>
+      </author><author>
-      <author>
         <personname>Luke Taylor</personname>
-      </author>
+      </author></authorgroup>
-    </authorgroup>
     <productname>Spring Security</productname>
     <releaseinfo>3.0.0.M2</releaseinfo>
   </info>
@@ -49,15 +47,15 @@
       custom requirements make application security interesting, challenging and rewarding. </para>
     <para>Please read <xref linkend="getting-started"/>, in its entirety to begin with. This will
       introduce you to the framework and the namespace-based configuration system with which you can
-      get up and running quite quickly. To get more of an understanding of an in-depth understaning
+      get up and running quite quickly. To get more of an understanding of how Spring Security
-      of how Spring Security works, and some of the classes you might need to use, you should then
+      works, and some of the classes you might need to use, you should then read <xref
-      read <xref linkend="overall-architecture"/>. The remaining parts of this guide are structured
+        linkend="overall-architecture"/>. The remaining parts of this guide are structured in a more
-      in a more traditional reference style, designed to be read on an as-required basis. We'd also
+      traditional reference style, designed to be read on an as-required basis. We'd also recommend
-      recommend that you read up as much as possible on application security issues in general.
+      that you read up as much as possible on application security issues in general. Spring
-      Spring Security is not a panacea which will solve all security issues. It is important that
+      Security is not a panacea which will solve all security issues. It is important that the
-      the application is designed with security in mind from the start. Attempting to retrofit it is
+      application is designed with security in mind from the start. Attempting to retrofit it is not
-      not a good idea. In particular, if you are building a web application, you should be aware of
+      a good idea. In particular, if you are building a web application, you should be aware of the
-      the many potential vulnerabilities such as cross-site scripting, request-forgery and
+      many potential vulnerabilities such as cross-site scripting, request-forgery and
       session-hijacking which you should be taking into account from the start. The OWASP web site
       (http://www.owasp.org/) maintains a top ten list of web application vulnerabilities as well as
       a lot of useful reference information. </para>
@@ -70,12 +68,12 @@
     <title>Getting Started</title>
     <partintro>
       <para>The later parts of this guide provide an in-depth discussion of the framework
-        architecture and implementation classes, an understanding of which is important if you need
+        architecture and implementation classes, which you need to understand if you want to do any
-        to do any serious customization. In this part, we'll introduce Spring Security 3.0, give a
+        serious customization. In this part, we'll introduce Spring Security 3.0, give a brief
-        brief overview of the project's history and take a slightly gentler look at how to get
+        overview of the project's history and take a slightly gentler look at how to get started
-        started using the framework. In particular, we'll look at namespace configuration which
+        using the framework. In particular, we'll look at namespace configuration which provides a
-        provides a much simpler way of securing your application compared to the traditional Spring
+        much simpler way of securing your application compared to the traditional Spring bean
-        bean approach where you had to wire up all the implementation classes individually. </para>
+        approach where you have to wire up all the implementation classes individually. </para>
       <para> We'll also take a look at the sample applications that are available. It's worth trying
         to run these and experimenting with them a bit even before you read the later sections - you
         can dip back into them as your understanding of the framework increases. </para>
@@ -115,9 +113,9 @@
     <xi:include href="basic-and-digest-auth.xml"/>
     <xi:include href="remember-me-authentication.xml"/>
     <xi:include href="concurrent-sessions.xml"/>
-    <xi:include href="anon-auth-provider.xml"/>    
+    <xi:include href="anon-auth-provider.xml"/>
   </part>
-<!--  
+  <!--  
   <part xml:id="authentication">
     <title>Authentication</title>
     <partintro>
@@ -141,7 +139,7 @@
     </partintro>
     <xi:include href="dao-auth-provider.xml"/>
   </part>
--->  
+-->
   <part xml:id="authorization">
     <title>Authorization</title>
     <partintro>
@@ -165,15 +163,16 @@
       Essentially standalone features which do not have to follow on directly from earlier chapters 
     -->
     <partintro>
-      <para> In this part we cover some of the more advanced and less-commonly used features of the framework.</para>
+      <para> In this part we cover some of the more advanced and less-commonly used features of the
+        framework.</para>
     </partintro>
-    <xi:include href="domain-acls.xml"/>    
+    <xi:include href="domain-acls.xml"/>
     <xi:include href="preauth.xml"/>
     <xi:include href="ldap-auth-provider.xml"/>
     <xi:include href="jaas-auth-provider.xml"/>
     <xi:include href="cas-auth-provider.xml"/>
     <xi:include href="x509-auth-provider.xml"/>
-    <xi:include href="runas-auth-provider.xml"/>    
+    <xi:include href="runas-auth-provider.xml"/>
   </part>
   <xi:include href="appendix-db-schema.xml"/>
   <xi:include href="appendix-namespace.xml"/>