SEC-1493: Documentation of support for erasing credentials.

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

@@ -524,7 +524,7 @@
             </para>
         </section>
     </section>
-    <section>
+    <section xml:id="nsa-authentication">
         <title>Authentication Services</title>
         <para> Before Spring Security 3.0, an <interfacename>AuthenticationManager</interfacename>
             was automatically registered internally. Now you must register one explicitly using the
@@ -545,6 +545,11 @@
                 described in the <link xlink:href="#ns-auth-manager">namespace introduction</link>.
                 All elements which create <interfacename>AuthenticationProvider</interfacename>
                 instances should be children of this element.</para>
+            <para>
+                The element also exposes an <literal>erase-credentials</literal> attribute which maps
+                to the <literal>eraseCredentialsAfterAuthentication</literal> property of
+                the <classname>ProviderManager</classname>. This is discussed in the
+                <link xlink:href="#core-services-erasing-credentials">Core Services</link> chapter.</para>
             <section>
                 <title>The <literal>&lt;authentication-provider&gt;</literal> Element</title>
                 <para> Unless used with a <literal>ref</literal> attribute, this element is

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

@@ -71,6 +71,28 @@
             concerned about this, because if you forget to register a suitable provider, you'll
             simply receive a <literal>ProviderNotFoundException</literal> when an attempt to
             authenticate is made.</para>
+        <section xml:id="core-services-erasing-credentials">
+            <title>Erasing Credentials on Successful Authentication</title>
+            <para>
+                By default (from Spring Security 3.1 onwards) the <classname>ProviderManager</classname>
+                will attempt to clear any sensitive credentials information from the
+                <interfacename>Authentication</interfacename> object which is returned by a successful
+                authentication request. This prevents information like passwords being retained longer
+                than necessary.
+            </para>
+            <para>
+                This may cause issues when you are using a cache of user objects, for example, to
+                improve performance in a stateless application. If the <interfacename>Authentication</interfacename>
+                contains a reference to an object in the cache (such as a <interfacename>UserDetails</interfacename>
+                instance) and this has its credentials removed, then it will no longer be possible to authenticate
+                against the cached value. You need to take this into account if you are using a cache. An obvious
+                solution is to make a copy of the object first, either in the cache implementation or in
+                the <interfacename>AuthenticationProvider</interfacename> which creates the returned
+                <interfacename>Authentication</interfacename> object. Alternatively, you can disable the
+                <literal>eraseCredentialsAfterAuthentication</literal> property on <classname>ProviderManager</classname>.
+                See the Javadoc for more information.
+            </para>
+        </section>
         <section xml:id="core-services-dao-provider">
             <title><literal>DaoAuthenticationProvider</literal></title>
             <para>The simplest <interfacename>AuthenticationProvider</interfacename> implemented by