Some doc clarifications on the use of UserDetailService vs AuthenticationProvider.

docs/faq/src/docbook/faq.xml

@@ -428,6 +428,25 @@
                     are marked as "optional" in the Spring Security POM files will have to be
                     added to your own pom.xml file if you need them. </para></answer>
             </qandaentry>
+            <qandaentry xml:id="faq-what-is-userdetailservice">
+                <question><para>What is a <literal>UserDetailsService</literal> and do I need one?</para></question>
+                <answer>
+                    <para><interfacename>UserDetailsService</interfacename> is a DAO interface for loading data
+                    that is specific to a user account. It has no other function other to load that
+                    data for use by other components within the framework. It is not responsible for
+                    authenticating the user. Authenticating a user with a username/password
+                    combination is most commonly performed by the <classname>DaoAuthenticationProvider</classname>,
+                    which is injected with a <interfacename>UserDetailsService</interfacename> to allow
+                    it to load the password (and other data) for a user in order to compare it with the
+                    submitted value.</para>
+                    <para>
+                    If you want to customize the authentication process then you should implement
+                    <interfacename>AuthenticationProvider</interfacename> yourself. See this
+                    <link xlink:href="http://blog.springsource.com/2010/08/02/spring-security-in-google-app-engine/">
+                    blog article</link> for an example integrating Spring Security authentication with
+                    Google App Engine.
+                </para></answer>
+            </qandaentry>
         </qandadiv>
     </qandaset>
     </section>

docs/manual/src/docbook/technical-overview.xml

@@ -83,13 +83,13 @@ if (principal instanceof UserDetails) {
                     <interfacename>UserDetails</interfacename> as the principal. </para>
             </section>
         </section>
-        <section>
+        <section xml:id="tech-userdetailsservice">
             <title>The UserDetailsService</title>
             <para>Another item to note from the above code fragment is that you can obtain a
                 principal from the <interfacename>Authentication</interfacename> object. The
                 principal is just an <literal>Object</literal>. Most of the time this can be cast
                 into a <interfacename>UserDetails</interfacename> object.
-                <interfacename>UserDetails</interfacename> is a central interface in Spring
+                <interfacename>UserDetails</interfacename> is a core interface in Spring
                 Security. It represents a principal, but in an extensible and application-specific
                 way. Think of <interfacename>UserDetails</interfacename> as the adapter between your
                 own user database and what Spring Security needs inside the
@@ -126,6 +126,16 @@ if (principal instanceof UserDetails) {
                 <interfacename>UserDetailsService</interfacename> returns can always be obtained
                 from the <classname>SecurityContextHolder</classname> using the above code fragment.
             </para>
+            <note>
+                <para>There is often some confusion about <interfacename>UserDetailsService</interfacename>.
+                    It is purely a DAO for user data and performs no other function other than to supply that data
+                    to other components within the framework. In particular, it <emphasis>does not</emphasis>
+                    authenticate the user, which is done by the <interfacename>AuthenticationManager</interfacename>.
+                    In many cases it makes more sense to
+                    <link xlink:href="#core-services-authentication-manager">implement <interfacename>AuthenticationProvider</interfacename></link>
+                    directly if you require a custom authentication process.
+                </para>
+            </note>
         </section>
         <section xml:id="tech-granted-authority">
             <title>GrantedAuthority</title>