Release numbering section.

doc/docbook/acegi.xml

@@ -95,27 +95,23 @@
       although equivalent functionality is fully accommodated by Acegi
       Security.</para>
 
-      <sect2 id="security-introduction-status">
-        <title>Current Status</title>
-
-        <para>The Acegi Security System for Spring is widely used by members
-        of the Spring Community. The APIs are considered stable and only minor
-        changes are expected. Having said that, like many other projects we
-        need to strike a balance between backward compatibility and
-        improvement. Effective version 0.6.1, Acegi Security uses the Apache
-        Portable Runtime Project versioning guidelines, available from
-        <literal>http://apr.apache.org/versioning.html</literal>.</para>
-
-        <para>We are now at release 0.9.0, and a lot of effort has been made
-        to implement all non-backward compatible changes either in or before
-        this release. Some minor improvements are currently intended to the
-        1.0.0 release, although they will in no way modify the project's
-        central interfaces or classes. Users of Acegi Security System for
-        Spring should therefore be comfortable depending on the current
-        version of the project in their applications. Please note that we will
-        be changing the package name prefix in the 1.0.0 release, but this
-        should be a simple "find and replace" type operation in your
-        code.</para>
+      <sect2 id="security-introduction-release-numbering">
+        <title>Release Numbering</title>
+
+        <para>It is useful to understand how the Acegi Security release
+        numbers work, as it will help you identify the effort (or lack
+        thereof) involved in migrating to future releases of the project.
+        Officially, we use the Apache Portable Runtime Project versioning
+        guidelines, which can be viewed at
+        <literal>http://apr.apache.org/versioning.html</literal>. We quote the
+        introduction contained on that page for your convenience:</para>
+
+        <para><quote>Versions are denoted using a standard triplet of
+        integers: MAJOR.MINOR.PATCH. The basic intent is that MAJOR versions
+        are incompatible, large-scale upgrades of the API. MINOR versions
+        retain source and binary compatibility with older minor versions, and
+        changes in the PATCH level are perfectly compatible, forwards and
+        backwards.</quote></para>
       </sect2>
     </sect1>
 
@@ -4070,8 +4066,6 @@ $CATALINA_HOME/bin/startup.sh</programlisting></para>
         process, is only invoked if the certificate is rejected and it always
         returns an error to the user. With a suitable bean configuration, the
         normal sequence of events is as follows <orderedlist>
-             
-
             <listitem>
               <para>The <classname>X509ProcessingFilter</classname> extracts
               the certificate from the request and uses it as the credentials
@@ -4080,8 +4074,6 @@ $CATALINA_HOME/bin/startup.sh</programlisting></para>
               The request is passed to the authentication manager.</para>
             </listitem>
 
-             
-
             <listitem>
               <para>The <classname>X509AuthenticationProvider</classname>
               receives the token. Its main concern is to obtain the user
@@ -4109,8 +4101,6 @@ $CATALINA_HOME/bin/startup.sh</programlisting></para>
               load the user information.<!-- TODO: Give email matching as an example --></para>
             </listitem>
 
-             
-
             <listitem>
               <para>If everything has gone smoothly then there should be a
               valid <classname>Authentication</classname> object in the secure
@@ -4120,7 +4110,6 @@ $CATALINA_HOME/bin/startup.sh</programlisting></para>
               <classname>X509ProcessingFilterEntryPoint</classname> which
               returns a 403 error (forbidden) to the user.</para>
             </listitem>
-             
           </orderedlist></para>
       </sect2>
 
@@ -4176,218 +4165,252 @@ $CATALINA_HOME/bin/startup.sh</programlisting></para>
 
       <sect2 id="security-ldap-overview">
         <title>Overview</title>
