8. Configuration

8.1. ContextSource Configuration

There are several properties in AbstractContextSource (superclass of DirContextSource and LdapContextSource) that can be used to modify its behaviour.

8.1.1. LDAP Server URLs

The URL of the LDAP server is specified using the url property. The URL should be in the format ldap://myserver.example.com:389. For SSL access, use the ldaps protocol and the appropriate port, e.g. ldaps://myserver.example.com:636

It is possible to configure multiple alternate LDAP servers using the urls property. In this case, supply all server urls in a String array to the urls property.

8.1.2. Base LDAP path

It is possible to specify the root context for all LDAP operations using the base property of AbstractContextSource. 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 Section 8.3, “Obtaining a reference to the base LDAP path”

8.1.3. DirContext Authentication

When DirContext 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.

[Note]Note

This section refers to authenticating contexts in the core functionality of the ContextSource - to construct DirContext instances for use by LdapTemplate. LDAP is commonly used for the sole purpose of user authentication, and the ContextSource may be used for that as well. This process is discussed in Chapter 10, User Authentication using Spring LDAP.

Authenticated contexts are created for both read-only and read-write operations by default. You specify userDn and password of the LDAP user to be used for authentication on the ContextSource.

[Note]Note

The userDn needs to be the full Distinguished Name (DN) of the user from the root of the LDAP tree, regardless of whether a base LDAP path has been supplied to the ContextSource.

Some LDAP server setups allow anonymous read-only access. If you want to use anonymous Contexts for read-only operations, set the anonymousReadOnly property to true.

Custom DirContext Authentication Processing

The default authentication mechanism used in Spring LDAP is SIMPLE authentication. This means that in the user DN (as specified to the userDn property) and the credentials (as specified to the password) are set in the Hashtable sent to the DirContext implementation constructor.

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.

It is possible to specify an alternative authentication mechanism by supplying a DirContextAuthenticationStrategy implementation to the ContextSource in the configuration.

TLS

Spring LDAP provides two different configuration options for LDAP servers requiring TLS secure channel communication: DefaultTlsDirContextAuthenticationStrategy and ExternalTlsDirContextAuthenticationStrategy. Both these implementations will negotiate a TLS channel on the target connection, but they differ in the actual authentication mechanism. Whereas the DefaultTlsDirContextAuthenticationStrategy will apply SIMPLE authentication on the secure channel (using the specified userDn and password), the ExternalDirContextAuthenticationStrategy will use EXTERNAL SASL authentication, applying a client certificate configured using system properties for authentication.

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 DirContextAuthenticationStrategy implementations support specifying the shutdown behavior using the shutdownTlsGracefully parameter. If this property is set to false (the default), no explicit TLS shutdown will happen; if it is true, Spring LDAP will try to shutdown the TLS channel gracefully before closing the target context.

[Note]Note

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 pooled property to false. This is particularly important if shutdownTlsGracefully is set to false. 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 Chapter 9, Pooling Support.

Custom Principal and Credentials Management

While the user name (i.e. user DN) and password used for creating an authenticated Context are static by default - the ones set on the ContextSource on startup will be used throughout the lifetime of the ContextSource - 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 AuthenticationSource implementation to the ContextSource on startup, instead of explicitly specifying the userDn and password. The AuthenticationSource will be queried by the ContextSource for principal and credentials each time an authenticated Context is to be created.

If you are using Spring Security you can make sure the principal and credentials of the currently logged in user is used at all times by configuring your ContextSource with an instance of the SpringSecurityAuthenticationSource shipped with Spring Security.

Example 8.1. The Spring bean definition for a SpringSecurityAuthenticationSource

<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>

[Note]Note

We don't specify any userDn or password to our ContextSource when using an AuthenticationSource - these properties are needed only when the default behaviour is used.

[Note]Note

When using the SpringSecurityAuthenticationSource you need to use Spring Security's LdapAuthenticationProvider to authenticate the users against LDAP.

Default Authentication

When using SpringSecurityAuthenticationSource, 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 DefaultValuesAuthenticationSourceDecorator:

Example 8.2. Configuring a DefaultValuesAuthenticationSourceDecorator

<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>

8.1.4. Native Java LDAP Pooling

The internal Java LDAP provider provides some very basic pooling capabilities. This LDAP connection pooling can be turned on/off using the pooled flag on AbstractContextSource. The default value is false (since release 1.3), i.e. the native Java LDAP pooling will be turned on. The configuration of LDAP connection pooling is managed using System properties, so this needs to be handled manually, outside of the Spring Context configuration. Details of the native pooling configuration can be found here.

[Note]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 Chapter 9, Pooling Support. If pooling functionality is required, this is the recommended approach.
[Note]Note
Regardless of the pooling configuration, the ContextSource#getContext(String principal, String credentials) method will always explicitly not use native Java LDAP Pooling, in order for reset passwords to take effect as soon as possible.

8.1.5. Advanced ContextSource Configuration

Alternate ContextFactory

It is possible to configure the ContextFactory that the ContextSource is to use when creating Contexts using the contextFactory property. The default value is com.sun.jndi.ldap.LdapCtxFactory.

Custom DirObjectFactory

As described in Chapter 3, Simpler Attribute Access and Manipulation with DirContextAdapter, a DirObjectFactory can be used to translate the Attributes of found Contexts to a more useful DirContext implementation. This can be configured using the dirObjectFactory property. You can use this property if you have your own, custom DirObjectFactory implementation.

The default value is DefaultDirObjectFactory.

Custom DirContext Environment Properties

In some cases the user might want to specify additional environment setup properties in addition to the ones directly configurable from AbstractContextSource. Such properties should be set in a Map and supplied to the baseEnvironmentProperties property.

8.2. LdapTemplate Configuration

8.2.1. Ignoring PartialResultExceptions

Some Active Directory (AD) servers are unable to automatically following referrals, which often leads to a PartialResultException being thrown in searches. You can specify that PartialResultException is to be ignored by setting the ignorePartialResultException property to true.

[Note]Note
This causes all referrals to be ignored, and no notice will be given that a PartialResultException has been encountered. There is currently no way of manually following referrals using LdapTemplate.

8.3. Obtaining a reference to the base LDAP path

As described above, a base LDAP path may be supplied to the ContextSource, 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. groupOfNames objectclass), in which case each group member attribute value will need to be the full DN of the referenced member.

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 BaseLdapPathAware interface. Secondly, a BaseLdapPathBeanPostProcessor needs to be defined in the application context

Example 8.3. Implementing BaseLdapPathAware

package com.example.service;

public class PersonService implements PersonService, BaseLdapPathAware {
   ...
   private DistinguishedName basePath;
   
   public void setBaseLdapPath(DistinguishedName basePath) {
      this.basePath = basePath;
   }
   ...
   private DistinguishedName getFullPersonDn(Person person) {
      return new DistinguishedName(basePath).append(person.getDn());
   }
   ...
}

Example 8.4. Specifying a BaseLdapPathBeanPostProcessor in your ApplicationContext

<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 class="org.springframework.ldap.core.support.BaseLdapPathBeanPostProcessor" />
</beans>
  	  

The default behaviour of the BaseLdapPathBeanPostProcessor is to use the base path of the single defined BaseLdapPathSource (AbstractContextSource )in the ApplicationContext. If more than one BaseLdapPathSource is defined, you will need to specify which one to use with the baseLdapPathSourceName property.