From 49bec559a96572e34f2ec17f8ed23aad307e4575 Mon Sep 17 00:00:00 2001
From: Luke Taylor <luke.taylor@springsource.com>
Date: Tue, 29 Apr 2008 10:57:52 +0000
Subject: [PATCH] SEC-804: Added notes to LDAP section to explain how to
 customize returned UserDetails

---
 src/docbkx/ldap-auth-provider.xml | 33 +++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/src/docbkx/ldap-auth-provider.xml b/src/docbkx/ldap-auth-provider.xml
index ebceeb80aa..1d64aa6302 100644
--- a/src/docbkx/ldap-auth-provider.xml
+++ b/src/docbkx/ldap-auth-provider.xml
@@ -384,5 +384,38 @@
                 property. The authenticator would then call the search object to obtain the correct
                 user's DN before attempting to bind as this user.</para>
         </section>
+        <section>
+            <title>LDAP Attributes and Customized UserDetails</title>
+            <para>
+                The net result of an authentication using <classname>LdapAuthenticationProvider</classname> is the
+                same as a normal Spring Security authentication using the standard <interfacename>UserDetailsService</interfacename>
+                interface. A <interfacename>UserDetails</interfacename> object is created and stored in the 
+                returned <interfacename>Authentication</interfacename> object. As with using a 
+                <interfacename>UserDetailsService</interfacename>, a common requirement is to be able to customize this
+                implementation and add extra properties. When using LDAP, these will normally be attributes from the user entry.
+                The creation of the <interfacename>UserDetails</interfacename> object is controlled by the provider's 
+                <interfacename>UserDetailsContextMapper</interfacename> strategy, which is responsible for mapping user objects
+                to and from LDAP context data:
+                <programlisting><![CDATA[
+public interface UserDetailsContextMapper {
+    UserDetails mapUserFromContext(DirContextOperations ctx, String username, GrantedAuthority[] authority);
+
+    void mapUserToContext(UserDetails user, DirContextAdapter ctx);
+}]]>                    
+                </programlisting>
+                Only the first method is relevant for authentication. If you provide an implememntation of this, you can
+                control exactly how the UserDetails object is created. The first parameter is an instance of Spring LDAP's
+                <interfacename>DirContextOperations</interfacename> which gives you access to the LDAP attributes which were loaded.
+                The <literal>username</literal> parameter is the name used to authenticate and the final parameter is the list of authorities
+                loaded for the user.
+            </para>
+            <para>
+                The way the context data is loaded varies slightly depending on the type of authentication you are using. With the
+                <classname>BindAuthenticatior</classname>, the context returned from the bind operation will be used to read the attributes, 
+                otherwise the data will be read using the standard context obtained from the configured 
+                <interfacename>ContextSource</interfacename> (when a search is configured to locate the user, 
+                this will be the data returned by the search object).
+            </para>
+        </section>
     </section>
 </chapter>
\ No newline at end of file