-        <para>LDAP is often used by organizations as a central repository for user information and
-          as an authentication service. It can also be used to store the role information for
-          application users. </para>
-        <para>There are many different scenarios for how an LDAP server may be configured so the
-          Acegi LDAP provider is fully configurable. It uses separate strategy interfaces for
-          authentication and role retrieval and provides default implementations which can be
-          configured to handle a wide range of situations. </para>
-        <para>You should be familiar with LDAP before trying to use it with Acegi. The following
-          link provides a good introduction to the concepts involved and a guide to setting up a
-          directory using the free LDAP server OpenLDAP: <ulink
-            url="http://www.zytrax.com/books/ldap/"/>. Some familiarity with the JNDI APIs used to
-          access LDAP from Java may also be useful. We don't use any third-party LDAP libraries
-          (Mozilla/Netscape, JLDAP etc.) in the LDAP provider. </para>
+
+        <para>LDAP is often used by organizations as a central repository for
+        user information and as an authentication service. It can also be used
+        to store the role information for application users.</para>
+
+        <para>There are many different scenarios for how an LDAP server may be
+        configured so the Acegi LDAP provider is fully configurable. It uses
+        separate strategy interfaces for authentication and role retrieval and
+        provides default implementations which can be configured to handle a
+        wide range of situations.</para>
+
+        <para>You should be familiar with LDAP before trying to use it with
+        Acegi. The following link provides a good introduction to the concepts
+        involved and a guide to setting up a directory using the free LDAP
+        server OpenLDAP: <ulink
+        url="http://www.zytrax.com/books/ldap/"></ulink>. Some familiarity
+        with the JNDI APIs used to access LDAP from Java may also be useful.
+        We don't use any third-party LDAP libraries (Mozilla/Netscape, JLDAP
+        etc.) in the LDAP provider.</para>
 
         <sect3 id="security-ldap-details">
           <title>LDAP with Acegi Security</title>
-  
+
           <para>The main LDAP provider class is
-            <classname>org.acegisecurity.providers.ldap.LdapAuthenticationProvider</classname>. This
-            bean doesn't actually do much itself other than implement the
-            <methodname>retrieveUser</methodname> method required by its base class,
-            <classname>AbstractUserDetailsAuthenticationProvider</classname>. It delegates the work
-            to two other beans, an <interfacename>LdapAuthenticator</interfacename> and an
-            <interfacename>LdapAuthoritiesPopulator</interfacename> which are responsible for
-            authenticating the user and retrieving the user's set of
-            <interfacename>GrantedAuthority</interfacename>s respectively. 
-          </para>
+          <classname>org.acegisecurity.providers.ldap.LdapAuthenticationProvider</classname>.
+          This bean doesn't actually do much itself other than implement the
+          <methodname>retrieveUser</methodname> method required by its base
+          class,
+          <classname>AbstractUserDetailsAuthenticationProvider</classname>. It
+          delegates the work to two other beans, an
+          <interfacename>LdapAuthenticator</interfacename> and an
+          <interfacename>LdapAuthoritiesPopulator</interfacename> which are
+          responsible for authenticating the user and retrieving the user's
+          set of <interfacename>GrantedAuthority</interfacename>s
+          respectively.</para>
         </sect3>
-      
       </sect2>
-        
+
       <sect2 id="security-ldap-authenticators">
