Cwikius-Spring/spring-security
1
0
Fork 0
mirror of https://github.com/spring-projects/spring-security.git synced 2025-06-29 15:22:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

Tidying up incorrectly rendered program listing

Browse Source
This commit is contained in:
Luke Taylor 2008-04-05 12:21:45 +00:00
parent b0a892397b
commit f4954d0eda
2 changed files with 325 additions and 224 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

63
src/docbkx/jaas-auth-provider.xml
View File

@ -1,10 +1,8 @@
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="jaas"><info><title>Java Authentication and Authorization Service (JAAS) <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="jaas">
Provider</title></info> <info><title>Java Authentication and Authorization Service (JAAS) Provider</title></info>
<section xml:id="jaas-overview">
<section xml:id="jaas-overview"><info><title>Overview</title></info> <info><title>Overview</title></info>
<para>Spring Security provides a package able to delegate <para>Spring Security provides a package able to delegate
authentication requests to the Java Authentication and Authorization authentication requests to the Java Authentication and Authorization
Service (JAAS). This package is discussed in detail below.</para> Service (JAAS). This package is discussed in detail below.</para>
@ -16,9 +14,8 @@
syntax in order to understand this section.</para> syntax in order to understand this section.</para>
</section> </section>
<section xml:id="jaas-config"><info><title>Configuration</title></info> <section xml:id="jaas-config">
<info><title>Configuration</title></info>
<para>The <literal>JaasAuthenticationProvider</literal> attempts to <para>The <literal>JaasAuthenticationProvider</literal> attempts to
authenticate a user’s principal and credentials through JAAS.</para> authenticate a user’s principal and credentials through JAAS.</para>
@ -36,34 +33,31 @@
above JAAS login configuration file:</para> above JAAS login configuration file:</para>
<para><programlisting> <para><programlisting>
&amp;lt;bean id="jaasAuthenticationProvider" <![CDATA[
class="org.springframework.security.providers.jaas.JaasAuthenticationProvider"&amp;gt; <bean id="jaasAuthenticationProvider"
&amp;lt;property name="loginConfig"&amp;gt; class="org.springframework.security.providers.jaas.JaasAuthenticationProvider">
&amp;lt;value&amp;gt;/WEB-INF/login.conf&amp;lt;/value&amp;gt; <property name="loginConfig" value="/WEB-INF/login.conf"/>
&amp;lt;/property&amp;gt; <property name="loginContextName" value="JAASTest"/>
&amp;lt;property name="loginContextName"&amp;gt; <property name="callbackHandlers">
&amp;lt;value&amp;gt;JAASTest&amp;lt;/value&amp;gt; <list>
&amp;lt;/property&amp;gt; <bean class="org.springframework.security.providers.jaas.JaasNameCallbackHandler"/>
&amp;lt;property name="callbackHandlers"&amp;gt; <bean class="org.springframework.security.providers.jaas.JaasPasswordCallbackHandler"/>
&amp;lt;list&amp;gt; </list>
&amp;lt;bean class="org.springframework.security.providers.jaas.JaasNameCallbackHandler"/&amp;gt; </property>
&amp;lt;bean class="org.springframework.security.providers.jaas.JaasPasswordCallbackHandler"/&amp;gt; <property name="authorityGranters">
&amp;lt;/list&amp;gt; <list>
&amp;lt;/property&amp;gt; <bean class="org.springframework.security.providers.jaas.TestAuthorityGranter"/>
&amp;lt;property name="authorityGranters"&amp;gt; </list>
&amp;lt;list&amp;gt; </property>
&amp;lt;bean class="org.springframework.security.providers.jaas.TestAuthorityGranter"/&amp;gt; </bean>
&amp;lt;/list&amp;gt; ]]>
&amp;lt;/property&amp;gt;
&amp;lt;/bean&amp;gt;
</programlisting></para> </programlisting></para>
<para>The <literal>CallbackHandler</literal>s and <para>The <literal>CallbackHandler</literal>s and
<literal>AuthorityGranter</literal>s are discussed below.</para> <literal>AuthorityGranter</literal>s are discussed below.</para>
<section xml:id="jaas-callbackhandler"><info><title xml:id="jaas-callback-handler">JAAS CallbackHandler</title></info> <section xml:id="jaas-callbackhandler">
<info><title xml:id="jaas-callback-handler">JAAS CallbackHandler</title></info>
<para>Most JAAS <literal>LoginModule</literal>s require a callback <para>Most JAAS <literal>LoginModule</literal>s require a callback
of some sort. These callbacks are usually used to obtain the of some sort. These callbacks are usually used to obtain the
@ -102,7 +96,8 @@
being wrapped.</para> being wrapped.</para>
</section> </section>
<section xml:id="jaas-authoritygranter"><info><title xml:id="jaas-authority-granter">JAAS AuthorityGranter</title></info> <section xml:id="jaas-authoritygranter">
<info><title xml:id="jaas-authority-granter">JAAS AuthorityGranter</title></info>
<para>JAAS works with principals. Even "roles" are represented as <para>JAAS works with principals. Even "roles" are represented as

