Expanded Javadoc.

core/src/main/java/org/acegisecurity/providers/ldap/LdapAuthenticationProvider.java

@@ -27,7 +27,8 @@ import org.springframework.util.Assert;
 import javax.naming.directory.Attributes;
 
 /**
- * The class responsible for LDAP authentication.
+ * An {@link org.acegisecurity.providers.AuthenticationProvider} implementation that
+ * provides integration with an LDAP server. 
  *
  * <p>
  * There are many ways in which an LDAP directory can be configured so this class
@@ -63,6 +64,42 @@ import javax.naming.directory.Attributes;
  * for example from a database.
  * </p>
  *
+ * <h3>Configuration</h3>
+ * A simple configuration might be as follows:
+ * <pre>
+ *    &lt;bean id="initialDirContextFactory" class="org.acegisecurity.providers.ldap.DefaultInitialDirContextFactory">
+ *      &lt;constructor-arg value="ldap://monkeymachine:389/dc=acegisecurity,dc=org"/>
+ *      &lt;property name="managerDn">&lt;value>cn=manager,dc=acegisecurity,dc=org&lt;/value>&lt;/property>
+ *      &lt;property name="managerPassword">&lt;value>password&lt;/value>&lt;/property>
+ *    &lt;/bean>
+ *
+ *    &lt;bean id="ldapAuthProvider" class="org.acegisecurity.providers.ldap.LdapAuthenticationProvider">
+ *    &lt;constructor-arg>
+ *      &lt;bean class="org.acegisecurity.providers.ldap.authenticator.BindAuthenticator">
+ *         &lt;constructor-arg>&lt;ref local="initialDirContextFactory"/>&lt;/constructor-arg>
+ *         &lt;property name="userDnPatterns">&lt;list>&lt;value>uid={0},ou=people&lt;/value>&lt;/list>&lt;/property>
+ *      &lt;/bean>
+ *    &lt;/constructor-arg>
+ *    &lt;constructor-arg>
+ *      &lt;bean class="org.acegisecurity.providers.ldap.populator.DefaultLdapAuthoritiesPopulator">
+ *         &lt;constructor-arg>&lt;ref local="initialDirContextFactory"/>&lt;/constructor-arg>
+ *         &lt;constructor-arg>&lt;value>ou=groups&lt;/value>&lt;/constructor-arg>
+ *         &lt;property name="groupRoleAttribute">&lt;value>ou&lt;/value>&lt;/property>
+ *      &lt;/bean>
+ *    &lt;/constructor-arg>
+ *  &lt;/bean>
+ * </pre>
+ * <p>
+ * This would set up the provider to access an LDAP server with URL
+ * <tt>ldap://monkeymachine:389/dc=acegisecurity,dc=org</tt>. Authentication will be performed by
+ * attempting to bind with the DN <tt>uid=&lt;user-login-name&gt;,ou=people,dc=acegisecurity,dc=org</tt>.
+ * After successful authentication, roles will be assigned to the user by searching under the DN
+ * <tt>ou=groups,dc=acegisecurity,dc=org</tt> with the default filter <tt>(member=&lt;user's-DN&gt;)</tt>.
+ * The role name will be taken from the "ou" attribute of each match.
+ * </p>
+ *
+ * @see org.acegisecurity.providers.ldap.authenticator.BindAuthenticator
+ * @see org.acegisecurity.providers.ldap.populator.DefaultLdapAuthoritiesPopulator
  *
  * @author Luke Taylor
  * @version $Id$

core/src/main/java/org/acegisecurity/providers/ldap/authenticator/AbstractLdapAuthenticator.java

@@ -25,6 +25,8 @@ import java.util.List;
 import java.util.ArrayList;
 
 /**
+ * Base class for the authenticator implementations.
+ *
  * @author Luke Taylor
  * @version $Id$
  */
@@ -33,11 +35,23 @@ public abstract class AbstractLdapAuthenticator implements LdapAuthenticator,
 
     //~ Instance fields ========================================================
 
-    //private String[] userDnPattern = null;
-    private MessageFormat[] userDnFormat = null;
     private InitialDirContextFactory initialDirContextFactory;
+
+    //private String[] userDnPattern = null;
+
+    /** Stores the patterns which are used as potential DN matches */
+    private MessageFormat[] userDnFormat = null;
+
+    /** Optional search object which can be used to locate a user when a simple DN match isn't sufficient */
     private LdapUserSearch userSearch;
+
+    /** The attributes which will be retrieved from the directory. Null means all attributes */
     private String[] userAttributes = null;
+
+    /**
+     * The suffix to be added to the DN patterns, worked out internally from the root DN of the
+     * configured InitialDirContextFactory.
+     */
     private String dnSuffix = "";
 
     //~ Constructors ===========================================================

core/src/main/java/org/acegisecurity/providers/ldap/populator/DefaultLdapAuthoritiesPopulator.java

@@ -84,11 +84,22 @@ import java.util.HashSet;
  * setting the <tt>groupRoleAttribute</tt> property (the default is "cn").
  * </p>
  * <p>
+ * The configuration below shows how the group searc might be performed with the above schema.
  * <pre>
  * &lt;bean id="ldapAuthoritiesPopulator" class="org.acegisecurity.providers.ldap.populator.DefaultLdapAuthoritiesPopulator">
- * TODO
+ *   &lt;constructor-arg>&lt;ref local="initialDirContextFactory"/>&lt;/constructor-arg>
+ *   &lt;constructor-arg>&lt;value>ou=groups&lt;/value>&lt;/constructor-arg>
+ *   &lt;property name="groupRoleAttribute">&lt;value>ou&lt;/value>&lt;/property>
+ *
+ * &lt;!-- the follwing properties are shown with their default values -->
+ *
+ *   &lt;property name="searchSubTree">&lt;value>false&lt;/value>&lt;/property>
+ *   &lt;property name="rolePrefix">&lt;value>ROLE_&lt;/value>&lt;/property>
+ *   &lt;property name="convertToUpperCase">&lt;value>true&lt;/value>&lt;/property>
  * &lt;/bean>
  * </pre>
+ * A search for roles for user "uid=ben,ou=people,dc=acegisecurity,dc=org" would return the single
+ * granted authority "ROLE_DEVELOPER".
  * </p>
  *
  *