-          <title>LdapAuthenticator Implementations</title>
-          <para> The authenticator is also responsible for retrieving any required user attributes.
-            This is because the permissions on the attributes may depend on the type of
-            authentication being used. For example, if binding as the user, it may be necessary to
-            read them with the user's own permissions. </para>
-          <para> There are currently two authentication strategies supplied with Acegi Security: 
-            <itemizedlist>
-              <listitem>
-                <para>Authentication directly to the LDAP server ("bind" authentication).</para>
-              </listitem>
-              <listitem>
-                <para>Password comparison, where the password supplied by the user is compared with
-                  the one stored in the repository. This can either be done by retrieving the value
-                  of the password attribute and checking it locally or by performing an LDAP
-                  "compare" operation, where the supplied password is passed to the server for
-                  comparison and the real password value is never retrieved.</para>
-              </listitem>
-            </itemizedlist>
-          </para>
-          <sect3>
-            <title>Common Functionality</title>
-            <para>Before it is possible to authenticate a user (by either strategy), the
-              distinguished name (DN) has to be obtained from the login name supplied to the
-              application. This can be done either by simple pattern-matching (by setting the
-              <property>setUserDnPatterns</property> array property) or by setting the
-              <property>userSearch</property> property. For the DN pattern-matching approach, a
-              standard Java pattern format is used, and the login name will be substituted for the
-              parameter <parameter>{0}</parameter>. The pattern should be relative to the DN that
-              the configured <interfacename>InitialDirContextFactory</interfacename> will bind to
-              (see the section on <link linkend="security-ldap-dircontextfactory">connecting to the
-              LDAP server</link> for more information on this). For example, if you are using an
-              LDAP server specified by the URL
-              <literal>ldap://monkeymachine.co.uk/dc=acegisecurity,dc=org</literal>, and have a
-              pattern <literal>uid={0},ou=greatapes</literal>, then a login name of "gorilla" will
-              map to a DN <literal>uid=gorilla,ou=greatapes,dc=acegisecurity,dc=org</literal>. Each
-              configured DN pattern will be tried in turn until a match is found. For information on
-              using a search, see the section on <link linkend="security-ldap-searchobjects">search
-              objects</link> below. A combination of the two approaches can also be used - the
-              patterns will be checked first and if no matching DN is found, the search will be
-              used. </para>
-          </sect3>
-          <sect3>
-            <title>BindAuthenticator</title>
-            <para>The class
-                <classname>org.acegisecurity.providers.ldap.authenticator.BindAuthenticator</classname>
-              implements the bind authentication strategy. It simply attempts to bind as the user.
-            </para>
-          </sect3>
-          <sect3>
-            <title>PasswordComparisonAuthenticator</title>
-            <para>The class
-                <classname>org.acegisecurity.providers.ldap.authenticator.PasswordComparisonAuthenticator</classname>
-              implements the password comparison authentication strategy.</para>
-          </sect3>
-          <sect3 id="security-ldap-authenticators-adauth">
-            <title>Active Directory Authentication</title>
-            <para>In addition to standard LDAP authentication (binding with a DN), Active Directory
-              has its own non-standard syntax for user authentication.
-            </para>
-          </sect3>
-        
+        <title>LdapAuthenticator Implementations</title>
+
+        <para>The authenticator is also responsible for retrieving any
+        required user attributes. This is because the permissions on the
+        attributes may depend on the type of authentication being used. For
+        example, if binding as the user, it may be necessary to read them with
+        the user's own permissions.</para>
+
+        <para>There are currently two authentication strategies supplied with
+        Acegi Security: <itemizedlist>
+            <listitem>
+              <para>Authentication directly to the LDAP server ("bind"
+              authentication).</para>
+            </listitem>
+
+            <listitem>
+              <para>Password comparison, where the password supplied by the
+              user is compared with the one stored in the repository. This can
+              either be done by retrieving the value of the password attribute
+              and checking it locally or by performing an LDAP "compare"
+              operation, where the supplied password is passed to the server
+              for comparison and the real password value is never
+              retrieved.</para>
+            </listitem>
+          </itemizedlist></para>
+
+        <sect3>
+          <title>Common Functionality</title>
+
+          <para>Before it is possible to authenticate a user (by either
+          strategy), the distinguished name (DN) has to be obtained from the
+          login name supplied to the application. This can be done either by
+          simple pattern-matching (by setting the
+          <property>setUserDnPatterns</property> array property) or by setting
+          the <property>userSearch</property> property. For the DN
+          pattern-matching approach, a standard Java pattern format is used,
+          and the login name will be substituted for the parameter
+          <parameter>{0}</parameter>. The pattern should be relative to the DN
+          that the configured
+          <interfacename>InitialDirContextFactory</interfacename> will bind to
+          (see the section on <link
+          linkend="security-ldap-dircontextfactory">connecting to the LDAP
+          server</link> for more information on this). For example, if you are
+          using an LDAP server specified by the URL
+          <literal>ldap://monkeymachine.co.uk/dc=acegisecurity,dc=org</literal>,
+          and have a pattern <literal>uid={0},ou=greatapes</literal>, then a
+          login name of "gorilla" will map to a DN
+          <literal>uid=gorilla,ou=greatapes,dc=acegisecurity,dc=org</literal>.
+          Each configured DN pattern will be tried in turn until a match is
+          found. For information on using a search, see the section on <link
+          linkend="security-ldap-searchobjects">search objects</link> below. A
+          combination of the two approaches can also be used - the patterns
+          will be checked first and if no matching DN is found, the search
+          will be used.</para>
+        </sect3>
+
+        <sect3>
+          <title>BindAuthenticator</title>
+
+          <para>The class
+          <classname>org.acegisecurity.providers.ldap.authenticator.BindAuthenticator</classname>
+          implements the bind authentication strategy. It simply attempts to
+          bind as the user.</para>
+        </sect3>
+
+        <sect3>
+          <title>PasswordComparisonAuthenticator</title>
+
+          <para>The class
+          <classname>org.acegisecurity.providers.ldap.authenticator.PasswordComparisonAuthenticator</classname>
+          implements the password comparison authentication strategy.</para>
+        </sect3>
+
+        <sect3 id="security-ldap-authenticators-adauth">
+          <title>Active Directory Authentication</title>
+
+          <para>In addition to standard LDAP authentication (binding with a
+          DN), Active Directory has its own non-standard syntax for user
+          authentication.</para>
+        </sect3>
       </sect2>
