File: configuration.xml

package info (click to toggle)
libspring-ldap-java 1.3.1.RELEASE-5
  • links: PTS, VCS
  • area: main
  • in suites: jessie-kfreebsd
  • size: 2,872 kB
  • sloc: java: 12,509; xml: 4,106; jsp: 36; makefile: 33; sh: 13
file content (321 lines) | stat: -rw-r--r-- 18,180 bytes parent folder | download | duplicates (4)
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>&lt;beans&gt;
   ...
   &lt;bean id="contextSource" class="org.springframework.ldap.core.support.LdapContextSource"&gt;
      &lt;property name="url" value="ldap://localhost:389" /&gt;
      &lt;property name="base" value="dc=example,dc=com" /&gt;
      &lt;property name="authenticationSource" ref="springSecurityAuthenticationSource" /&gt;
   &lt;/bean&gt;

   &lt;bean id="springSecurityAuthenticationSource"
      class="org.springframework.security.ldap.SpringSecurityAuthenticationSource" /&gt;
   ...
&lt;/beans&gt;</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>&lt;beans&gt;
   ...
   &lt;bean id="contextSource" class="org.springframework.ldap.core.support.LdapContextSource"&gt;
      &lt;property name="url" value="ldap://localhost:389" /&gt;
      &lt;property name="base" value="dc=example,dc=com" /&gt;
      &lt;property name="authenticationSource" ref="authenticationSource" /&gt;
   &lt;/bean&gt;

   &lt;bean id="authenticationSource"
      class="org.springframework.ldap.authentication.DefaultValuesAuthenticationSourceDecorator"&gt;
      &lt;property name="target" ref="springSecurityAuthenticationSource" /&gt;
      &lt;property name="defaultUser" value="cn=myDefaultUser" /&gt;
      &lt;property name="defaultPassword" value="pass" /&gt;
   &lt;/bean&gt;

   &lt;bean id="springSecurityAuthenticationSource"
      class="org.springframework.security.ldap.SpringSecurityAuthenticationSource" /&gt;
   ...
&lt;/beans&gt;</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>&lt;beans&gt;
   ...
   &lt;bean id="contextSource" class="org.springframework.ldap.core.support.LdapContextSource"&gt;
      &lt;property name="url" value="ldap://localhost:389" /&gt;
      &lt;property name="base" value="dc=example,dc=com" /&gt;
      &lt;property name="authenticationSource" ref="authenticationSource" /&gt;
   &lt;/bean&gt;
   ...
   <emphasis role="bold">&lt;bean class="org.springframework.ldap.core.support.BaseLdapPathBeanPostProcessor" /&gt;</emphasis>
&lt;/beans&gt;
  	  </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>