SEC-1535: Added suggested doc fixes.

config/src/main/resources/org/springframework/security/config/spring-security-3.1.rnc

@@ -519,7 +519,7 @@ token-repository-ref =
     ## Reference to a PersistentTokenRepository bean for use with the persistent token remember-me implementation.
     attribute token-repository-ref {xsd:token}
 remember-me-services-ref =
-    ## Allows a custom implementation of RememberMeServices to be used. Note that this implementation should return RememberMeAuthenticationToken instances with the same "key" value as specified in the remember-me element. Alternatively it should register its own AuthenticationProvider.
+    ## Allows a custom implementation of RememberMeServices to be used. Note that this implementation should return RememberMeAuthenticationToken instances with the same "key" value as specified in the remember-me element. Alternatively it should register its own AuthenticationProvider. It should also implement the LogoutHandler interface, which will be invoked when a user logs out. Typically the remember-me cookie would be removed on logout.
     attribute services-ref {xsd:token}?
 remember-me-data-source-ref =
     ## DataSource bean for the database that contains the token repository schema.

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

@@ -15,7 +15,7 @@
         explaining their purpose. The namespace is written in <link
         xlink:href="http://www.relaxng.org/">RELAX NG</link> Compact format and later converted into
         an XSD schema. If you are familiar with this format, you may wish to examine the <link
-        xlink:href="https://src.springsource.org/svn/spring-security/trunk/config/src/main/resources/org/springframework/security/config/spring-security-3.0.rnc"
+        xlink:href="https://fisheye.springsource.org/browse/spring-security/config/src/main/resources/org/springframework/security/config/spring-security-3.1.rnc"
         >schema file</link> directly.</para>
     <section xml:id="nsa-http">
         <title>Web Application Security - the <literal>&lt;http&gt;</literal> Element</title>
@@ -235,7 +235,7 @@
                 filter stack and an <classname>LoginUrlAuthenticationEntryPoint</classname> to the
                 application context to provide authentication on demand. This will always take
                 precedence over other namespace-created entry points. If no attributes are supplied,
-                a login page will be generated automatically at the URL "/spring-security-login" <footnote>
+                a login page will be generated automatically at the URL "/spring_security_login" <footnote>
                 <para>This feature is really just provided for convenience and is not intended for
                     production (where a view technology will have been chosen and can be used to
                     render a customized login page). The class
@@ -248,7 +248,7 @@
                 <para> The URL that should be used to render the login page. Maps to the
                     <literal>loginFormUrl</literal> property of the
                     <classname>LoginUrlAuthenticationEntryPoint</classname>. Defaults to
-                    "/spring-security-login". </para>
+                    "/spring_security_login". </para>
             </section>
             <section>
                 <title><literal>login-processing-url</literal></title>
@@ -322,18 +322,13 @@
                     will be used and configured with a
                     <classname>JdbcTokenRepositoryImpl</classname> instance. </para>
             </section>
-            <section>
-                <title><literal>token-repository-ref</literal></title>
-                <para> Configures a <classname>PersistentTokenBasedRememberMeServices</classname>
-                    but allows the use of a custom
-                    <interfacename>PersistentTokenRepository</interfacename> bean. </para>
-            </section>
             <section>
                 <title><literal>services-ref</literal></title>
                 <para> Allows complete control of the
                     <interfacename>RememberMeServices</interfacename> implementation that will be
-                    used by the filter. The value should be the Id of a bean in the application
-                    context which implements this interface. </para>
+                    used by the filter. The value should be the <literal>id</literal> of a bean in the application
+                    context which implements this interface. Should also implement 
+                    <interfacename>LogoutHandler</interfacename> if a logout filter is in use.</para>
             </section>
             <section>
                 <title><literal>token-repository-ref</literal></title>
@@ -365,7 +360,7 @@
                     <interfacename>UserDetailsService</interfacename>, so there has to be one
                     defined in the application context. If there is only one, it will be selected
                     and used automatically by the namespace configuration. If there are multiple
-                    instances, you can specify a bean Id explicitly using this attribute. </para>
+                    instances, you can specify a bean <literal>id</literal> explicitly using this attribute. </para>
             </section>
         </section>
         <section xml:id="nsa-session-mgmt">
@@ -468,7 +463,7 @@
                 <classname>OpenIDAuthenticationFilter</classname> and
                 <classname>OpenIDAuthenticationProvider</classname> will be registered. The latter
                 requires a reference to a <interfacename>UserDetailsService</interfacename>. Again,
-                this can be specified by Id, using the <literal>user-service-ref</literal>
+                this can be specified by <literal>id</literal>, using the <literal>user-service-ref</literal>
                 attribute, or will be located automatically in the application context. </para>
             <section>
                 <title>The <literal>&lt;attribute-exchange></literal> Element</title>