-        
+
       <sect2 id="security-ldap-dircontextfactory">
         <title>Connecting to the LDAP Server</title>
-        <para>The beans discussed above have to be able to connect to the server. They both have
-          to be supplied with an <interfacename>InitialDirContextFactory</interfacename> instance.
-          Unless you have special requirements, this will usually be a
-            <classname>DefaultInitialDirContextFactory</classname> bean, which can be configured
-          with the URL of your LDAP server and optionally with the username and password of a
-          "manager" user which will be used by default when binding to the server (instead of
-          binding anonymously). It currently supports "simple" LDAP authentication.</para>
-          <para><classname>DefaultInitialDirContextFactory</classname> uses Sun's JNDI LDAP
-          implementation by default (the one that comes with the JDK). It also supports the
-          built in connection pooling offered by Sun's provider. Connections which are obtained
-          either anonymously or with the "manager" user's identity will be pooled automatically.
-          Connections obtained with a specific user's identity will not be pooled. Connection
-          pooling can be disabled completely by setting the <property>useConnectionPool</property>
-          property to false.
-        </para>
-        <para> See the <ulink
-            url="http://acegisecurity.org/multiproject/acegi-security/xref/org/acegisecurity/providers/ldap/DefaultInitialDirContextFactory.html"
-            >class Javadoc and source</ulink> for more information on this bean and its properties.
-        </para>
-      </sect2> 
-      
+
+        <para>The beans discussed above have to be able to connect to the
+        server. They both have to be supplied with an
+        <interfacename>InitialDirContextFactory</interfacename> instance.
+        Unless you have special requirements, this will usually be a
+        <classname>DefaultInitialDirContextFactory</classname> bean, which can
+        be configured with the URL of your LDAP server and optionally with the
+        username and password of a "manager" user which will be used by
+        default when binding to the server (instead of binding anonymously).
+        It currently supports "simple" LDAP authentication.</para>
+
+        <para><classname>DefaultInitialDirContextFactory</classname> uses
+        Sun's JNDI LDAP implementation by default (the one that comes with the
+        JDK). It also supports the built in connection pooling offered by
+        Sun's provider. Connections which are obtained either anonymously or
+        with the "manager" user's identity will be pooled automatically.
+        Connections obtained with a specific user's identity will not be
+        pooled. Connection pooling can be disabled completely by setting the
+        <property>useConnectionPool</property> property to false.</para>
+
+        <para>See the <ulink
+        url="http://acegisecurity.org/multiproject/acegi-security/xref/org/acegisecurity/providers/ldap/DefaultInitialDirContextFactory.html">class
+        Javadoc and source</ulink> for more information on this bean and its
+        properties.</para>
+      </sect2>
+
       <sect2 id="security-ldap-searchobjects">
         <title>LDAP Search Objects</title>
