diff --git a/src/docbkx/ldap-auth-provider.xml b/src/docbkx/ldap-auth-provider.xml index e5d75cde90..a216db355a 100644 --- a/src/docbkx/ldap-auth-provider.xml +++ b/src/docbkx/ldap-auth-provider.xml @@ -17,16 +17,132 @@ 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. + (Mozilla, JLDAP etc.) in the LDAP provider, but extensive use is made of Spring LDAP, so + some familiarity with that project may be useful if you plan on adding your own + customizations. - + Using LDAP with Spring Security - The main LDAP provider class is + LDAP authentication in Spring Security can be roughly divided into the following + stages. + + Obtaining the unique LDAP Distinguished Name, or DN, from + the login name. This will often mean performing a search in the directory, + unless the exact mapping of usernames to DNs is known in advance. + + + Authenticating the user, either by binding as that user or by performing a + remote compare operation of the user's password against the + password attribute in the directory entry for the DN. + + + Loading the list of authorities for the user. + + The exception is when the LDAP directory is just being used to retrieve + user information and authenticate against it locally. This may not be possible as + directories are often set up with limited read access for attributes such as user + passwords. + We will look at some configuration scenarios below. For full information on available + configuration options, please consult the security namespace schema (information from + which should be available in your XML editor). + + + Configuring an LDAP Server + The first thing you need to do is configure the server against which authentication + should take place. This is done using the <ldap-server> element + from the security namespace. This can be configured to point at an external LDAP server, + using the url attribute: + ]]> + + Using an Embedded Test Server + The <ldap-server> element can also be used to create an + embedded server, which can be very useful for testing and demonstrations. In this + case you use it without the url attribute: + ]]> Here we've specified that the root DIT of the directory should be + dc=springframework,dc=org, which is the default. Used this way, + the namespace parser will create an embedded Apache Directory server and scan the + classpath for any LDIF files, which it will attempt to load into the server. You can + customize this behaviour using the ldif attribute, which defines + an LDIF resource to be loaded: + ]]> This makes it a lot easier to get up and running with LDAP, since it can be + inconvenient to work all the time with an external server. It also insulates the + user from the complex bean configuration needed to wire up an Apache Directory + server. Using plain Spring Beans the configuration would be much more cluttered. You + must have the necessary Apache Directory dependency jars available for your + application to use. These can be obtained from the LDAP sample application. + + + Using Bind Authentication + This is the most common LDAP authentication scenario. + + ]]> This simple example would obtain the DN for the user by + substituting the user login name in the supplied pattern and attempting to bind as + that user with the login password. This is OK if all your users are stored under a + single node in the directory. If instead you wished to configure an LDAP search + filter to locate the user, you could use the following: + + ]]> If used with the server definition above, this would + perform a search under the DN ou=people,dc=springframework,dc=org + using the value of the user-search-filter attribute as a filter. + Again the user login name is substituted for the parameter in the filter name. If + user-search-base isn't supplied, the search will be performed + from the root. + + + Loading Authorities + How authorities are loaded from groups in the LDAP directory is controlled by the + following attributes. + + group-search-base. Defines the part of the + directory tree under which group searches should be performed. + + + group-role-attribute. The attribute which contains + the name of the authority defined by the group entry. Defaults to + cn + + + group-search-filter. The filter which is used to + search for group membership. The default is uniqueMember={0}, corresponding to the groupOfUniqueMembers LDAP class. In this case, the + substituted parameter is the full distinguished name of the user. The + parameter {1} can be used if you want to filter on + the login name. + + So if we used the following configuration + + ]]> and authenticated successfully as user ben, + the subsequent loading of authorities would perform a search under the directory + entry ou=groups,dc=springframework,dc=org, looking for entries + which contain the attribute uniqueMember with value uid=ben,ou=people,dc=springframework,dc=org. For more information on + loading authorities, see the Javadoc for the + DefaultLdapAuthoritiesPopulator class. + + + + Implementation Classes + The namespace configuration options we've used above are simple to use and much more + concise than using Spring beans explicitly. There are situations when you may need to + know how to configure Spring Security LDAP directly in your application context. You may + wish to customize the behaviour of some of the classes, for example. If you're happy using + namespace configuration then you can skip this section and the next one. + + + + The main LDAP + provider class is org.springframework.security.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 + This bean doesn't actually do much itself but 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. @@ -61,10 +177,9 @@ 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 + 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=springframework,dc=org, and have a + LDAP server with the URL ldap://monkeymachine.co.uk/dc=springframework,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=springframework,dc=org. Each configured @@ -93,27 +208,18 @@ 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 + to be supplied with a SpringSecurityContextSource + which is an extension of Spring LDAP's ContextSource. + Unless you have special requirements, you will usually + configure a DefaultSpringSecurityContextSource 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. + server (instead of binding anonymously). For more information read the Javadoc for + this class and for Spring LDAP's AbstractContextSource. + LDAP Search Objects @@ -134,61 +240,58 @@ >{0} which will be replaced with the user's login name. - - - Configuration - 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: - + + Spring Bean Configuration + A typical configuration, using some of the beans we've discussed here, might look + like this: + - cn=manager,dc=springframework,dc=org - password - - - - - - - - - + + - + uid={0},ou=people - - ou=groups - ou + + + - + ]]> - This would set up the provider to access an LDAP server with URL + This would set up the provider to access an LDAP server with URL ldap://monkeymachine:389/dc=springframework,dc=org. - Authentication will be performed by attempting to bind with the DN uid=<user-login-name>,ou=people,dc=springframework,dc=org. After - successful authentication, roles will be assigned to the user by searching under the DN + Authentication will be performed by attempting to bind with the DN uid=<user-login-name>,ou=people,dc=springframework,dc=org. After + successful authentication, roles will be assigned to the user by searching under the DN ou=groups,dc=springframework,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 authenticator would then call the search object to - obtain the correct user's DN before attempting to bind as this user. + To configurae a user search object, which uses the filter + (uid=<user-login-name>) for use instead of the + DN-pattern (or in addition to it), you would configure the following bean + + + + + + ]]> + + and use it by setting the authenticator's userSearch property. The authenticator + would then call the search object to obtain the correct user's DN before attempting to bind as this user. + +