486
src/docbkx/ldap-auth-provider.xml
View File

@ -1,7 +1,11 @@
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="ldap"><info><title>LDAP Authentication</title></info> <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="ldap">
<info>
<section xml:id="ldap-overview"><info><title>Overview</title></info> <title>LDAP Authentication</title>
</info>
<section xml:id="ldap-overview">
<info>
<title>Overview</title>
</info>
<para>LDAP is often used by organizations as a central repository for user information and <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 as an authentication service. It can also be used to store the role information for
application users.</para> application users.</para>
@ -11,143 +15,205 @@
configured to handle a wide range of situations.</para> configured to handle a wide range of situations.</para>
<para>You should be familiar with LDAP before trying to use it with Spring Security. The <para>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 following link provides a good introduction to the concepts involved and a guide to
setting up a directory using the free LDAP server OpenLDAP: <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.zytrax.com/books/ldap/">http://www.zytrax.com/books/ldap/</uri>. Some familiarity with the JNDI APIs used setting up a directory using the free LDAP server OpenLDAP:
to access LDAP from Java may also be useful. We don't use any third-party LDAP libraries <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.zytrax.com/books/ldap/">http://www.zytrax.com/books/ldap/</uri>.
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 (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 some familiarity with that project may be useful if you plan on adding your own
customizations.</para> customizations.</para>
</section> </section>
<section><info><title>Using LDAP with Spring Security</title></info> <section>
<info>
<para> LDAP authentication in Spring Security can be roughly divided into the following <title>Using LDAP with Spring Security</title>
stages. <orderedlist inheritnum="ignore" continuation="restarts"> </info>
<para>
LDAP authentication in Spring Security can be roughly divided into the following stages.
<orderedlist inheritnum="ignore" continuation="restarts">
<listitem> <listitem>
<para>Obtaining the unique LDAP <quote>Distinguished Name</quote>, or DN, from <para>Obtaining the unique LDAP
the login name. This will often mean performing a search in the directory, <quote>Distinguished Name</quote>, or DN, from the login name. This will
unless the exact mapping of usernames to DNs is known in advance.</para> often mean performing a search in the directory, unless the exact mapping of
usernames to DNs is known in advance.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Authenticating the user, either by binding as that user or by performing a <para>Authenticating the user, either by binding as that user or by performing a
remote <quote>compare</quote> operation of the user's password against the remote
password attribute in the directory entry for the DN.</para> <quote>compare</quote>
operation of the user's password against the password attribute in the
directory entry for the DN.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Loading the list of authorities for the user.</para> <para>Loading the list of authorities for the user.</para>
</listitem> </listitem>
</orderedlist> The exception is when the LDAP directory is just being used to retrieve </orderedlist>
user information and authenticate against it locally. This may not be possible as The exception is when the LDAP directory is just being used to retrieve user information
directories are often set up with limited read access for attributes such as user and authenticate against it locally. This may not be possible as directories are often
passwords. </para> set up with limited read access for attributes such as user passwords.
<para> We will look at some configuration scenarios below. For full information on available </para>
<para>
We will look at some configuration scenarios below. For full information on available
configuration options, please consult the security namespace schema (information from configuration options, please consult the security namespace schema (information from
which should be available in your XML editor). </para> which should be available in your XML editor).
</para>
</section> </section>
<section><info><title>Configuring an LDAP Server</title></info> <section>
<info>
<para> The first thing you need to do is configure the server against which authentication <title>Configuring an LDAP Server</title>
should take place. This is done using the <literal>&lt;ldap-server&gt;</literal> element </info>
from the security namespace. This can be configured to point at an external LDAP server, <para>
using the <literal>url</literal> attribute: <programlisting> The first thing you need to do is configure the server against which authentication
&lt;ldap-server url="ldap://springframework.org:389/dc=springframework,dc=org" /&gt; should take place. This is done using the
</programlisting></para> <literal>&lt;ldap-server&gt;</literal>
<section><info><title>Using an Embedded Test Server</title></info> element from the security namespace. This can be configured to point at an external LDAP
server, using the
<para> The <literal>&lt;ldap-server&gt;</literal> element can also be used to create an <literal>url</literal>
embedded server, which can be very useful for testing and demonstrations. In this attribute:
case you use it without the <literal>url</literal> attribute: <programlisting> <programlisting><![CDATA[
&lt;ldap-server root="dc=springframework,dc=org"/&gt; <ldap-server url="ldap://springframework.org:389/dc=springframework,dc=org" />
</programlisting> Here we've specified that the root DIT of the directory should be ]]>
<quote>dc=springframework,dc=org</quote>, which is the default. Used this way, </programlisting>
the namespace parser will create an embedded Apache Directory server and scan the </para>
<section>
<info>
<title>Using an Embedded Test Server</title>
</info>
<para>
The
<literal>&lt;ldap-server&gt;</literal>
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
<literal>url</literal>
attribute:
<programlisting><![CDATA[
<ldap-server root="dc=springframework,dc=org"/>
]]>
</programlisting>
Here we've specified that the root DIT of the directory should be
<quote>dc=springframework,dc=org</quote>, 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 classpath for any LDIF files, which it will attempt to load into the server. You can
customize this behaviour using the <literal>ldif</literal> attribute, which defines customize this behaviour using the
an LDIF resource to be loaded: <programlisting> <literal>ldif</literal>
&lt;ldap-server ldif="classpath:users.ldif" /&gt; attribute, which defines an LDIF resource to be loaded:
</programlisting> This makes it a lot easier to get up and running with LDAP, since it can be <programlisting><![CDATA[
<ldap-server ldif="classpath:users.ldif" />
]]></programlisting>
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 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 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 server. Using plain Spring Beans the configuration would be much more cluttered. You
must have the necessary Apache Directory dependency jars available for your must have the necessary Apache Directory dependency jars available for your
application to use. These can be obtained from the LDAP sample application. </para> application to use. These can be obtained from the LDAP sample application.
</para>
</section> </section>
<section><info><title>Using Bind Authentication</title></info> <section>
<info>
<para> This is the most common LDAP authentication scenario. <programlisting> <title>Using Bind Authentication</title>
</info>
&lt;ldap-authentication-provider user-dn-pattern="uid={0},ou=people"/&gt; <para>
</programlisting> This simple example would obtain the DN for the user by This is the most common LDAP authentication scenario.
substituting the user login name in the supplied pattern and attempting to bind as <programlisting>
that user with the login password. This is OK if all your users are stored under a <![CDATA[<ldap-authentication-provider user-dn-pattern="uid={0},ou=people"/>
single node in the directory. If instead you wished to configure an LDAP search ]]></programlisting>
filter to locate the user, you could use the following: <programlisting> 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
&lt;ldap-authentication-provider user-search-filter="(uid={0})" user-search-base="ou=people"/&gt; password. This is OK if all your users are stored under a single node in the
</programlisting> If used with the server definition above, this would directory. If instead you wished to configure an LDAP search filter to locate the
perform a search under the DN <literal>ou=people,dc=springframework,dc=org</literal> user, you could use the following:
using the value of the <literal>user-search-filter</literal> attribute as a filter. <programlisting><![CDATA[
Again the user login name is substituted for the parameter in the filter name. If <ldap-authentication-provider user-search-filter="(uid={0})" user-search-base="ou=people"/>
<literal>user-search-base</literal> isn't supplied, the search will be performed ]]></programlisting>
from the root. </para> If used with the server definition above, this would perform a search under the DN
<literal>ou=people,dc=springframework,dc=org</literal>
using the value of the
<literal>user-search-filter</literal>
attribute as a filter. Again the user login name is substituted for the parameter in
the filter name. If
<literal>user-search-base</literal>
isn't supplied, the search will be performed from the root.
</para>
</section> </section>
<section><info><title>Loading Authorities</title></info> <section>
<info>
<para> How authorities are loaded from groups in the LDAP directory is controlled by the <title>Loading Authorities</title>
following attributes. <itemizedlist> </info>
<para>
How authorities are loaded from groups in the LDAP directory is controlled by the
following attributes.
<itemizedlist>
<listitem> <listitem>
<para><literal>group-search-base</literal>. Defines the part of the <para>
directory tree under which group searches should be performed.</para> <literal>group-search-base</literal>. Defines the part of the directory
tree under which group searches should be performed.</para>
</listitem> </listitem>
<listitem> <listitem>
<para><literal>group-role-attribute</literal>. The attribute which contains <para>
<literal>group-role-attribute</literal>. The attribute which contains
the name of the authority defined by the group entry. Defaults to the name of the authority defined by the group entry. Defaults to
<literal>cn</literal></para> <literal>cn</literal>
</para>
</listitem> </listitem>
<listitem> <listitem>
<para><literal>group-search-filter</literal>. The filter which is used to <para>
search for group membership. The default is <literal>uniqueMember={0}</literal>, corresponding to the <literal>groupOfUniqueMembers</literal> LDAP class. In this case, the <literal>group-search-filter</literal>. The filter which is used to
substituted parameter is the full distinguished name of the user. The search for group membership. The default is
parameter <literal>{1}</literal> can be used if you want to filter on <literal>uniqueMember={0}</literal>, corresponding to the
the login name.</para> <literal>groupOfUniqueMembers</literal>
LDAP class. In this case, the substituted parameter is the full
distinguished name of the user. The parameter
<literal>{1}</literal>
can be used if you want to filter on the login name.</para>
</listitem> </listitem>
</itemizedlist> So if we used the following configuration <programlisting> </itemizedlist>
So if we used the following configuration
&lt;ldap-authentication-provider user-dn-pattern="uid={0},ou=people group-search-base="ou=groups" /&gt; <programlisting><![CDATA[
</programlisting> and authenticated successfully as user <quote>ben</quote>, <ldap-authentication-provider user-dn-pattern="uid={0},ou=people group-search-base="ou=groups" />
the subsequent loading of authorities would perform a search under the directory ]]></programlisting>
entry <literal>ou=groups,dc=springframework,dc=org</literal>, looking for entries and authenticated successfully as user
which contain the attribute <literal>uniqueMember</literal> with value <literal>uid=ben,ou=people,dc=springframework,dc=org</literal>. For more information on <quote>ben</quote>, the subsequent loading of authorities would perform a search
loading authorities, see the Javadoc for the under the directory entry
<classname>DefaultLdapAuthoritiesPopulator</classname> class. </para> <literal>ou=groups,dc=springframework,dc=org</literal>, looking for entries which
contain the attribute
<literal>uniqueMember</literal>
with value
<literal>uid=ben,ou=people,dc=springframework,dc=org</literal>. For more information
on loading authorities, see the Javadoc for the
<classname>DefaultLdapAuthoritiesPopulator</classname>
class.
</para>
</section> </section>
</section> </section>
<section><info><title>Implementation Classes</title></info> <section>
<info>
<title>Implementation Classes</title>
</info>
<para>The namespace configuration options we've used above are simple to use and much more <para>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 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 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 wish to customize the behaviour of some of the classes, for example. If you're happy
namespace configuration then you can skip this section and the next one. using namespace configuration then you can skip this section and the next one.
</para> </para>
<para> <para>
The main LDAP provider class is
The main LDAP <classname>org.springframework.security.providers.ldap.LdapAuthenticationProvider</classname>.
provider class is
<classname>org.springframework.security.providers.ldap.LdapAuthenticationProvider</classname>.
This bean doesn't actually do much itself but delegates the work to two other beans, an This bean doesn't actually do much itself but delegates the work to two other beans, an
<interfacename>LdapAuthenticator</interfacename> and an <interfacename>LdapAuthenticator</interfacename>
<interfacename>LdapAuthoritiesPopulator</interfacename> which are responsible for and an
authenticating the user and retrieving the user's set of <interfacename>LdapAuthoritiesPopulator</interfacename>
which are responsible for authenticating the user and retrieving the user's set of
<interfacename>GrantedAuthority</interfacename>s respectively.</para> <interfacename>GrantedAuthority</interfacename>s respectively.</para>
<section xml:id="ldap-ldap-authenticators"><info><title>LdapAuthenticator Implementations</title></info> <section xml:id="ldap-ldap-authenticators">
<info>
<title>LdapAuthenticator Implementations</title>
</info>
<para>The authenticator is also responsible for retrieving any required user attributes. <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 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 authentication being used. For example, if binding as the user, it may be necessary
to read them with the user's own permissions.</para> to read them with the user's own permissions.</para>
<para>There are currently two authentication strategies supplied with Spring Security: <itemizedlist> <para>There are currently two authentication strategies supplied with Spring Security:
<itemizedlist>
<listitem> <listitem>
<para>Authentication directly to the LDAP server ("bind" <para>Authentication directly to the LDAP server ("bind" authentication).</para>
authentication).</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Password comparison, where the password supplied by the user is <para>Password comparison, where the password supplied by the user is
@ -157,127 +223,167 @@
password is passed to the server for comparison and the real password password is passed to the server for comparison and the real password
value is never retrieved.</para> value is never retrieved.</para>
</listitem> </listitem>
</itemizedlist></para> </itemizedlist>
<section xml:id="ldap-ldap-authenticators-common"><info><title>Common Functionality</title></info> </para>
<section xml:id="ldap-ldap-authenticators-common">
<info>
<title>Common Functionality</title>
</info>
<para>Before it is possible to authenticate a user (by either strategy), the <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 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 application. This can be done either by simple pattern-matching (by setting the
<property>setUserDnPatterns</property> array property) or by setting the <property>setUserDnPatterns</property>
<property>userSearch</property> property. For the DN pattern-matching array property) or by setting the
approach, a standard Java pattern format is used, and the login name will be <property>userSearch</property>
substituted for the parameter <parameter>{0}</parameter>. The pattern should be property. For the DN pattern-matching approach, a standard Java pattern format
relative to the DN that the configured is used, and the login name will be substituted for the parameter
<interfacename>InitialDirContextFactory</interfacename> will bind to (see the <parameter>{0}</parameter>. The pattern should be relative to the DN that the
section on <link linkend="ldap-context-source">connecting to the LDAP configured
server</link> for more information on this). For example, if you are using an <interfacename>InitialDirContextFactory</interfacename>
LDAP server with the URL <literal>ldap://monkeymachine.co.uk/dc=springframework,dc=org</literal>, and have a will bind to (see the section on
pattern <literal>uid={0},ou=greatapes</literal>, then a login name of "gorilla" <link linkend="ldap-context-source">connecting to the LDAP server</link>
will map to a DN <literal>uid=gorilla,ou=greatapes,dc=springframework,dc=org</literal>. Each configured for more information on this). For example, if you are using an LDAP server with
DN pattern will be tried in turn until a match is found. For information on the URL
using a search, see the section on <link linkend="ldap-searchobjects">search <literal>ldap://monkeymachine.co.uk/dc=springframework,dc=org</literal>, and
objects</link> below. A combination of the two approaches can also be used - have a pattern
the patterns will be checked first and if no matching DN is found, the search <literal>uid={0},ou=greatapes</literal>, then a login name of "gorilla" will map
will be used.</para> to a DN
<literal>uid=gorilla,ou=greatapes,dc=springframework,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="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>
</section> </section>
<section xml:id="ldap-ldap-authenticators-bind"><info><title>BindAuthenticator</title></info> <section xml:id="ldap-ldap-authenticators-bind">
<info>
<title>BindAuthenticator</title>
</info>
<para>The class <para>The class
<classname>org.springframework.security.providers.ldap.authenticator.BindAuthenticator</classname> <classname>org.springframework.security.providers.ldap.authenticator.BindAuthenticator</classname>
implements the bind authentication strategy. It simply attempts to bind as the implements the bind authentication strategy. It simply attempts to bind as the
user.</para> user.</para>
</section> </section>
<section xml:id="ldap-ldap-authenticators-password"><info><title>PasswordComparisonAuthenticator</title></info> <section xml:id="ldap-ldap-authenticators-password">
<info>
<title>PasswordComparisonAuthenticator</title>
</info>
<para>The class <para>The class
<classname>org.springframework.security.providers.ldap.authenticator.PasswordComparisonAuthenticator</classname> <classname>org.springframework.security.providers.ldap.authenticator.PasswordComparisonAuthenticator</classname>
implements the password comparison authentication strategy.</para> implements the password comparison authentication strategy.</para>
</section> </section>
<section xml:id="ldap-ldap-authenticators-active-directory"><info><title>Active Directory Authentication</title></info> <section xml:id="ldap-ldap-authenticators-active-directory">
<info>
<title>Active Directory Authentication</title>
</info>
<para>In addition to standard LDAP authentication (binding with a DN), Active <para>In addition to standard LDAP authentication (binding with a DN), Active
Directory has its own non-standard syntax for user authentication.</para> Directory has its own non-standard syntax for user authentication.</para>
</section> </section>
</section> </section>
<section xml:id="ldap-context-source"><info><title>Connecting to the LDAP Server</title></info> <section xml:id="ldap-context-source">
<info>
<title>Connecting to the LDAP Server</title>
</info>
<para>The beans discussed above have to be able to connect to the server. They both have <para>The beans discussed above have to be able to connect to the server. They both have
to be supplied with a <interfacename>SpringSecurityContextSource</interfacename> to be supplied with a
which is an extension of Spring LDAP's <interfacename>ContextSource</interfacename>. <interfacename>SpringSecurityContextSource</interfacename>
Unless you have special requirements, you will usually which is an extension of Spring LDAP's
configure a <classname>DefaultSpringSecurityContextSource</classname> bean, which can be <interfacename>ContextSource</interfacename>. Unless you have special requirements,
configured with the URL of your LDAP server and optionally with the username and you will usually configure a
password of a "manager" user which will be used by default when binding to the <classname>DefaultSpringSecurityContextSource</classname>
server (instead of binding anonymously). For more information read the Javadoc for bean, which can be configured with the URL of your LDAP server and optionally with
this class and for Spring LDAP's <classname>AbstractContextSource</classname>. 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
<classname>AbstractContextSource</classname>.
</para> </para>
</section> </section>
<section xml:id="ldap-searchobjects"><info><title>LDAP Search Objects</title></info> <section xml:id="ldap-searchobjects">
<info>
<title>LDAP Search Objects</title>
</info>
<para>Often more a more complicated strategy than simple DN-matching is required to <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 locate a user entry in the directory. This can be encapsulated in an
<interfacename>LdapUserSearch</interfacename> instance which can be supplied to <interfacename>LdapUserSearch</interfacename>
the authenticator implementations, for example, to allow them to locate a user. The instance which can be supplied to the authenticator implementations, for example, to
supplied implementation is <classname>FilterBasedLdapUserSearch</classname>.</para> allow them to locate a user. The supplied implementation is
<section xml:id="ldap-searchobjects-filter"><info><title xml:id="ldap-searchobjects-filter-based"><classname>FilterBasedLdapUserSearch</classname></title></info> <classname>FilterBasedLdapUserSearch</classname>.</para>
<section xml:id="ldap-searchobjects-filter">
<info>
<title xml:id="ldap-searchobjects-filter-based">
<classname>FilterBasedLdapUserSearch</classname>
</title>
</info>
<para>This bean uses an LDAP filter to match the user object in the directory. The <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 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 <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
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> 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> </section>
<section xml:id="ldap-bean-config"><info><title>Spring Bean Configuration</title></info> <section xml:id="ldap-bean-config">
<info>
<title>Spring Bean Configuration</title>
</info>
<para>A typical configuration, using some of the beans we've discussed here, might look <para>A typical configuration, using some of the beans we've discussed here, might look
like this: <programlisting> like this:
<programlisting>
&lt;bean id="contextSource" <![CDATA[
class="org.springframework.security.ldap.DefaultSpringSecurityContextSource"&gt; <bean id="contextSource"
&lt;constructor-arg value="ldap://monkeymachine:389/dc=springframework,dc=org"/&gt; class="org.springframework.security.ldap.DefaultSpringSecurityContextSource">
&lt;property name="userDn" value="cn=manager,dc=springframework,dc=org"/&gt; <constructor-arg value="ldap://monkeymachine:389/dc=springframework,dc=org"/>
&lt;property name="password" value="password"/&gt; <property name="userDn" value="cn=manager,dc=springframework,dc=org"/>
&lt;/bean&gt; <property name="password" value="password"/>
</bean>
&lt;bean id="ldapAuthProvider" <bean id="ldapAuthProvider"
class="org.springframework.security.providers.ldap.LdapAuthenticationProvider"&gt; class="org.springframework.security.providers.ldap.LdapAuthenticationProvider">
&lt;constructor-arg&gt; <constructor-arg>
&lt;bean class="org.springframework.security.providers.ldap.authenticator.BindAuthenticator"&gt; <bean class="org.springframework.security.providers.ldap.authenticator.BindAuthenticator">
&lt;constructor-arg ref="contextSource"/&gt; <constructor-arg ref="contextSource"/>
&lt;property name="userDnPatterns"&gt;&lt;list&gt;&lt;value&gt;uid={0},ou=people&lt;/value&gt;&lt;/list&gt;&lt;/property&gt; <property name="userDnPatterns"><list><value>uid={0},ou=people</value></list></property>
&lt;/bean&gt; </bean>
&lt;/constructor-arg&gt; </constructor-arg>
&lt;constructor-arg&gt; <constructor-arg>
&lt;bean class="org.springframework.security.ldap.populator.DefaultLdapAuthoritiesPopulator"&gt; <bean class="org.springframework.security.ldap.populator.DefaultLdapAuthoritiesPopulator">
&lt;constructor-arg ref="contextSource"/&gt; <constructor-arg ref="contextSource"/>
&lt;constructor-arg value="ou=groups"/&gt; <constructor-arg value="ou=groups"/>
&lt;property name="groupRoleAttribute" value="ou"/&gt; <property name="groupRoleAttribute" value="ou"/>
&lt;/bean&gt; </bean>
&lt;/constructor-arg&gt; </constructor-arg>
&lt;/bean&gt; </bean>]]>
</programlisting>
</programlisting> 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
<literal>ldap://monkeymachine:389/dc=springframework,dc=org</literal>. <literal>ldap://monkeymachine:389/dc=springframework,dc=org</literal>.
Authentication will be performed by attempting to bind with the DN <literal>uid=&lt;user-login-name&gt;,ou=people,dc=springframework,dc=org</literal>. After Authentication will be performed by attempting to bind with the DN
successful authentication, roles will be assigned to the user by searching under the DN <literal>uid=&lt;user-login-name&gt;,ou=people,dc=springframework,dc=org</literal>.
<literal>ou=groups,dc=springframework,dc=org</literal> with the default filter After successful authentication, roles will be assigned to the user by searching
under the DN
<literal>ou=groups,dc=springframework,dc=org</literal>
with the default filter
<literal>(member=&lt;user's-DN&gt;)</literal>. The role name will be taken from the <literal>(member=&lt;user's-DN&gt;)</literal>. The role name will be taken from the
<quote>ou</quote> attribute of each match.</para> <quote>ou</quote>
attribute of each match.</para>
<para>To configurae a user search object, which uses the filter <para>To configurae a user search object, which uses the filter
<literal>(uid=&lt;user-login-name&gt;)</literal> for use instead of the <literal>(uid=&lt;user-login-name&gt;)</literal>
DN-pattern (or in addition to it), you would configure the following bean for use instead of the DN-pattern (or in addition to it), you would configure the
following bean
<programlisting> <programlisting>
&lt;bean id="userSearch" <![CDATA[
class="org.springframework.security.ldap.search.FilterBasedLdapUserSearch"&gt; <bean id="userSearch"
&lt;constructor-arg index="0" value=""/&gt; class="org.springframework.security.ldap.search.FilterBasedLdapUserSearch">
&lt;constructor-arg index="1" value="(uid={0})"/&gt; <constructor-arg index="0" value=""/>
&lt;constructor-arg index="2" ref="contextSource" /&gt; <constructor-arg index="1" value="(uid={0})"/>
&lt;property name="searchSubtree" value="true"/&gt; <constructor-arg index="2" ref="contextSource" />
&lt;/bean&gt; <property name="searchSubtree" value="true"/>
</programlisting> </bean> ]]>
and use it by setting the authenticator's <property>userSearch</property> property. The authenticator </programlisting>
would then call the search object to obtain the correct user's DN before attempting to bind as this user.</para> and use it by setting the authenticator's
<property>userSearch</property>
property. The authenticator would then call the search object to obtain the correct
user's DN before attempting to bind as this user.</para>
</section> </section>
</section> </section>
</chapter> </chapter>