@@ -666,7 +661,7 @@
                 <para> If you only have one server defined in your application context, the other
                     LDAP namespace-defined beans will use it automatically. Otherwise, you can give
                     the element an "id" attribute and refer to it from other namespace beans using
-                    the <literal>server-ref</literal> attribute. This is actually the bean Id of the
+                    the <literal>server-ref</literal> attribute. This is actually the bean <literal>id</literal> of the
                     <literal>ContextSource</literal> instance, if you want to use it in other
                     traditional Spring beans. </para>
             </section>

docs/manual/src/docbook/core-filters.xml

@@ -136,7 +136,7 @@
         </section>
         <section xml:id="access-denied-handler">
             <title><interfacename>AccessDeniedHandler</interfacename></title>
-            <para>What happens if a user is already authenticated an they try to access a protected
+            <para>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
@@ -174,7 +174,7 @@
                 to save the current request before invoking the <interfacename>AuthenticationEntryPoint</interfacename>.
                 This allows the request to be restored after the use has authenticated (see previous overview
                 of <link xlink:href="#tech-intro-web-authentication">web authentication</link>).
-                A typical example would be where the user logs in with a from, and is then redirected to the
+                A typical example would be where the user logs in with a form, and is then redirected to the
                 original URL by the default <classname>SavedRequestAwareAuthenticationSuccessHandler</classname>
                 (see <link xlink:href="#form-login-flow-handling">below</link>).
             </para>

docs/manual/src/docbook/introduction.xml

@@ -38,13 +38,13 @@
             technologies:</para>
         <itemizedlist spacing="compact">
             <listitem>
-                <para>HTTP BASIC authentication headers (an IEFT RFC-based standard)</para>
+                <para>HTTP BASIC authentication headers (an IETF RFC-based standard)</para>
             </listitem>
             <listitem>
-                <para>HTTP Digest authentication headers (an IEFT RFC-based standard)</para>
+                <para>HTTP Digest authentication headers (an IETF RFC-based standard)</para>
             </listitem>
             <listitem>
-                <para>HTTP X.509 client certificate exchange (an IEFT RFC-based standard)</para>
+                <para>HTTP X.509 client certificate exchange (an IETF RFC-based standard)</para>
             </listitem>
             <listitem>
                 <para>LDAP (a very common approach to cross-platform authentication needs,
@@ -62,7 +62,7 @@
             </listitem>
             <listitem>
                 <para>JA-SIG Central Authentication Service (otherwise known as CAS, which is a
-                    popular open source single sign on system)</para>
+                    popular open source single sign-on system)</para>
             </listitem>
             <listitem>
                 <para>Transparent authentication context propagation for Remote Method Invocation
@@ -73,7 +73,7 @@
                     re-authentication for a predetermined period of time)</para>
             </listitem>
             <listitem>
