# Configuration

## ContextSource Configuration

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

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

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

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

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 .

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

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.

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 .

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

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>

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.

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

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>

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

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 . If pooling functionality is required, this is the recommended approach.

### 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 , 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.

## LdapTemplate Configuration

### 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`.

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.

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

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());
       }
       ...
    }

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.