From 75311bad9adeb156cadc7efe3e7eea0fab9885a7 Mon Sep 17 00:00:00 2001 From: Luke Taylor Date: Fri, 18 Dec 2009 18:04:08 +0000 Subject: [PATCH] LDAP API correction in ref manual --- .../manual/src/docbook/ldap-auth-provider.xml | 381 ++++++++---------- 1 file changed, 163 insertions(+), 218 deletions(-) diff --git a/docs/manual/src/docbook/ldap-auth-provider.xml b/docs/manual/src/docbook/ldap-auth-provider.xml index cde7d95376..d22bf3e350 100644 --- a/docs/manual/src/docbook/ldap-auth-provider.xml +++ b/docs/manual/src/docbook/ldap-auth-provider.xml @@ -15,9 +15,11 @@ configured to handle a wide range of situations. You should be familiar with LDAP before trying to use it with Spring Security. 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: - 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 + setting up a directory using the free LDAP server OpenLDAP: 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, 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. @@ -26,122 +28,89 @@ Using LDAP with Spring Security - - LDAP authentication in Spring Security can be roughly divided into the following stages. - + 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. + 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. + 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 + 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). - + 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: - 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: - 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 + 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: - 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 + ]]> 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. - + application to use. These can be obtained from the LDAP sample application.
Using Bind Authentication - - This is the most common LDAP authentication scenario. - 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: - 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. - + ]]> 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. - + 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 @@ -151,39 +120,32 @@ group-role-attribute. The attribute which contains the name of the authority defined by the group entry. Defaults to - cn + 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. + 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 - 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. - By default the authority names will have the prefix ROLE_ prepended. You can - change this using the role-prefix attribute. If you don't want any prefix, use - role-prefix="none". For more information - on loading authorities, see the Javadoc for the - DefaultLdapAuthoritiesPopulator - class. - + ]]> 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. By default the + authority names will have the prefix ROLE_ prepended. You can + change this using the role-prefix attribute. If you don't want + any prefix, use role-prefix="none". For more information on + loading authorities, see the Javadoc for the + DefaultLdapAuthoritiesPopulator class.
@@ -194,16 +156,13 @@ 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, LdapAuthenticationProvider, + using namespace configuration then you can skip this section and the next one. + The main LDAP provider class, LdapAuthenticationProvider, 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. + LdapAuthenticator and an + LdapAuthoritiesPopulator which are responsible for + authenticating the user and retrieving the user's set of + GrantedAuthoritys respectively.
LdapAuthenticator Implementations @@ -212,10 +171,10 @@ 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 Spring Security: - + There are currently two authentication strategies supplied with Spring Security: - Authentication directly to the LDAP server ("bind" authentication). + Authentication directly to the LDAP server ("bind" + authentication). Password comparison, where the password supplied by the user is @@ -225,8 +184,7 @@ password is passed to the server for comparison and the real password value is never retrieved. - - +
Common Functionality @@ -234,35 +192,31 @@ 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 - SpringSecurityContextSource - 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 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 + 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 + SpringSecurityContextSource 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 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 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. + 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 BindAuthenticator in the package - org.springframework.security.ldap.authentication + org.springframework.security.ldap.authentication implements the bind authentication strategy. It simply attempts to bind as the user.
@@ -270,8 +224,8 @@ PasswordComparisonAuthenticator - The class PasswordComparisonAuthenticator - implements the password comparison authentication strategy. + The class PasswordComparisonAuthenticator implements + the password comparison authentication strategy.
@@ -286,17 +240,14 @@ 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 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). For more information read - the Javadoc for this class and for Spring LDAP's - AbstractContextSource. + 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). For more information read the Javadoc for + this class and for Spring LDAP's AbstractContextSource.
@@ -305,10 +256,9 @@ 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. + LdapUserSearch instance which can be supplied to + the authenticator implementations, for example, to allow them to locate a user. The + supplied implementation is FilterBasedLdapUserSearch.
@@ -317,33 +267,35 @@ </info> <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 - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="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</link>. - 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> + <link xmlns:xlink="http://www.w3.org/1999/xlink" + xlink:href="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</link>. 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> </section> </section> <section xml:id="ldap-authorities"> <title>LdapAuthoritiesPopulator - - After authenticating the user successfully, the LdapAuthenticationProvider - will attempt to load a set of authorities for the user by calling the configured - LdapAuthoritiesPopulator bean. The DefaultLdapAuthoritiesPopulator - is an implementation which will load the authorities by searching the directory for groups of which the user is a member - (typically these will be groupOfNames or groupOfUniqueNames entries in the directory). - Consult the Javadoc for this class for more details on how it works. - - If you want to use LDAP only for authentication, but load the authorities from a difference source (such as a database) - then you can provide your own implementation of this interface and inject that instead. + After authenticating the user successfully, the + LdapAuthenticationProvider will attempt to load a set of + authorities for the user by calling the configured + LdapAuthoritiesPopulator bean. The + DefaultLdapAuthoritiesPopulator is an implementation + which will load the authorities by searching the directory for groups of which the + user is a member (typically these will be groupOfNames or + groupOfUniqueNames entries in the directory). Consult the + Javadoc for this class for more details on how it works. + If you want to use LDAP only for authentication, but load the authorities from a + difference source (such as a database) then you can provide your own implementation + of this interface and inject that instead.
Spring Bean Configuration A typical configuration, using some of the beans we've discussed here, might look - like this: - @@ -370,68 +322,61 @@ ]]> - - This would set up the provider to access an LDAP server with URL - ldap://monkeymachine:389/dc=springframework,dc=org. + 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. + 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. + 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. To configure 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 - (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 BindAuthenticator bean's - userSearch + and use it by setting the + BindAuthenticator bean'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.
LDAP Attributes and Customized UserDetails - - The net result of an authentication using LdapAuthenticationProvider is the - same as a normal Spring Security authentication using the standard UserDetailsService - interface. A UserDetails object is created and stored in the - returned Authentication object. As with using a - UserDetailsService, 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 UserDetails object is controlled by the provider's - UserDetailsContextMapper strategy, which is responsible for mapping user objects - to and from LDAP context data: - The net result of an authentication using + LdapAuthenticationProvider is the same as a normal Spring + Security authentication using the standard + UserDetailsService interface. A + UserDetails object is created and stored in the + returned Authentication object. As with using a + UserDetailsService, 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 + UserDetails object is controlled by the + provider's UserDetailsContextMapper strategy, which + is responsible for mapping user objects to and from LDAP context data: authorities); void mapUserToContext(UserDetails user, DirContextAdapter ctx); }]]> - - Only the first method is relevant for authentication. If you provide an implementation of this interface, you can - control exactly how the UserDetails object is created. The first parameter is an instance of Spring LDAP's - DirContextOperations which gives you access to the LDAP attributes which were loaded. - The username parameter is the name used to authenticate and the final parameter is the list of authorities - loaded for the user. - - - The way the context data is loaded varies slightly depending on the type of authentication you are using. With the - BindAuthenticatior, 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 - ContextSource (when a search is configured to locate the user, - this will be the data returned by the search object). - + Only the first method is relevant for + authentication. If you provide an implementation of this interface, you can control + exactly how the UserDetails object is created. The first parameter is an instance of + Spring LDAP's DirContextOperations which gives you + access to the LDAP attributes which were loaded. The username + parameter is the name used to authenticate and the final parameter is the collection + of authorities loaded for the user. + The way the context data is loaded varies slightly depending on the type of + authentication you are using. With the BindAuthenticatior, + 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 ContextSource (when a search is configured + to locate the user, this will be the data returned by the search object).
- \ No newline at end of file +