-                <para>Anonymous authentication (allowing every call to automatically assume a
+                <para>Anonymous authentication (allowing every unauthenticated call to automatically assume a
                     particular security identity)</para>
             </listitem>
             <listitem>
@@ -133,9 +133,8 @@
                 <para>Your own authentication systems (see below)</para>
             </listitem>
         </itemizedlist>
-        <para>(* Denotes provided by a third party; check our <link
-            xlink:href="http://acegisecurity.org/powering.html">integration page</link> for links to
-            the latest details)</para>
+        <para>(* Denotes provided by a third party</para>
+        <!-- TODO: Reinstate web link to third-party integrations/users -->
         <para>Many independent software vendors (ISVs) adopt Spring Security because of this
             significant choice of flexible authentication models. Doing so allows them to quickly
             integrate their solutions with whatever their end clients need, without undertaking a
@@ -145,17 +144,9 @@
             Spring Security need to integrate with "legacy" systems that don't follow any particular
             security standards, and Spring Security is happy to "play nicely" with such
             systems.</para>
-        <para>Sometimes the mere process of authentication isn't enough. Sometimes you need to also
-            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. This is especially helpful to protect password recovery processes from brute
-            force attacks, or simply to make it harder for people to duplicate your application's
-            key content. To help you achieve these goals, 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 whether methods can be
+        <para>Irrespective of the authentication mechanism, Spring Security provides a deep set
+            of authorization capabilities. There are three main areas of interest 
+            - authorizing web requests, authorizing whether methods can be
             invoked, and authorizing access to individual domain object instances. To help you
             understand the differences, consider the authorization capabilities found in the Servlet
             Specification web pattern security, EJB Container Managed Security and file system
@@ -300,13 +291,13 @@
                 line that's causing the problem and work out what's happening. The source is the
                 ultimate documentation for a project and often the simplest place to find out how
                 something actually works. </para>
-            <para>To obtain the source for the project trunk, use the following git command:
+            <para>To obtain the source for the project, use the following git command:
                 <programlisting>
   git clone git://git.springsource.org/spring-security/spring-security.git
     </programlisting>
-                You can checkout specific versions from
-                <literal>https://src.springframework.org/svn/spring-security/tags/</literal>.
             </para>
+            <para>This will give you access to the entire project history (including all releases
+            and branches) on your local machine.</para>
         </section>
     </section>
 </chapter>

docs/manual/src/docbook/jaas-auth-provider.xml

@@ -100,7 +100,7 @@ JAASTest {
                 Spring Security, on the other hand, works with
                 <interfacename>Authentication</interfacename> objects. Each
                 <interfacename>Authentication</interfacename> object contains a single principal,
-                and multiple <interfacename>GrantedAuthority</interfacename>[]s. To facilitate
+                and multiple <interfacename>GrantedAuthority</interfacename>s. To facilitate
                 mapping between these different concepts, Spring Security's JAAS package includes an
                 <literal>AuthorityGranter</literal> interface.</para>
 

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

@@ -37,9 +37,9 @@
   xmlns:security="http://www.springframework.org/schema/security"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.springframework.org/schema/beans
-          http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
+          http://www.springframework.org/schema/beans/spring-beans-3.1.xsd
           http://www.springframework.org/schema/security
-          http://www.springframework.org/schema/security/spring-security-3.0.xsd">
+          http://www.springframework.org/schema/security/spring-security-3.1.xsd">
     ...
 </beans>
   ]]></programlisting> In many of the examples you will see (and in the sample) applications, we
@@ -52,9 +52,9 @@
   xmlns:beans="http://www.springframework.org/schema/beans"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.springframework.org/schema/beans
-           http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
+           http://www.springframework.org/schema/beans/spring-beans-3.1.xsd
            http://www.springframework.org/schema/security
-           http://www.springframework.org/schema/security/spring-security-3.0.xsd">
+           http://www.springframework.org/schema/security/spring-security-3.1.xsd">
     ...
 </beans:beans>
 ]]></programlisting> We'll assume this syntax is being used from now on in this chapter. </para>
@@ -888,7 +888,7 @@ List&lt;OpenIDAttribute> attributes = token.getAttributes();</programlisting>The
                 set an alternative for both method and web security. </para>
             <para> For method security, you do this by setting the
                 <literal>access-decision-manager-ref</literal> attribute on
-                <literal>global-method-security</literal> to the Id of the appropriate
+                <literal>global-method-security</literal> to the <literal>id</literal> of the appropriate
                 <interfacename>AccessDecisionManager</interfacename> bean in the application
                 context: <programlisting language="xml"><![CDATA[
   <global-method-security access-decision-manager-ref="myAccessDecisionManagerBean">

docs/manual/src/docbook/remember-me-authentication.xml

@@ -125,7 +125,7 @@
                 <literal>TokenBasedRememberMeServices</literal> requires A UserDetailsService from
                 which it can retrieve the username and password for signature comparison purposes,
                 and generate the <literal>RememberMeAuthenticationToken</literal> to contain the
-                correct <interfacename>GrantedAuthority</interfacename>[]s. Some sort of logout
+                correct <interfacename>GrantedAuthority</interfacename>s. Some sort of logout
                 command should be provided by the application that invalidates the cookie if the
                 user requests this. <classname>TokenBasedRememberMeServices</classname> also
                 implements Spring Security's <interfacename>LogoutHandler</interfacename> interface

docs/manual/src/docbook/samples.xml

@@ -8,9 +8,9 @@
         distribution zip file. You can either build the others yourself, or you can obtain the war
         files individually from the central Maven repository. We'd recommend the former. You can get
         the source as described in <link xlink:href="#get-source">the introduction</link> and it's
-        easy to build the project using Maven. There is more information on the project web site at
+        easy to build the project yourself. There's more information on the project web site at
         <link xlink:href="http://www.springsource.org/security/">
-        http://www.springsource.org/security/ </link> if you need it. All paths referred to in this
+        http://www.springsource.org/security/ </link>. All paths referred to in this
         chapter are relative to the project source directory. </para>
     <section xml:id="tutorial-sample">
         <title>Tutorial Sample</title>
@@ -35,7 +35,7 @@
             administer a simple database of contacts (the domain objects).</para>
         <para>To deploy, simply copy the WAR file from Spring Security distribution into your
             container’s <literal>webapps</literal> directory. The war should be called
-            <filename>spring-security-samples-contacts-3.0.x.war</filename> (the appended version
+            <filename>spring-security-samples-contacts-3.1.x.war</filename> (the appended version
             number will vary depending on what release you are using). </para>
         <para>After starting your container, check the application can load. Visit
             <literal>http://localhost:8080/contacts</literal> (or whichever URL is appropriate for