Table of Contents
There are several properties in AbstractContextSource
(superclass of DirContextSource and LdapContextSource)
that can be used to modify its behaviour.
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.
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 the section called “Obtaining a reference to the base LDAP path”
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 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.
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.
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.
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 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.
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>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.
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>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.
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.