-        <para>Often more a more complicated strategy than simple DN-matching is required to locate
-        a user entry in the directory. This can be encapsulated in an
-        <interfacename>LdapUserSearch</interfacename> instance which can be supplied to the
-          authenticator implementations, for example, to allow them to locate a user. The supplied
-          implementation is <classname>FilterBasedLdapUserSearch</classname>.
-        </para>
-        
+
+        <para>Often more a more complicated strategy than simple DN-matching
+        is required to locate a user entry in the directory. This can be
+        encapsulated in an <interfacename>LdapUserSearch</interfacename>
+        instance which can be supplied to the authenticator implementations,
+        for example, to allow them to locate a user. The supplied
+        implementation is
+        <classname>FilterBasedLdapUserSearch</classname>.</para>
+
         <sect3>
           <title><classname>FilterBasedLdapUserSearch</classname></title>
-          <para>This bean uses an LDAP filter to match the user object in the directory. The
-            process is explained in the Javadoc for the corresponding search method on the 
-            <ulink
-              url="http://java.sun.com/j2se/1.4.2/docs/api/javax/naming/directory/DirContext.html#search(javax.naming.Name,%20java.lang.String,%20java.lang.Object[],%20javax.naming.directory.SearchControls)">JDK
-              DirContext class</ulink>.              
-            As explained there, the search filter can be supplied with parameters. For this class,
-            the only valid parameter is <parameter>{0}</parameter> which will be replaced with
-            the user's login name.
-          </para>
+
+          <para>This bean uses an LDAP filter to match the user object in the
+          directory. The process is explained in the Javadoc for the
+          corresponding search method on the <ulink
+          url="http://java.sun.com/j2se/1.4.2/docs/api/javax/naming/directory/DirContext.html#search(javax.naming.Name,%20java.lang.String,%20java.lang.Object[],%20javax.naming.directory.SearchControls)">JDK
+          DirContext class</ulink>. As explained there, the search filter can
+          be supplied with parameters. For this class, the only valid
+          parameter is <parameter>{0}</parameter> which will be replaced with
+          the user's login name.</para>
         </sect3>
-     </sect2>
+      </sect2>
 
       <sect2 id="security-ldap-config">
         <title>Configuring the LDAP Provider</title>
 
-        <para>There is a version of the 
-          <link linkend="security-sample">Contacts Sample Application</link> which
-          uses LDAP. You can copy the beans and filter setup from this as a starting
-          point for configuring your own application.
-        </para>
-        <para>
-          A typical configuration, using some of the beans we've discussed above, might look like this:
-          <programlisting>
-    &lt;bean id=&quot;initialDirContextFactory&quot; 
-            class=&quot;org.acegisecurity.providers.ldap.DefaultInitialDirContextFactory&quot;&gt;
-      &lt;constructor-arg value=&quot;ldap://monkeymachine:389/dc=acegisecurity,dc=org&quot;/&gt;
-      &lt;property name=&quot;managerDn&quot;&gt;&lt;value&gt;cn=manager,dc=acegisecurity,dc=org&lt;/value&gt;&lt;/property&gt;
-      &lt;property name=&quot;managerPassword&quot;&gt;&lt;value&gt;password&lt;/value&gt;&lt;/property&gt;
+        <para>There is a version of the <link
+        linkend="security-sample">Contacts Sample Application</link> which
+        uses LDAP. You can copy the beans and filter setup from this as a
+        starting point for configuring your own application.</para>
+
+        <para>A typical configuration, using some of the beans we've discussed
+        above, might look like this: <programlisting>
+    &lt;bean id="initialDirContextFactory" 
+            class="org.acegisecurity.providers.ldap.DefaultInitialDirContextFactory"&gt;
+      &lt;constructor-arg value="ldap://monkeymachine:389/dc=acegisecurity,dc=org"/&gt;
+      &lt;property name="managerDn"&gt;&lt;value&gt;cn=manager,dc=acegisecurity,dc=org&lt;/value&gt;&lt;/property&gt;
+      &lt;property name="managerPassword"&gt;&lt;value&gt;password&lt;/value&gt;&lt;/property&gt;
     &lt;/bean&gt;
 
