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 Section 8.3, “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.
Note | |
---|---|
This section refers to authenticating contexts in the core functionality
of the |
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 | |
---|---|
The |
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.
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 |
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 | |
---|---|
We don't specify any |
Note | |
---|---|
When using the |
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.
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 | |
---|---|
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.
|
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
.
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 | |
---|---|
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. |
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.