SEC-786: Added information on the need ofor a UserDetailsService if using auto-config/remember-me

src/docbkx/namespace-config.xml

@@ -115,7 +115,7 @@
     </section>
   </section>
   <section xml:id="ns-getting-started">
-    <title>Getting Started with Security Namespace Cofiguration</title>
+    <title>Getting Started with Security Namespace Configuration</title>
     <para>
       In this section, we'll look at how you can build up a namespace configuration to use some of the main
       features of the framework. Let's assume you initially want to get up and running as quickly as possible 
@@ -230,6 +230,17 @@
           <link xlink:href="#anonymous">anonymous authentication</link>, basic authentication, logout handling and remember-me services
           respectively. They each have attributes which can be used to alter their behaviour.
         </para>
+        <tip>
+          <title><literal>auto-config</literal> Requires a UserDetailsService</title>
+          <para>An error can occur when using auto-config without a <interfacename>UserDetailsService</interfacename> in
+          your application context (for example, if you are using LDAP authentication). 
+          This is because remember-me is automatically enabled when <literal>auto-config="true"</literal> and it requires
+            an authentication mechanism which uses a <interfacename>UserDetailsService</interfacename> to function (see 
+            the <link xlink:href="#remember-me">Remember-me chapter</link> for more details). If you have an error caused
+            by a missing <interfacename>UserDetailsService</interfacename> then try removing the <literal>auto-config</literal> 
+            setting (and any <literal>remember-me</literal> setting you might have).  
+          </para>
+        </tip>
       </section>
       <section xml:id="ns-form-and-basic">
         <title>Form and Basic Login Options</title>
@@ -325,6 +336,11 @@
   <section xml:id="ns-web-advanced">
     <title>Advanced Web Features</title>
     
+    <section xml:id="ns-remember-me">
+      <title>Remember-Me Authentication</title>
+      <para>See the separate <link xlink:href="#remember-me">Remember-Me chapter</link> for information on remember-me namespace configuration.</para>
+    </section>
+
     <section xml:id="ns-requires-channel">
       <title>Adding HTTP/HTTPS Channel Security</title>
       <para>If your application supports both HTTP and HTTPS, and you require that particular URLs can only be accessed over HTTPS, then this is

src/docbkx/remember-me-authentication.xml

@@ -14,7 +14,13 @@
         these operations to take place, and has two concrete
         remember-me implementations. One uses hashing to preserve the security of
         cookie-based tokens and the other uses a database or other persistent storage
-        mechanism to store the generated tokens.</para>
+        mechanism to store the generated tokens. </para>
+    <para>
+        Note that both implemementations require a <interfacename>UserDetailsService</interfacename>. 
+        If you are using an authentication provider which doesn't use a <interfacename>UserDetailsService</interfacename> 
+        (for example, the LDAP provider) then it won't work unless you also have a <interfacename>UserDetailsService</interfacename> 
+        bean in your application context.
+    </para>
 </section>
     
     <section xml:id="remember-me-hash-token">
@@ -52,10 +58,9 @@
   ]]>
                 </programlisting>
             It is automatically enabled for you if you are using the <link xlink:href="ns-auto-config">auto-config</link> setting.
-            Note that remember-me requires a <interfacename>UserDetailsService</interfacename>. If you are using an authentication
+            The <interfacename>UserDetailsService</interfacename> will normally be selected automatically. If you have more than one in
-            provider which doesn't use a <interfacename>UserDetailsService</interfacename> (for example, the LDAP provider) then it won't work
+            your application context, you need to specify which one should be used with the <literal>user-service-ref</literal> attribute,
-            unless you also have a <interfacename>UserDetailsService</interfacename> bean in your application context. If you have more than one, 
+            where the value is the name of your <interfacename>UserDetailsService</interfacename> bean.
-            you need to specify which one should be used with the <literal>user-service-ref</literal> attribute. 
           </para>
     </section>
     
@@ -78,7 +83,7 @@
     create table persistent_logins (username varchar(64) not null, series varchar(64) primary key, token varchar(64) not null, last_used timestamp not null)    
 </programlisting>                
         </para>
-        <!-- TODO: Add more info on the implementation and behaviour when tokens are stolen etc -->
+        <!-- TODO: Add more info on the implementation and behaviour when tokens are stolen etc. Also some info for admins on invalidating tokens using key, or deleting info from db -->
     </section>    
 
 <section xml:id="remember-me-impls">