-    &lt;bean id=&quot;userSearch&quot;
-            class=&quot;org.acegisecurity.providers.ldap.search.FilterBasedLdapUserSearch&quot;&gt;
-      &lt;constructor-arg index=&quot;0&quot;&gt;
+    &lt;bean id="userSearch"
+            class="org.acegisecurity.providers.ldap.search.FilterBasedLdapUserSearch"&gt;
+      &lt;constructor-arg index="0"&gt;
         &lt;value&gt;&lt;/value&gt;
       &lt;/constructor-arg&gt;
-      &lt;constructor-arg index=&quot;1&quot;&gt;
+      &lt;constructor-arg index="1"&gt;
         &lt;value&gt;(uid={0})&lt;/value&gt;
       &lt;/constructor-arg&gt;
-      &lt;constructor-arg index=&quot;2&quot;&gt;
-        &lt;ref local=&quot;initialDirContextFactory&quot; /&gt;
+      &lt;constructor-arg index="2"&gt;
+        &lt;ref local="initialDirContextFactory" /&gt;
       &lt;/constructor-arg&gt;            
-      &lt;property name=&quot;searchSubtree&quot;&gt;
+      &lt;property name="searchSubtree"&gt;
         &lt;value&gt;true&lt;/value&gt;
       &lt;/property&gt;            
     &lt;/bean&gt;            
             
-    &lt;bean id=&quot;ldapAuthProvider&quot; 
-            class=&quot;org.acegisecurity.providers.ldap.LdapAuthenticationProvider&quot;&gt;
+    &lt;bean id="ldapAuthProvider" 
+            class="org.acegisecurity.providers.ldap.LdapAuthenticationProvider"&gt;
       &lt;constructor-arg&gt;
-        &lt;bean class=&quot;org.acegisecurity.providers.ldap.authenticator.BindAuthenticator&quot;&gt;
-           &lt;constructor-arg&gt;&lt;ref local=&quot;initialDirContextFactory&quot;/&gt;&lt;/constructor-arg&gt;
-           &lt;property name=&quot;userDnPatterns&quot;&gt;&lt;list&gt;&lt;value&gt;uid={0},ou=people&lt;/value&gt;&lt;/list&gt;&lt;/property&gt;
+        &lt;bean class="org.acegisecurity.providers.ldap.authenticator.BindAuthenticator"&gt;
+           &lt;constructor-arg&gt;&lt;ref local="initialDirContextFactory"/&gt;&lt;/constructor-arg&gt;
+           &lt;property name="userDnPatterns"&gt;&lt;list&gt;&lt;value&gt;uid={0},ou=people&lt;/value&gt;&lt;/list&gt;&lt;/property&gt;
         &lt;/bean&gt;
       &lt;/constructor-arg&gt;
       &lt;constructor-arg&gt;
-        &lt;bean class=&quot;org.acegisecurity.providers.ldap.populator.DefaultLdapAuthoritiesPopulator&quot;&gt;
-           &lt;constructor-arg&gt;&lt;ref local=&quot;initialDirContextFactory&quot;/&gt;&lt;/constructor-arg&gt;
+        &lt;bean class="org.acegisecurity.providers.ldap.populator.DefaultLdapAuthoritiesPopulator"&gt;
+           &lt;constructor-arg&gt;&lt;ref local="initialDirContextFactory"/&gt;&lt;/constructor-arg&gt;
            &lt;constructor-arg&gt;&lt;value&gt;ou=groups&lt;/value&gt;&lt;/constructor-arg&gt;
