1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321
|
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="configuration">
<title>Configuration</title>
<sect1 id="context-source-configuration">
<title>ContextSource Configuration</title>
<para>There are several properties in <literal>AbstractContextSource</literal>
(superclass of <literal>DirContextSource</literal> and <literal>LdapContextSource</literal>)
that can be used to modify its behaviour.</para>
<sect2 id="dir-context-url">
<title>LDAP Server URLs</title>
<para>The URL of the LDAP server is specified using the <literal>url</literal> property.
The URL should be in the format <literal>ldap://myserver.example.com:389</literal>.
For SSL access, use the <literal>ldaps</literal> protocol and the appropriate port, e.g.
<literal>ldaps://myserver.example.com:636</literal></para>
<para>It is possible to configure multiple alternate LDAP servers using the
<literal>urls</literal> property. In this case, supply all server urls in a String
array to the <literal>urls</literal> property.</para>
</sect2>
<sect2 id="dir-context-base">
<title>Base LDAP path</title>
<para>It is possible to specify the root context for all LDAP operations using the
<literal>base</literal> property of <literal>AbstractContextSource</literal>.
When a value has been specified to this property, all Distinguished Names supplied to and received from LDAP operations
will be relative to the LDAP path supplied. This can significantly simplify working against the LDAP
tree; however there are several occations when you will need to have access to the base path.
For more information on this, please refer to <xref linkend="base-context-configuration" /></para>
</sect2>
<sect2 id="dir-context-authentication">
<title>DirContext Authentication</title>
<para>When <literal>DirContext</literal> instances are created to be used for performing
operations on an LDAP server these contexts often need to be authenticated. There are
different options for configuring this using Spring LDAP, described in this chapter.</para>
<para><note><para>This section refers to authenticating contexts in the core functionality
of the <literal>ContextSource</literal> - to construct <literal>DirContext</literal> instances
for use by <literal>LdapTemplate</literal>. LDAP is commonly used for the sole purpose
of user authentication, and the <literal>ContextSource</literal> may be used for that as
well. This process is discussed in <xref linkend="user-authentication" />.
</para></note></para>
<para>Authenticated contexts are created for both read-only and
read-write operations by default. You specify
<literal>userDn</literal> and <literal>password</literal> of the LDAP
user to be used for authentication on the
<literal>ContextSource</literal>.</para>
<para><note>
<para>The <literal>userDn</literal> needs to be the full
Distinguished Name (DN) of the user from the root of the LDAP tree,
regardless of whether a <literal>base</literal> LDAP path has been supplied to
the <literal>ContextSource</literal>.</para>
</note></para>
<para>Some LDAP server setups allow anonymous read-only access. If you
want to use anonymous Contexts for read-only operations, set the
<literal>anonymousReadOnly</literal> property to
<literal>true</literal>.<literal></literal></para>
<sect3 id="custom-authentication-processing">
<title>Custom DirContext Authentication Processing</title>
<para>The default authentication mechanism used in Spring LDAP is SIMPLE authentication.
This means that in the user DN (as specified to the <literal>userDn</literal> property) and
the credentials (as specified to the <literal>password</literal>) are set in
the Hashtable sent to the <literal>DirContext</literal> implementation constructor.</para>
<para>There are many occasions when this processing is not sufficient. For instance,
LDAP Servers are commonly set up to only accept communication on a secure TLS channel;
there might be a need to use the particular LDAP Proxy Auth mechanism, etc.</para>
<para>It is possible to specify an alternative authentication mechanism by supplying a
<literal>DirContextAuthenticationStrategy</literal> implementation to the <literal>ContextSource</literal>
in the configuration.</para>
<sect4 id="authentication-tls">
<title>TLS</title>
<para>Spring LDAP provides two different configuration options for LDAP servers requiring TLS secure
channel communication: <literal>DefaultTlsDirContextAuthenticationStrategy</literal> and
<literal>ExternalTlsDirContextAuthenticationStrategy</literal>. Both these
implementations will negotiate a TLS channel on the target connection, but they differ in the actual authentication mechanism.
Whereas the <literal>DefaultTlsDirContextAuthenticationStrategy</literal> will apply SIMPLE authentication
on the secure channel (using the specified <literal>userDn</literal> and <literal>password</literal>),
the <literal>ExternalDirContextAuthenticationStrategy</literal> will use EXTERNAL SASL authentication,
applying a client certificate configured using system properties for authentication.</para>
<para>Since different LDAP server implementations respond differently to explicit shutdown of the
TLS channel (some servers require the connection be shutdown gracefully; others do not support it),
the TLS <literal>DirContextAuthenticationStrategy</literal> implementations support specifying
the shutdown behavior using the <literal>shutdownTlsGracefully</literal> parameter. If this
property is set to <literal>false</literal> (the default), no explicit TLS shutdown will happen;
if it is <literal>true</literal>, Spring LDAP will try to shutdown the TLS channel gracefully
before closing the target context.</para>
<para><note><para>When working with TLS connections you need to make sure that the native LDAP
Pooling functionality is turned off. As of release 1.3, the default setting is off. For earlier
versions, simply set the <literal>pooled</literal> property to <literal>false</literal>. This is
particularly important if <literal>shutdownTlsGracefully</literal> is set to <literal>false</literal>.
However, since the TLS channel negotiation process is quite expensive, great performance benefits will
be gained by using the Spring LDAP Pooling Support, described in <xref linkend="pooling" />.
</para></note></para>
</sect4>
</sect3>
<sect3>
<title>Custom Principal and Credentials Management</title>
<para>While the user name (i.e. user DN) and password used for
creating an authenticated <literal>Context</literal> are static by
default - the ones set on the <literal>ContextSource</literal> on
startup will be used throughout the lifetime of the
<literal>ContextSource</literal> - there are however several cases in
which this is not the desired behaviour. A common scenario is that the
principal and credentials of the current user should be used when
executing LDAP operations for that user. The default behaviour can be
modified by supplying a custom <literal>AuthenticationSource</literal>
implementation to the <literal>ContextSource</literal> on startup,
instead of explicitly specifying the <literal>userDn</literal> and
<literal>password</literal>. The
<literal>AuthenticationSource</literal> will be queried by the
<literal>ContextSource</literal> for principal and credentials each
time an authenticated <literal>Context</literal> is to be
created.</para>
<para>If you are using <ulink url="http://springsecurity.org">Spring Security</ulink>
you can make sure the principal and credentials of the currently logged in user
is used at all times by configuring your <literal>ContextSource</literal>
with an instance of the <literal>SpringSecurityAuthenticationSource</literal>
shipped with Spring Security.</para>
<example>
<title>The Spring bean definition for a
SpringSecurityAuthenticationSource</title>
<programlisting><beans>
...
<bean id="contextSource" class="org.springframework.ldap.core.support.LdapContextSource">
<property name="url" value="ldap://localhost:389" />
<property name="base" value="dc=example,dc=com" />
<property name="authenticationSource" ref="springSecurityAuthenticationSource" />
</bean>
<bean id="springSecurityAuthenticationSource"
class="org.springframework.security.ldap.SpringSecurityAuthenticationSource" />
...
</beans></programlisting>
</example>
<note>
<para>We don't specify any <literal>userDn</literal> or
<literal>password</literal> to our <literal>ContextSource</literal>
when using an <literal>AuthenticationSource</literal> - these
properties are needed only when the default behaviour is
used.</para>
</note>
<note>
<para>When using the <literal>SpringSecurityAuthenticationSource</literal>
you need to use Spring Security's
<literal>LdapAuthenticationProvider</literal> to authenticate the
users against LDAP.</para>
</note>
</sect3>
<sect3>
<title>Default Authentication</title>
<para>When using <literal>SpringSecurityAuthenticationSource</literal>,
authenticated contexts will only be possible to create once the user
is logged in using Spring Security. To use default authentication information
when no user is logged in, use the
<literal>DefaultValuesAuthenticationSourceDecorator</literal>:</para>
<example>
<title>Configuring a
DefaultValuesAuthenticationSourceDecorator</title>
<programlisting><beans>
...
<bean id="contextSource" class="org.springframework.ldap.core.support.LdapContextSource">
<property name="url" value="ldap://localhost:389" />
<property name="base" value="dc=example,dc=com" />
<property name="authenticationSource" ref="authenticationSource" />
</bean>
<bean id="authenticationSource"
class="org.springframework.ldap.authentication.DefaultValuesAuthenticationSourceDecorator">
<property name="target" ref="springSecurityAuthenticationSource" />
<property name="defaultUser" value="cn=myDefaultUser" />
<property name="defaultPassword" value="pass" />
</bean>
<bean id="springSecurityAuthenticationSource"
class="org.springframework.security.ldap.SpringSecurityAuthenticationSource" />
...
</beans></programlisting>
</example>
</sect3>
</sect2>
<sect2 id="context-source-pooling">
<title>Native Java LDAP Pooling</title>
<para>The internal Java LDAP provider provides some very basic pooling capabilities.
This LDAP connection pooling can be turned on/off using the
<literal>pooled</literal> flag on <literal>AbstractContextSource</literal>.
The default value is <literal>false</literal> (since release 1.3), i.e. the native
Java LDAP pooling will be turned on. The configuration of LDAP connection pooling is managed using
<literal>System</literal> properties, so this needs to be handled
manually, outside of the Spring Context configuration. Details of the native pooling configuration
can be found <ulink url="http://java.sun.com/products/jndi/tutorial/ldap/connect/config.html">here</ulink>.
</para>
<para><note>
There are several serious deficiencies in the built-in LDAP connection pooling,
which is why Spring LDAP provides a more sophisticated approach to LDAP connection pooling,
described in <xref linkend="pooling" />. If pooling functionality is required, this is the
recommended approach.</note></para>
</sect2>
<sect2 id="context-source-advanced">
<title>Advanced ContextSource Configuration</title>
<sect3 id="context-source-context-factory">
<title>Alternate ContextFactory</title>
<para>It is possible to configure the <literal>ContextFactory</literal> that the
<literal>ContextSource</literal> is to use when creating Contexts using the
<literal>contextFactory</literal> property. The default value is
<literal>com.sun.jndi.ldap.LdapCtxFactory</literal>.</para>
</sect3>
<sect3 id="context-source-object-factory">
<title>Custom DirObjectFactory</title>
<para>As described in <xref linkend="dirobjectfactory" />, a <literal>DirObjectFactory</literal>
can be used to translate the <literal>Attributes</literal> of found Contexts
to a more useful <literal>DirContext</literal> implementation. This can be
configured using the <literal>dirObjectFactory</literal> property. You can use
this property if you have your own, custom <literal>DirObjectFactory</literal> implementation.</para>
<para>The default value is <literal>DefaultDirObjectFactory</literal>.</para>
</sect3>
<sect3 id="context-source-custom-env-properties">
<title>Custom DirContext Environment Properties</title>
<para>In some cases the user might want to specify additional environment setup properties
in addition to the ones directly configurable from <literal>AbstractContextSource</literal>.
Such properties should be set in a <literal>Map</literal> and supplied to
the <literal>baseEnvironmentProperties</literal> property.</para>
</sect3>
</sect2>
</sect1>
<sect1 id="ldap-template-configuration">
<title>LdapTemplate Configuration</title>
<sect2 id="ldap-template-ignore-partial-result">
<title>Ignoring PartialResultExceptions</title>
<para>Some Active Directory (AD) servers are unable to automatically following
referrals, which often leads to a <literal>PartialResultException</literal> being
thrown in searches. You can specify that <literal>PartialResultException</literal>
is to be ignored by setting the <literal>ignorePartialResultException</literal>
property to <literal>true</literal>.
<note>This causes all referrals to be ignored, and no notice will be given that
a <literal>PartialResultException</literal> has been encountered.
There is currently no way of manually following referrals using LdapTemplate.</note></para>
</sect2>
</sect1>
<sect1 id="base-context-configuration">
<title>Obtaining a reference to the base LDAP path</title>
<para>As described above, a base LDAP path may be supplied to the <literal>ContextSource</literal>,
specifying the root in the LDAP tree to which all operations will be relative. This means that
you will only be working with relative distinguished names throughout your system, which is
typically rather handy. There are however some cases in which you will need to have access
to the base path in order to be able to construct full DNs, relative to the actual root of the LDAP tree.
One example would be when working with LDAP groups (e.g. <literal>groupOfNames</literal> objectclass),
in which case each group member attribute value will need to be the full DN of the referenced member.</para>
<para>For that reason, Spring LDAP has a mechanism by which any Spring controlled bean may be supplied
the base path on startup. For beans to be notified of the base path, two things need to be in place:
First of all, the bean that wants the base path reference needs to implement the
<literal>BaseLdapPathAware</literal> interface. Secondly, a <literal>BaseLdapPathBeanPostProcessor</literal>
needs to be defined in the application context</para>
<example>
<title>Implementing <literal>BaseLdapPathAware</literal></title>
<programlisting>package com.example.service;
public class PersonService implements PersonService, <emphasis role="bold">BaseLdapPathAware</emphasis> {
...
<emphasis role="bold">private DistinguishedName basePath;
public void setBaseLdapPath(DistinguishedName basePath) {
this.basePath = basePath;
}</emphasis>
...
private DistinguishedName getFullPersonDn(Person person) {
return new DistinguishedName(<emphasis role="bold">basePath</emphasis>).append(person.getDn());
}
...
}</programlisting>
</example>
<example>
<title>Specifying a <literal>BaseLdapPathBeanPostProcessor</literal> in your <literal>ApplicationContext</literal></title>
<programlisting><beans>
...
<bean id="contextSource" class="org.springframework.ldap.core.support.LdapContextSource">
<property name="url" value="ldap://localhost:389" />
<property name="base" value="dc=example,dc=com" />
<property name="authenticationSource" ref="authenticationSource" />
</bean>
...
<emphasis role="bold"><bean class="org.springframework.ldap.core.support.BaseLdapPathBeanPostProcessor" /></emphasis>
</beans>
</programlisting>
</example>
<para>The default behaviour of the <literal>BaseLdapPathBeanPostProcessor</literal> is to use the base path of the single
defined <literal>BaseLdapPathSource</literal> (<literal>AbstractContextSource</literal> )in the <literal>ApplicationContext</literal>.
If more than one <literal>BaseLdapPathSource</literal> is defined, you will need to specify which one to use with the
<literal>baseLdapPathSourceName</literal> property.</para>
</sect1>
</chapter>
|