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

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.

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.

<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
	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
	When using the SpringSecurityAuthenticationSource you need to use Spring Security's LdapAuthenticationProvider to authenticate the users against LDAP.

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:

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

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.

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.

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.