Simple LDAP Authentication

One of the most requested pieces of functionality in Spring LDAP has been a means to perform simple authentication. We have previously hesitated to include this, not finding any logical place to put it. In this release however we got a couple of suggestions on suitable API additions that enabled us to attack this from a different angle, in the end resulting in explicit methods in LdapTemplate for this purpose.

Background

The problem with authentication in LDAP is that it normally requires two separate steps: First you need to find the principal to authenticate in the LDAP tree, typically performing an LDAP search based on e.g. a user name. A new LDAP connection will then be acquired, authenticating it using the Distinguished Name of the found entry (normally referred to as an 'LDAP Bind').

Example

Consider the LDAP tree below:

Let us say a user identifying himself as 'John Doe' is trying to log into our system. We would execute a search from the top of the LDAP tree using a search filter like (&(objectclass=person)(cn=John Doe)). The search would return one single entry, from which we would extract the absolute DN; cn=John Doe, ou=company1, c=Sweden, dc=jayway, dc=se. This DN would then be used for authenticating a new LDAP connection to the server, thus validating the password supplied by the user.

New Spring LDAP Authentication API

While the above has indeed been possible to do using previous versions of Spring LDAP, it has required quite a lot of work and resulted in rather messy code. Spring LDAP 1.3.0 adds a couple of methods to LdapTemplate, making the authentication procedure very straightforward:

public boolean authenticate(Name base, String filter, String password)
public boolean authenticate(Name base, String filter, String password, AuthenticatedLdapEntryContextCallback callback)

The first method performs exactly the procedure described above, returning true or false depending on the outcome. The second method goes one step further, allowing us to perform any operation on the authenticated LDAP connection. Focusing on the simplest case, a standard authentication method using Spring LDAP would look something like the following:

public boolean login(String username, String password){
  AndFilter filter = new AndFilter();
  filter.and(new EqualsFilter("objectclass", "person")).and(new EqualsFilter("cn", username));
  return ldapTemplate.authenticate(DistinguishedName.EMPTY_PATH, filter.toString(), password);
}