-           &lt;property name=&quot;groupRoleAttribute&quot;&gt;&lt;value&gt;ou&lt;/value&gt;&lt;/property&gt;
+           &lt;property name="groupRoleAttribute"&gt;&lt;value&gt;ou&lt;/value&gt;&lt;/property&gt;
         &lt;/bean&gt;
       &lt;/constructor-arg&gt;
     &lt;/bean&gt;
   
-          </programlisting>
-
-          This would set up the provider to access an LDAP server with URL
-          <literal>ldap://monkeymachine:389/dc=acegisecurity,dc=org</literal>. Authentication will be performed by
-          attempting to bind with the DN <literal>uid=&lt;user-login-name&gt;,ou=people,dc=acegisecurity,dc=org</literal>.
-          After successful authentication, roles will be assigned to the user by searching under the DN
-          <literal>ou=groups,dc=acegisecurity,dc=org</literal> with the default filter <literal>(member=&lt;user's-DN&gt;)</literal>.
-          The role name will be taken from the <quote>ou</quote> attribute of each match.
-        </para>
-        <para>
-          We've also included the configuration for a user search object, which uses the filter
-          <literal>(uid=&lt;user-login-name&gt;)</literal>. This could be used
-          instead of the DN-pattern (or in addition to it), by setting the authenticator's 
-          <property>userSearch</property> property. The autheticator would then call the search
-          object to obtain the correct user's DN before attempting to bind as this user.
-        </para>
+          </programlisting> This would set up the provider to access an LDAP
+        server with URL
+        <literal>ldap://monkeymachine:389/dc=acegisecurity,dc=org</literal>.
+        Authentication will be performed by attempting to bind with the DN
+        <literal>uid=&lt;user-login-name&gt;,ou=people,dc=acegisecurity,dc=org</literal>.
+        After successful authentication, roles will be assigned to the user by
+        searching under the DN
+        <literal>ou=groups,dc=acegisecurity,dc=org</literal> with the default
+        filter <literal>(member=&lt;user's-DN&gt;)</literal>. The role name
+        will be taken from the <quote>ou</quote> attribute of each
+        match.</para>
+
+        <para>We've also included the configuration for a user search object,
+        which uses the filter
+        <literal>(uid=&lt;user-login-name&gt;)</literal>. This could be used
+        instead of the DN-pattern (or in addition to it), by setting the
+        authenticator's <property>userSearch</property> property. The
+        autheticator would then call the search object to obtain the correct
+        user's DN before attempting to bind as this user.</para>
       </sect2>
+    </sect1>
 
-    </sect1>    
-    
     <sect1 id="security-channels">
       <title>Channel Security</title>
 
@@ -5394,12 +5417,12 @@ INSERT INTO acl_permission VALUES (null, 6, 'scott', 1);</programlisting></para>
       <title>Further Information</title>
 
       <para>Questions and comments on the Acegi Security System for Spring are
-      welcome. Please use the Spring Community Forum web site at
-      <ulink url="http://forum.springframework.org"></ulink>. You're also welcome
-      to join the acegisecurity-developer mailing list. Our project home page
+      welcome. Please use the Spring Community Forum web site at <ulink
+      url="http://forum.springframework.org"></ulink>. You're also welcome to
+      join the acegisecurity-developer mailing list. Our project home page
       (where you can obtain the latest release of the project and access to
-      CVS, mailing lists, forums etc) is at
-      <ulink url="http://acegisecurity.org"></ulink>.</para>
+      CVS, mailing lists, forums etc) is at <ulink
+      url="http://acegisecurity.org"></ulink>.</para>
     </sect1>
   </chapter>
 </book>