diff --git a/doc/docbook/acegi.xml b/doc/docbook/acegi.xml index f1d01bf159..6755b74aab 100644 --- a/doc/docbook/acegi.xml +++ b/doc/docbook/acegi.xml @@ -4090,8 +4090,6 @@ $CATALINA_HOME/bin/startup.sh X509AuthoritiesPopulator. - . - The populator's single method, getUserDetails(X509Certificate @@ -4122,7 +4120,6 @@ $CATALINA_HOME/bin/startup.sh X509ProcessingFilterEntryPoint which returns a 403 error (forbidden) to the user. - @@ -4174,6 +4171,220 @@ $CATALINA_HOME/bin/startup.sh + + LDAP Authentication Provider + + + Overview + 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. + 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. + 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: . 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. + + + LDAP with Acegi Security + + The main LDAP provider class is + org.acegisecurity.providers.ldap.LdapAuthenticationProvider. This + bean doesn't actually do much itself other than implement the + retrieveUser method required by its base class, + AbstractUserDetailsAuthenticationProvider. It delegates the work + to two other beans, an LdapAuthenticator and an + LdapAuthoritiesPopulator which are responsible for + authenticating the user and retrieving the user's set of + GrantedAuthoritys respectively. + + + + + + + LdapAuthenticator Implementations + 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. + There are currently two authentication strategies supplied with Acegi Security: + + + Authentication directly to the LDAP server ("bind" authentication). + + + 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. + + + + + Common Functionality + 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 + setUserDnPatterns array property) or by setting the + userSearch property. For the DN pattern-matching approach, a + standard Java pattern format is used, and the login name will be substituted for the + parameter {0}. The pattern should be relative to the DN that + the configured InitialDirContextFactory will bind to + (see the section on connecting to the + LDAP server for more information on this). For example, if you are using an + LDAP server specified by the URL + ldap://monkeymachine.co.uk/dc=acegisecurity,dc=org, and have a + pattern uid={0},ou=greatapes, then a login name of "gorilla" will + map to a DN uid=gorilla,ou=greatapes,dc=acegisecurity,dc=org. Each + configured DN pattern will be tried in turn until a match is found. For information on + using a search, see the section on search + objects 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. + + + BindAuthenticator + The class + org.acegisecurity.providers.ldap.authenticator.BindAuthenticator + implements the bind authentication strategy. It simply attempts to bind as the user. + + + + PasswordComparisonAuthenticator + The class + org.acegisecurity.providers.ldap.authenticator.PasswordComparisonAuthenticator + implements the password comparison authentication strategy. + + + Active Directory Authentication + In addition to standard LDAP authentication (binding with a DN), Active Directory + has its own non-standard syntax for user authentication. + + + + + + + Connecting to the LDAP Server + The beans discussed above have to be able to connect to the server. They both have + to be supplied with an InitialDirContextFactory instance. + Unless you have special requirements, this will usually be a + DefaultInitialDirContextFactory 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. + DefaultInitialDirContextFactory 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 useConnectionPool + property to false. + + See the class Javadoc and source for more information on this bean and its properties. + + + + + LDAP Search Objects + 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 + LdapUserSearch instance which can be supplied to the + authenticator implementations, for example, to allow them to locate a user. The supplied + implementation is FilterBasedLdapUserSearch. + + + + <classname>FilterBasedLdapUserSearch</classname> + 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 + JDK + DirContext class. + As explained there, the search filter can be supplied with parameters. For this class, + the only valid parameter is {0} which will be replaced with + the user's login name. + + + + + + Configuring the LDAP Provider + + There is a version of the + Contacts Sample Application which + uses LDAP. You can copy the beans and filter setup from this as a starting + point for configuring your own application. + + + A typical configuration, using some of the beans we've discussed above, might look like this: + + <bean id="initialDirContextFactory" class="org.acegisecurity.providers.ldap.DefaultInitialDirContextFactory"> + <constructor-arg value="ldap://monkeymachine:389/dc=acegisecurity,dc=org"/> + <property name="managerDn"><value>cn=manager,dc=acegisecurity,dc=org</value></property> + <property name="managerPassword"><value>password</value></property> + </bean> + + <bean + id="userSearch" + class="org.acegisecurity.providers.ldap.search.FilterBasedLdapUserSearch"> + <property name="searchSubtree"> + <value>true</value> + </property> + <property name="initialDirContextFactory"> + <ref local="initialDirContextFactory" /> + </property> + <property name="searchFilter"> + <value>(uid={0})</value> + </property> + </bean> + + <bean + id="ldapAuthProvider" class="org.acegisecurity.providers.ldap.LdapAuthenticationProvider"> + <constructor-arg> + <bean class="org.acegisecurity.providers.ldap.authenticator.BindAuthenticator"> + <constructor-arg><ref local="initialDirContextFactory"/></constructor-arg> + <property name="userDnPatterns"><list><value>uid={0},ou=people</value></list></property> + </bean> + </constructor-arg> + <constructor-arg> + <bean class="org.acegisecurity.providers.ldap.populator.DefaultLdapAuthoritiesPopulator"> + <constructor-arg><ref local="initialDirContextFactory"/></constructor-arg> + <constructor-arg><value>ou=groups</value></constructor-arg> + <property name="groupRoleAttribute"><value>ou</value></property> + </bean> + </constructor-arg> + </bean> + + + + This would set up the provider to access an LDAP server with URL + ldap://monkeymachine:389/dc=acegisecurity,dc=org. Authentication will be performed by + attempting to bind with the DN uid=<user-login-name>,ou=people,dc=acegisecurity,dc=org. + After successful authentication, roles will be assigned to the user by searching under the DN + ou=groups,dc=acegisecurity,dc=org with the default filter (member=<user's-DN>). + The role name will be taken from the ou attribute of each match. + + + We've also included the configuration for a user search object, which uses the filter + (uid=<user-login-name>). This could be used + instead of the DN-pattern (or in addition to it), by setting the authenticator's + userSearch property. The autheticator would then call the search + object to obtain the correct user's DN before attempting to bind as this user. + + + + + Channel Security @@ -5181,11 +5392,11 @@ INSERT INTO acl_permission VALUES (null, 6, 'scott', 1); Questions and comments on the Acegi Security System for Spring are welcome. Please use the Spring Community Forum web site at - http://forum.springframework.org. You're also welcome + . 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 - http://acegisecurity.sourceforge.net. + . \ No newline at end of file