Simple, clean and to the point, especially compared to the mess that used to be required (won't linger on those nasty details here). Obviously however, using a Spring library we will be required to write a few lines of XML as well:

<bean id="contextSource" class="org.springframework.ldap.core.support.LdapContextSource">
<property name="url" value="ldap://url.to.ldap.server:389" />
<property name="userDn" value="uid=admin,ou=system" />
<property name="password" value="adminpassword" />
</bean>
<bean id="ldapTemplate" class="org.springframework.ldap.core.LdapTemplate">
  <constructor-arg ref="contextSource" />
</bean>
<bean id="myAuthenticator" class="com.example.MyAuthenticatingClass">
  <!-- Assuming constructor injection of LdapTemplate instance in your authentication class -->
  <constructor-arg ref="ldapTemplate" />
</bean>
 

A couple of comments on the suggested solution:

• The search needs to return exactly one result entry. In the example above, if there would be more than one person entry in the tree with cn 'John Doe' (which would be perfectly legal according to schema regulations), the call to authenticate would fail.
• In actual implementations the attribute to use for identification will likely be e.g. uid or sAMAccountname (in Active Directory). Both of these attributes have uniqueness enforced throughout the entire tree by the LDAP server.
• The method only returns true or false; thus the actual reason for failing will not be visible to the caller. The reason will however be logged, which might be useful useful when tracking down problems with search filters and such.
• A common reason for confusion in LDAP searches is the base parameter, which is used for pointing out where in the LDAP tree to start searching. Referring again to the potential problem where several users might have the same cn; in that case these entries would have to be located in different subtrees. The search could then be narrowed by specifying a different base DN to the authenticate method, e.g. c=Sweden, dc=jayway, dc=com

Note: While the provided methods will handle the simple task of authentication for you it is likely that your actual security requirements go way past plain authentication (e.g. authorization, web integration, etc.). The realm of security is a very complex one, which is the reason you should carefully consider your actual requirements - if they appear to go beyond simple authentication you should definitely consider using Spring Security instead. (Obviously, under the covers Spring LDAP would be used for the actual authentication anyway).

That said, for many systems the API provided with Spring LDAP will be quite sufficient.

Other improvements in Spring LDAP 1.3.0

As compared to the 1.2.1 version of Spring LDAP, 1.3.0 includes more than 50 fixes, varying from internal modifications and minor improvements to important bug fixes and significant functionality additions. The full list of modifications can be viewed in the the changelog.

About Spring LDAP

Spring LDAP is a Java library for simplifying LDAP operations, based on the pattern of Spring's JdbcTemplate. The framework relieves the user of common chores, such as looking up and closing contexts, looping through results, encoding/decoding values and filters, and more. The library is free, open source, and distributed under the Apache Licence version 2.

For more information on the Spring LDAP project, including downloads, maven usage, as well as project reference and API documentation, refer to its project home page on springsource.org. Support and enhancement requests will be answered in the Spring LDAP Forum at Spring Community Forums.

Simple Authentication Mechanism

By far the most requested feature for inclusion in Spring LDAP has been the ability to easily perform simple authentication using the library. While you would typically like to use Spring Security to implement full-blown application security many of our users have expressed the need to just do the authentication part, not having to worry about the full Spring Security framework. This is now explicitly supported with a new method in the ContextSource interface: getContext(String principal, String password). This means that in order to do simple user authentication you would write something like the following:

 
...
private SimpleLdapTemplate ldapTemplate;
private ContextSource contextSource;
public void setLdapTemplate(SimpleLdapTemplate ldapTemplate) {
	this.ldapTemplate = ldapTemplate;
}
public void setContextSource(ContextSource contextSource) {
	this.contextSource = contextSource;
}
 
public boolean authenticate(String userName, String password) {
	EqualsFilter filter = new EqualsFilter("uid", userName);
	// Actual filter will differ depending on LDAP Server and schema
	List<String> results = ldapTemplate.search("", filter.toString(),
			new DnContextMapper());
	if (results.size() != 1) {
		throw new IncorrectResultSizeDataAccessException(1, results.size());
	}
 
	DirContext ctx = null;
	try {
		ctx = contextSource.getContext(results.get(0), password);
		return true;
	} catch (Exception e) {
		return false;
	} finally {
		LdapUtils.closeContext(ctx);
	}
}
 
private final static class DnContextMapper extends
		AbstractParameterizedContextMapper<String> {
	@Override
	protected String doMapFromContext(DirContextOperations ctx) {
		return ctx.getNameInNamespace();
	}
}
 

The required XML configuration for this:

 
<bean id="ldapTemplate" class="org.springframework.ldap.core.LdapTemplate">
	<constructor-arg ref="contextSource" />
</bean>
<bean id="contextSource" class="org.springframework.ldap.core.support.LdapContextSource">
<property name="url" value="ldap://my.ldap.server" />
<property name="base" value="dc=mycompany, dc=com" />
<property name="userDn" value="cn=Administrator, ou=system" />
<property name="password" value="secret" />
</bean>
<bean id="dummy" class="se.jayway.web.Dummy">
<property name="ldapTemplate" ref="ldapTemplate" />
<property name="contextSource" ref="contextSource" />
</bean>
 

LDAP Data Management

Working with data in LDAP is usually tedious and verbose. Spring LDAP relieves the programmer from explicitly worrying about the details of the underlying Attributes and encapsulates all data regarding an LDAP entry in the DirContextAdapter class. You can get the Attributes of an entry using a DirContextAdapter in a ContextMapper (or ParameterizedContextMapper like above), or you can use the Attribute management capabilities in DirContextAdapter to help you when performing updates or creating entries.

This has been one of the key features from Spring LDAP from the very beginning, and the API has been improved further in this release; particularly a new bind has been added in Spring LDAP, enabling even simpler standard repository code using Spring LDAP:

 
public void create(Person p) {
	p.setDn(buildDn(p));
	DirContextOperations ctx = new DirContextAdapter(p.getDn());
	setAttributeValues(p, ctx);
	ldapTemplate.bind(ctx);
}
 
public void update(Person p) {
	DirContextOperations ctx = ldapTemplate.lookupContext(p.getDn());
	setAttributeValues(p, ctx);
	ldapTemplate.modifyAttributes(ctx);
}
 
private void setAttributeValues(Person p, DirContextOperations ctx) {
	ctx.setAttributeValue("description", p.getDescription());
	ctx.setAttributeValue("telephoneNumber", p.getPhone());
	// Set more attribute values here.
}
 

DirContextAdapter now also supports entries that represent referrals. This means that if you configure your ContextSource to follow referrals (setting the referral property to follow and properly configuring DNS settings so that the server names of the referrals can be resolved) you can get the server URL from any DirContextAdapter resulting from referrals.

TLS Connections

It is a very common setup that the LDAP server is configured only to accept TLS connections. This has previously not been supported by Spring LDAP, but due to some internal rework in AbstractContextSource it is now possible to perform some more elaborate authentication and connection negotiation logic by supplying a DirContextAuthenticationStrategy implementation to the ContextSource. To enable TLS connections you will supply a DefaultTlsDirContextAuthenticationStrategy to your LdapContextSource:

 
<bean id="contextSource" class="org.springframework.ldap.core.support.LdapContextSource">
<property name="url" value="ldap://my.ldap.server" />
<property name="base" value="dc=mycompany, dc=com" />
<property name="userDn" value="cn=Administrator, ou=system" />
<property name="password" value="secret" />
<property name="authenticationStrategy">
		<bean
			class="org.springframework.ldap.core.support.DefaultTlsDirContextAuthenticationStrategy" />
	</property>
</bean>
 

Authentication customization has previously often been done by subclassing LdapContextSource. The recommended approach from Spring LDAP 1.3 is to create a custom DirContextAuthenticationStrategy implementation to suit your need. This would be useful for e.g. LDAP Proxy Authentication or similar functionality.

Major Bug Fixes and Other Changes

Some interesting bug fixes are included in Spring LDAP. Also, some default behavior has been changed; the most important stuff is listed here:

Distinguished Name toString representation

It has long been requested that the Spring LDAP DistinguishedName toString representation should be changed. The toString representation has previously been focused on the readability of the string, adding spaces between the RDNs to make it less compact, e.g.:
cn=John Doe, ou=Some Company, c=Sweden
Several users have been complaining that their DN representations have been compact and that the discrepancy has been causing problems:
cn=John Doe,ou=Some Company,c=Sweden
We have changed the default string representation to the compact one in the 1.3 release. If your system should require the old, 'spaced' format, you can change the default by setting the system property org.springframework.ldap.core.spacedDnFormat to true.

Built-in JNDI Connection Pooling

The pooled property of ContextSource has previously defaulted to true, enabling the built-in Java LDAP connection pooling by default. However the built-in LDAP connection pooling suffers from several deficiencies (most notable there is no way of doing connection validation and configuration is cumbersome), which is why we decided to change the default to false . If you require connection pooling we strongly recommend using the Spring LDAP PoolingContextSource instead.

The Dreaded '\' in Distinguished Names Problem

Java JNDI cannot handle '\' in the Distinguished Names of entries in an LDAP tree. If they do, the DN returned from JNDI will be invalid, which previously caused Spring LDAP to throw an exception. We now work around this bug.

Downloads

We obviously want people to use our stuff. Here are the relevant links:
Binaries(sha)
Binary With Dependencies(sha)
Javadocs
Reference docs

Maven Users

Since this is a release candidate it is not published to the main maven repository. It is however available from the Spring Framework milestone repository:

 
<repositories>
	<repository>
		<id>spring-milestone</id>
		<name>Spring Portfolio Milestone Repository</name>
		<url>http://s3.amazonaws.com/maven.springframework.org/milestone</url>
	</repository>
</repositories>
 

The maven dependencies are as follows:

 
<dependency>
	<groupId>org.springframework.ldap</groupId>
	<artifactId>spring-ldap-core</artifactId>
	<version>1.3.0.RC1</version>
</dependency>
 

 
<dependency>
	<groupId>org.springframework.ldap</groupId>
	<artifactId>spring-ldap-core-tiger</artifactId>
	<version>1.3.0.RC1</version>
</dependency>
 

Summary

In addition to the above there's quite a number of minor feature enhancements and bug fixes. The full change log can be found here. We're obviously very interested in getting your feedback. Please post any comments you might have on the Sping LDAP Support Forum. Bugs should be submitted to the Spring Framework Jira System.