SEC-1493: Documentation of support for erasing credentials.

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

@@ -459,7 +459,12 @@
         instance for use in your own configuration. Its use is 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>
+          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 shorthand for configuring a

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

@@ -35,7 +35,7 @@
                 <classname>SecurityContext</classname>. </para>
         <para> If you are using the namespace, an instance of
                 <classname>ProviderManager</classname> is created and maintained internally, and
-            you add providers to it by using the namespace authentication provider elements 
+            you add providers to it by using the namespace authentication provider elements
             (see <link xlink:href="#ns-auth-manager">the namespace chapter</link>). In this
             case, you should not declare a <classname>ProviderManager</classname> bean in your
             application context. However, if you are not using the namespace then you would declare
@@ -99,6 +99,28 @@
                 repository. These will be discussed in more detail <link
                     xlink:href="core-services-password-encodin">below</link>. </para>
         </section>
+        <section xml:id="core-services-erasing-credentials">
+            <title>Erasing Credentials on Successful Authentication</title>
+            <para>
+                From Spring Security 3.0.3, you can configure 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, to prevent information like passwords being retained longer
+                than necessary. This feature is controlled by the <literal>eraseCredentialsAfterAuthentication</literal>
+                property on <classname>ProviderManager</classname>. It is off by default.
+                See the Javadoc for more information.
+            </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.
+            </para>
+        </section>
     </section>
     <section>
         <title><interfacename>UserDetailsService</interfacename> Implementations</title>