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.

BDD in Java with easyb (John Ferguson Smart)

John started out by arguing that TDD is not about testing, it's about writing better code. That is, it's about making your code more maintainable, flexible, reliable and simple. TDD is forces the programmer to think about how to test the class before actually writing the class. BDD, on the other hand, helps to determine what to test and to write more focused code, by starting with the behavior. Instead of thinking that you're testing your class, you should think that you're validating your requirements!

easyb is a BDD testing framework for Java, written in Groovy (hence providing full access to all Java API's). It ensures that tests become clearer and easier to both write and read! It helps the developer to focus on the requirements only. A competitor to easyb is JBehave, which is an extension to JUnit. However, according to John, JBehave is more cumbersome than easyb.

easyb makes use of stories, much like the story cards in the Agile world. In a story, a narrative approach is used to describe a precise requirement. In easyb, a story could look like this:

 
scenario “Make initial deposit onto a new account”, {
	given “a new account”
	when “an initial deposit is made”
	then “the balance should be equal to the amount deposited”
}
 

This scenario is quite clear and readable, isn't it!? Furthermore, it's self-documenting - a very appreciated feature =) And the syntax is so trivial that even a non-technical stakeholder would have no problem understanding it. The developer can then reuse the given scenario (pseudo) code and implement the test case, like this:

 
import com.mycompany.bankonline.domain.Account
 
scenario “Make initial deposit onto a new account”, {
	given “a new account”, {
		account = new Account()
	}
	when “an initial deposit is made”, {
		initialAmount = 100
		account.makeDeposit(initialAmount)
	}
	then “the balance should be equal to the amount deposited”, {
		account.balance.shouldBe initialAmount
	}
}
 

The shouldBe call is an intuitive and readable way to verify that the requirement holds. Another way to verify the outcomes is to use the ensure syntax. Example:

 
ensure(account.balance > 0)
 

or

 
ensure(account) {
	has([balance:100])
}
 

easyb could be extended to use DBUnit (and further plugins for Grails and Excel are on the way). On the IDE support, the only good option is IntelliJ IDEA. It really comes down to the Groovy support, and Eclipse and NetBeans doesn't shine here. In those cases, you're better off running the tests in Maven or Ant, which both are well supported. In the upcoming version, easyb will have full support for Continuous Integration (CI), enabling automatic test execution in a CI-server such as Hudson.

Furthermore, easyb comes with a web application - Easiness (cmp. Fitnesse) - where stakeholders can create stories in plain text. The developers can then go ahead and implement the stories defined by the stakeholders. This is an important features, that further improves the cooperation between the customer and the provider. It really seems like a quite nice little framework! If you agree, have a look at it at http://easyb.org/.

From Concurrent to Parallel – Library-based parallelism in JDK 7 (Brian Goetz)

Brian is an expert in the concurrency area, but he's not a good presenter! He speaks faster than I can read, and his slides are so packed with info that he doesn't have time to say the half of it. That put aside, in this very interesting session Brian presented some really cool concurrency features to be included in JDK 7.

As you probably know, JDK 5 introduced a set of very useful classes for course-grained parallelism. JDK 7 will introduce a framework for fine-grained parallelism - the "fork-join" framework.

We have now reach a point in time when Moore's laws isn't valid anymore. The new reality is not faster CPUs but more CPUs. To adapt to these changes, programmers have to change the way they think about parallelism. The unit of work (UoW) that represents a task to be solved must be split into even smaller parts to be able to keep all hardware busy. Nowadays, it isn't enough to for ex. spawn a new thread for each service call in a server, the UoW must be split up even further.

Examples of finer-grained parallelism is searching, sorting and filtering a data set. Such a task is preferably solved by dividing it into sub-problems and combining the sub-results at the end. We could use the course-grained concurrency tools (for ex. Executor + Future) introduced in JDK 5 to solve this problem. However, with multiple CPUs available, these tools doesn't perform optimally. For ex., the shared work queue in the Executor becomes a bottle neck when the number of threads/CPUs increases. Furthermore, these tools provide no form of load balancing, i.e. if one thread finishes before the others, it is never reused.

The divide-and-conquer algorithm could also be applied to solve the problem. This great advantage of this approach is that it's independent of the number of CPUs used! Using plain threads for this approach is too expensive though, since thread creation costs way too much. However, the fork-join-operation in JDK 7 solves problems like these using the divide-and-conquer algorithm in a much more effective way! Internally, it uses an slim thread pool to overcome the cost of thread creation. Furthermore, no data-copying penalty exist since the data set (for ex. an array) is not divided/copied during the solution. Instead, the indexes within the data structure is used to define each data subset. Another advantage is that the code doesn't know how many CPUs it executes on, hence it's portable!

While the Executor (JDK 5) should be used for tasks consisting of both IO and computing, the fork-join-operation (JDK 7) should be used for highly compute-intensive tasks. Examples of such tasks are matrix operations, numerical integrations and game playing. The JDK 7 class to be used for these kind of problems is ParallelArray. It's a utility class that greatly simplifies the work of solving a task in parallel. You can think of it as an in-memory database for data sets. Typical usage is:

 
ParallelLongArray pa = ParallelLongArray.createUsingHandoff(array, forkJoinPool);
long max = pa.max();
 

The ParallelArray class provides operations for:

• Filtering (nestable)
• Mapping
• Replacement
• Aggregation (max, count, sum, ...)
• Application (one action performed for each selected element)

To compare, the ParallelArray class acts much like the Map-Produce concept introduced by Google but it works in a different domain (local system instead of in a distributed system).

The only downside really is that JDK 7 isn't scheduled until mid 2010, meaning we'll have to wait quite some time before we can actually use these new concurrency features. But from the looks of it ... it may be worth the wait!

The SpringSource DM Server (Joris Kuipers)

The reasons why SpringSource decided to develop a new application server were many. Today, modularity is important and developers spend much time on achieving it in their applications (layering, separation of concerns, etc.). However, when the application is deployed, all modularity is lost - the deployable unit is one huge, monolithic WAR file. That means that sharing code (let alone services) between applications become hard if not impossible. In order to perform the smallest update on the application, whole WAR file have to be redeployed. Furthermore, the servers themselves lack modularity; they come prepackaged with a lot of modules but there's no way to configure that your application only make use of a couple of them. Hence, they are all left in there, consuming unnecessary CPU cycles and memory.

The DM (Dynamic Modules) server was developed to tackle these issues of non-modularity. In order to achieve true modularity, is has been built on top of OSGi (namely the Equinox container). Since OSGi can be quite hard sometimes, the DM server conceal the complexity of OSGi in the same way as the Spring framework does with for ex. Remoting or JMX.

In order to be able to use a third-party library from within the DM server (and from any other OSGi containers), the standard JAR library needs to be extended with OSGi-specific meta data - the OSGi manifest. SpringSource has therefore created the Enterprise Bundle Repository, where they have started to upload and publish OSGi-ified Java EE libraries. If you're using Maven or Ivy, the bundle repository can easily be configured as a remote (or local) repository.

The DM server also introduces a couple of new OSGi import constructs, enabling ease of development. One example is the "Import-library" that can be useful if you want to make use of a framework (for ex. Spring) but don't want to waste your time having to specify every single Import-package (for example Spring-Remoting) within the framework (as you normally would have had to do). This doesn't affect performance improvement since (thanks to OSGi) none of the pre-installed bundles are loaded before they are actually used! Furthermore, with the DM server it's now possible to remove the library bloat of monolithic Java EE WARs. Instead of building the external libraries into your WAR, you can instead declare them as dependencies in the OSGi manifest headers. The server will then convert these into plain "Import-package" constructs during deployment. That way, the size of the built/deployed WAR can be reduced significantly!

In the DM server, one can of course deploy plain OSGi bundles but also WARs, EARs etc. Typical scenarios for deploying a plain OSGi bundle are stand-alone libraries, global services and small stand-alone applications. However, being able to deploy a bundle is not enough in most cases ... A normal application normally consist of multiple bundles, which becomes hard to un/deploy since there is no single deployable unit. Furthermore, with multiple bundles you don't get a common log file or a notion of an application scope. To tackle this issue, the DM server adds the notion of an application by introducing the PAR (Platform Archive) format. It's basically a JAR with a number of 'Application-*' manifest headers. You can think of it as an EAR in Java EE. PARs are versioned and the versions apply to all of their bundles. This mean that one can deploy a PAR twice with different versions but with the same bundles, without conflicts.

The DM server comes in several versions. Of course there's the community version, using a GPL and SpringSource license. Then there's the commercial license where full support from SpringSource is included. On the extension side, better Maven support will soon be released so that the dependencies can be specified in a single place (not like now when you have to duplicate them in the pom and in the manifest). There's a Eclipse-plugin available that enables re/deployments from within the IDE.

These are some of the features in the DM server. There are plenty or more cool ones, read all about them here. There, you'll also find a lot of sample applications that can get you going! With the DM server, SpringSource feel that they are filling the (up until now) empty space of server side OSGi and states that "The DM server is the healthy new way to run your apps!". I must say it looks very promising! Why don't you go ahead and try it out!? I know I will!

If you appreciated these posts, you will definitely enjoy next years conference! Pick up your calendar and reserve December 2009 for a great week at Devoxx!

 
<bean id="traditionalPersonDao"
      class="org.springframework.ldap.samples.article.dao.TraditionalPersonDaoImpl">
<property name="url" value="ldap://localhost:3901" />
<property name="base" value="dc=jayway,dc=se" />
<property name="userDn" value="uid=admin,ou=system" />
<property name="password" value="secret" />
</bean>
 

In order to simplify deployment and maintenance, it's quite common to extract properties related to server names, ports, and user credentials from the Spring configuration file into a separate property file, like in this ldap.properties:

url=ldap://localhost:3901
userDn=uid=admin,ou=system
password=secret

In the configuration file, the previously hard-coded values are replaced with "property placeholders", ie variables enclosed with ${}:

 
<bean id="traditionalPersonDao"
      class="org.springframework.ldap.samples.article.dao.TraditionalPersonDaoImpl">
<property name="url" value="${url}" />
<property name="base" value="dc=jayway,dc=se" />
<property name="userDn" value="${userDn}" />
<property name="password" value="${password}" />
</bean>
 

In order to perform the property value substitution in a transparent way, a PropertyPlaceholderConfigurer is configured:

 
<bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
<property name="location" value="classpath:/config/ldap.properties" />
</bean>
 

Spring will pick up that one has been configured and run it before any beans are instantiated. It will read the property file and replace the placeholders with the actual values. Quite handy and very simple.

But what if your organization dislikes having sensitive information like passwords lying around in property files, in clear text? Let's say that your boss demands that all such passwords must be encrypted. Wouldn't it be great if the password then somehow could be automatically decrypted before being used? This can quite easily be achieved using the Jasypt library.

It's a two-step process. First we need to encrypt the password. Then we configure a different PropertyPlaceholderConfigurer that is capable of decrypting the property after it has been read.

Encrypting the password

The available encryption algorithms are currently limited to Password Based Encryptors (PBE). There are scripts for encrypting and decrypting in the Jasypt distribution. This is the procedure for encrypting a text (assuming the Jasypt library has been unpacked in JASYPT_HOME):

% cd $JASYPT_HOME/bin
% chmod +x *.sh
% ./encrypt.sh input="This is my message to be encrypted" password=MYPAS_WORD verbose=false
p3ZVFhK+aqQCyvSk9uWk7p/eisyPbXp3zt3sqnEZsn1Z5plr4CHNC/HHqlgRQ7I3

Let's verify that it can actually be decrypted:

% ./decrypt.sh input="p3ZVFhK+aqQCyvSk9uWk7p/eisyPbXp3zt3sqnEZsn1Z5plr4CHNC/HHqlgRQ7I3"
    password=MYPAS_WORD verbose=false
This is my message to be encrypted

Good. Note that the encryption is "salted", so you'll never get the same result twice. You'll always be able to decrypt it, though. Want to see? OK, one more time then:

% ./encrypt.sh input="This is my message to be encrypted" password=MYPAS_WORD verbose=false
Zi68CfrcLndtKg0npE9OScr+7qNJmWrcO8XI7ZGyucjFiqT9h1FnAIxyezbqNjQq

% ./decrypt.sh input="Zi68CfrcLndtKg0npE9OScr+7qNJmWrcO8XI7ZGyucjFiqT9h1FnAIxyezbqNjQq"
    password=MYPAS_WORD verbose=false
This is my message to be encrypted

Now, let's encrypt our password:

% ./encrypt.sh input="secret" password=MYPAS_WORD verbose=false
6mbJVZ6jozGYF1pjjqDQOQ==

We'll replace the password value in the properties file with the string above, surrounded by ENC():

url=ldap://localhost:3901
userDn=uid=admin,ou=system
password=ENC(6mbJVZ6jozGYF1pjjqDQOQ==)

Configure A Decrypting PropertyPlaceholderConfigurer

We'll simply replace our existing PropertyPlaceholderConfigurer with the Jasypt EncryptablePropertyPlaceholderConfigurer:

 
<bean class="org.jasypt.spring.properties.EncryptablePropertyPlaceholderConfigurer">
   <constructor-arg ref="configurationEncryptor" />
<property name="location" value="classpath:/config/ldap.properties" />
</bean>
 

It delegates the actual decryption to a StringEncryptor implementation:

 
<bean id="configurationEncryptor" class="org.jasypt.encryption.pbe.StandardPBEStringEncryptor">
<property name="config" ref="environmentVariablesConfiguration" />
</bean>
 

The encryptor in turn needs a configuration that provides information such as the algorithm to use and the encryption password. It delegates that responsibility to a PBEConfig implementation that expects the password to be available in an environment variable or a system property:

 
<bean id="environmentVariablesConfiguration"
      class="org.jasypt.encryption.pbe.config.EnvironmentStringPBEConfig">
<property name="algorithm" value="PBEWithMD5AndDES" />
<property name="passwordEnvName" value="APP_ENCRYPTION_PASSWORD" />
</bean>
 

Providing the encryption password as a system property is actually a good thing. A system property can be cleared just when the application has started, thereby minimizing considerably the time that the password is exposed.

Running The Application

It won't work with a Maven property:

% mvn test -DAPP_ENCRYPTION_PASSWORD=MYPAS_WORD
...
Tests run: 8, Failures: 0, Errors: 8, Skipped: 0
[INFO] ------------------------------------------------------------------------
[ERROR] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] There are test failures.

Please refer to target/surefire-reports for the individual test results

We check the Surefire reports and find the cause of the error:

org.jasypt.exceptions.EncryptionInitializationException:
  Password not set for Password Based Encryptor

It does however work with an environment variable:

% export APP_ENCRYPTION_PASSWORD=MYPAS_WORD
% mvn test
...
Tests run: 8, Failures: 0, Errors: 0, Skipped: 0
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
...
% unset APP_ENCRYPTION_PASSWORD

Issues With Java5

If we're on Java5 (or lower), we'll need ICU4J. Otherwise, we'll run into this:

org.jasypt.exceptions.EncryptionInitializationException:
  java.lang.NoClassDefFoundError: com/ibm/icu/text/Normalizer

There are two places where we'll need ICU4J: the command line tools and our Maven project.

ICU4J With The Command Line Tools

Reviewing the Jasypt scripts, we find that it's possible to customize the classpath:

export JASYPT_CLASSPATH=~/Downloads/icu4j-4_0.jar

ICU4J With Maven

Add this profile to the Maven pom.xml to get ICU4J in the classpath:

 
<profiles>
<profile>
      <id>jdk15</id>
      <activation>
         <jdk>1.5</jdk>
      </activation>
      <dependencies>
         <dependency>
            <groupId>com.ibm.icu</groupId>
            <artifactId>icu4j</artifactId>
            <version>3.8</version>
         </dependency>
      </dependencies>
   </profile>
</profiles>
 

Currently, the 4.0 version is not available in the central Maven repo, but 3.8 seems to work just fine.

Summary

Using Jasypt, it's actually quite easy to use encrypted values in your property files. In a Spring-based application, it's simply a question of replacing the existing PropertyPlaceholderConfigurer with the Jasypt encrypting equivalent, plus two more beans providing encryption and configuration. Choose how to provide the encryption password, and you're set to go.

If running on Java5 or lower, you'll also need to add ICU4J to your classpath, for the encryption scripts as well as your build and deployment environment.

References

• http://jasypt.org
• http://www.springframework.org
• http://icu-project.org/

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

Prerequisites

In order to keep this reasonably brief I'll have to refer to the getting started guide for information on how to get going with Amazon EC2.

A FactoryBean to Launch EC2 Instances

What we want to achieve here is to launch an EC2 instance transparently and independently of the actual test code. Ideally, the test code should be oblivious of the target server and we want to externalize those details to external configuration. We will use Spring's excellent JUnit test support to automatically wire the integration test setup and make sure that the target server is up and running before the actual test code is running.

A powerful way to transparently perform complex initialization logic when using Spring is the FactoryBean concept. We will create a FactoryBean implementation to launch the EC2 image and set up our target resource:

AbstractEc2InstanceLaunchingFactoryBean.java
public abstract class AbstractEc2InstanceLaunchingFactoryBean extends AbstractFactoryBean {
  private static final int INSTANCE_START_SLEEP_TIME = 1000;
  private static final long DEFAULT_PREPARATION_SLEEP_TIME = 30000;
  private static final Log log = LogFactory.getLog(AbstractEc2InstanceLaunchingFactoryBean.class);
  private String imageName;
  private String awsKey;
  private String awsSecretKey;
  private String keypairName;
  private String groupName;
  private Instance instance;
  private long preparationSleepTime = DEFAULT_PREPARATION_SLEEP_TIME;
  public void setImageName(String imageName) {
      this.imageName = imageName;
  }
  public void setAwsKey(String awsKey) {
      this.awsKey = awsKey;
  }
  public void setAwsSecretKey(String awsSecretKey) {
      this.awsSecretKey = awsSecretKey;
  }
  public void setKeypairName(String keypairName) {
      this.keypairName = keypairName;
  }
  public void setGroupName(String groupName) {
      this.groupName = groupName;
  }
  public void setPreparationSleepTime(long preparationSleepTime) {
    this.preparationSleepTime = preparationSleepTime;
  }
  @Override
  protected final Object createInstance() throws Exception {
      Assert.hasLength(imageName, "ImageName must be set");
      Assert.hasLength(awsKey, "AwsKey must be set");
      Assert.hasLength(awsSecretKey, "AwsSecretKey must be set");
      Assert.hasLength(keypairName, "KeyName must be set");
      Assert.hasLength(groupName, "GroupName must be set");
 
      log.info("Launching EC2 instance for image: " + imageName);
 
      Jec2 jec2 = new Jec2(awsKey, awsSecretKey);
      LaunchConfiguration launchConfiguration = new LaunchConfiguration(imageName);
      launchConfiguration.setKeyName(keypairName);
      launchConfiguration.setSecurityGroup(Collections.singletonList(groupName));
 
      ReservationDescription reservationDescription = jec2.runInstances(launchConfiguration);
      instance = reservationDescription.getInstances().get(0);
      while (!instance.isRunning() && !instance.isTerminated()) {
          log.info("Instance still starting up; sleeping " + INSTANCE_START_SLEEP_TIME + "ms");
          Thread.sleep(INSTANCE_START_SLEEP_TIME);
          reservationDescription = jec2.describeInstances(Collections.singletonList(instance.getInstanceId())).get(0);
          instance = reservationDescription.getInstances().get(0);
      }
 
      if (instance.isRunning()) {
          log.info("EC2 instance is now running");
          if (preparationSleepTime > 0) {
              log.info("Sleeping " + preparationSleepTime + "ms allowing instance services to start up properly.");
              Thread.sleep(preparationSleepTime);
              log.info("Instance prepared - proceeding");
          }
          return doCreateInstance(instance.getDnsName());
      } else {
          throw new IllegalStateException("Failed to start a new instance");
      }
   }
 
  protected abstract Object doCreateInstance(String ip) throws Exception;
 
  @Override
  protected void destroyInstance(Object ignored) throws Exception {
    if (this.instance != null) {
      log.info("Shutting down instance");
      Jec2 jec2 = new Jec2(awsKey, awsSecretKey);
      jec2.terminateInstances(Collections.singletonList(this.instance.getInstanceId()));
    }
  }
}
 

This superclass makes use of the typica library (also available in maven) to launch the EC2 instance and delegates to doCreateInstance for creating the target resource that we will use in our test case. In our setup we want to create a ContextSource, which is the Spring LDAP equivalent of a DataSource:

ContextSourceEc2InstanceLaunchingFactoryBean.java
public class ContextSourceEc2InstanceLaunchingFactoryBean extends AbstractEc2InstanceLaunchingFactoryBean {
  private String base;
  private String userDn;
  private String password;
  @Override
  public final Class getObjectType() {
    return ContextSource.class;
  }
  @Override
  protected final Object doCreateInstance(final String dnsName) throws Exception {
    Assert.hasText(userDn);
    LdapContextSource instance = new LdapContextSource();
    instance.setUrl("ldap://" + dnsName);
    instance.setUserDn(userDn);
    instance.setPassword(password);
    instance.setBase(base);
 
    instance.afterPropertiesSet();
    return instance;
  }
  public void setBase(String base) {
    this.base = base;
  }
  public void setUserDn(String userDn) {
    this.userDn = userDn;
  }
  public void setPassword(String password) {
    this.password = password;
  }
}
 

Note that the AbstractEc2InstanceLaunchingFactoryBean will wait for the instance to start up properly. It will also wait an additional period of time once the instance is up and running to allow for all relevant services to start up properly. Finally it will automatically close down the launched instance once it is properly shut down (which it will be when executing using the Spring automated test support).

Test Case Configuration

We now have the infrastructure to have the EC2 instance launched transparently from a Spring Application Context. All we need to do is configure it:

testContext.xml
<bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
<property name="location" value="ldap.properties" />
<property name="systemPropertiesModeName" value="SYSTEM_PROPERTIES_MODE_OVERRIDE" />
</bean>
 
<bean id="contextSource" class="org.springframework.ldap.ContextSourceEc2InstanceLaunchingFactoryBean">
<property name="awsKey" value="${aws.key}" />
<property name="awsSecretKey" value="${aws.secret.key}" />
<property name="imageName" value="${aws.ami}" />
<property name="groupName" value="${aws.security.group}" />
<property name="keypairName" value="${aws.keypair}" />
<property name="base" value="dc=jayway,dc=se" />
<property name="userDn" value="${userDn}" />
<property name="password" value="${password}" />
</bean>
 
<bean id="ldapTemplate"
  class="org.springframework.ldap.core.LdapTemplate">
  <constructor-arg ref="contextSource" />
</bean>
 

We are referring to ldap.properties for the actual settings:

userDn=cn=admin,dc=jayway,dc=se
password=secret
base=dc=jayway,dc=se
aws.ami=ami-56ec083f
aws.keypair=spring-ldap-keypair
aws.security.group=spring-ldap

The referenced AMI is a public image specifically set up for our test cases. It has OpenLDAP installed and has been pre-populated with the test data that our test cases expect.

Note that we are not specifying any property value for aws.key and aws.secret.key, as this is the Amazon account access information. That will be the account settings of the individual developer and should be supplied at runtime using system properties (e.g. mvn -Daws.key=xxxxxxx -Daws.secret.key=xxxxxx test).

Performing the Test

Now all we need to do is use Spring's automated test support to start our test:

SomeLdapITest.java
@ContextConfiguration(locations = { "testContext.xml" })
public class SomeLdapITest extends AbstractJUnit4SpringContextTests {
  @Autowired
  private LdapTemplate tested;
 
  @Test
  public void testSomething() {
    // Use the automatically injected LdapTemplate instance to perform a test.
  }
}
 

Set to Go

With the above you should be all set to go to start using this powerful approach to integration testing. The actual code is available with the 1.3.0.RC1 release of Spring LDAP; links to downloads and documentation available here.

Basic Spring Remoting Configuration

In the general situation all you need to do is create a DispatcherServlet (just as you would with any Spring MVC application), add an Exporter on the server side and reference a ProxyFactoryBean on the client.
On the server side:

web.xml
<context-param>
<param-name>contextConfigLocation</param-name>
<param-value>/WEB-INF/applicationContext.xml</param-value>
</context-param>
<listener>
<listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
</listener>
<servlet>
  <servlet-name>demo</servlet-name>
  <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
    <init-param>
<param-name>contextConfigLocation</param-name>
<param-value>/WEB-INF/demo-servlet.xml</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>
 
<servlet-mapping>
  <servlet-name>demo</servlet-name>
  <url-pattern>/*</url-pattern>
</servlet-mapping>
 

demo-servlet.xml - exposes bean 'helloService' as remote service
<bean name="/hello"
    class="org.springframework.remoting.httpinvoker.HttpInvokerServiceExporter">
<property name="service" ref="helloService" />
<property name="serviceInterface"
      value="se.jayway.demo.server.HelloService" />
</bean>
 

On the client side:

clientContext.xml
<bean id="helloService"
  class="org.springframework.remoting.httpinvoker.HttpInvokerProxyFactoryBean">
<property name="serviceUrl"
      value="https://remote-host:8080/security-remoting/hello" />
<property name="serviceInterface"
      value="se.jayway.demo.server.HelloService" />
</bean>
 

Now, in the client application all you need to do is ask for the 'helloService' bean and you will be handed a proxy that talks to the target service on the server without the server or the client knowing anything about it.

Securing the Remote Service

Now, in many cases you'll want to apply some security restrictions on the exposed HTTP service. Being in the Spring world the natural choice for this purpose will be Spring Security. Far from the complications of its predecessor Acegi, Spring Security configuration is now a matter of very few lines of XML code:

web.xml
...
<filter>
  <filter-name>springSecurityFilterChain</filter-name>
  <filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
</filter>
 
<filter-mapping>
  <filter-name>springSecurityFilterChain</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>
...
 

demo-servlet.xml - additions to the original file above; default with one hard coded user
<beans
  xmlns="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:sec="http://www.springframework.org/schema/security"
  xsi:schemaLocation=
        "http://www.springframework.org/schema/beans
         http://www.springframework.org/schema/beans/spring-beans.xsd
         http://www.springframework.org/schema/security
         http://www.springframework.org/schema/security/spring-security-2.0.xsd">
...
<sec:http realm="Hello App">
  <sec:http-basic/>
  <sec:intercept-url pattern="/**" access="ROLE_USER" />
</sec:http>
<sec:authentication-provider>
  <sec:user-service>
    <sec:user name="someuser" password="somepassword" authorities="ROLE_USER" />
  </sec:user-service>
</sec:authentication-provider>
 

Note that we're defining the Spring Security XML schema in the schema definition.

clientContext.xml
<bean id="helloService"
  class="org.springframework.remoting.httpinvoker.HttpInvokerProxyFactoryBean">
<property name="serviceUrl"
      value="https://remote-host:8080/security-remoting/hello" />
<property name="serviceInterface"
      value="se.jayway.demo.server.HelloService" />
<property name="httpInvokerRequestExecutor">
    <bean class="org.springframework.security.context.httpinvoker.AuthenticationSimpleHttpInvokerRequestExecutor  />
  </property>
</bean>

The AuthenticationSimpleHttpInvokerRequestExecutor will make sure that any Spring Security applied on the client side will be transferred to the server side using Basic HTTP Authentication. The filters and the XML configuration on the server side will make sure the Authentication headers are inspected and checked against the valid principals and credentials.

Applying SSL

As most of you probably know, Basic HTTP Authentication is pretty much the same thing as sending the authentication information over the network in plain text. This is why you will typically want to use encrypted connections whenever you are working with this type of authentication. This gets us into the core of this post, because it's here it becomes tricky.

In the ideal world you would just configure your web server to expose the service over HTTPS, change the target URL on the client side and be on your way. The reality however is slightly more complicated.

The problem is that you the built-in HttpURLConnection class on which the AuthenticationSimpleHttpInvokerRequestExecutor relies is very picky when it comes to certificates. What you want to do when working with SSL in Spring Remoting is to use the CommonsHttpInvokerRequestExecutor, which relies on Commons HttpClient - a more flexible and capable HTTP client. Now, the problem with this is that then you cannot use the AuthenticationSimpleHttpInvokerRequestExecutor anymore - they plug into the HttpInvokerProxyFactoryBean at the same extension point.

It boils down to this: if you want to use Spring Remoting and Spring Security over SSL you will need to implement your own HttpInvokerRequestExecutor:

 
public class BasicAuthenticationCommonsHttpInvokerRequestExecutor extends
  CommonsHttpInvokerRequestExecutor {
 
  @Override
  protected PostMethod createPostMethod(HttpInvokerClientConfiguration config) throws IOException {
    PostMethod postMethod = super.createPostMethod(config);
 
    Authentication auth =
        SecurityContextHolder.getContext().getAuthentication();
 
    if ((auth != null) && (auth.getName() != null) &&
          (auth.getCredentials() != null)) {
      String base64 = auth.getName() + ":" + auth.getCredentials().toString();
      postMethod.setRequestHeader("Authorization", "Basic " +
          new String(Base64.encodeBase64(base64.getBytes())));
    }
 
    return postMethod;
  }
}
 

Now all you need to do is specify this implementation as HttpInvokerRequestExecutor for your client ProxyFactoryBean and you're all set:

clientContext.xml
<bean id="helloService"
  class="org.springframework.remoting.httpinvoker.HttpInvokerProxyFactoryBean">
<property name="serviceUrl"
      value="https://remote-host:8080/security-remoting/hello" />
<property name="serviceInterface"
      value="se.jayway.demo.server.HelloService" />
<property name="httpInvokerRequestExecutor">
    <bean class="se.jayway.demo.security.BasicAuthenticationCommonsHttpInvokerRequestExecutor"  />
  </property>
</bean>
 

In the perfect world, each developer would at all times have access to a server park with all of these different server versions installed. Reality is however almost always a different question: Being an Open Source project with limited funding and developers located throughout the world this has been impossible for us, up until now. You're probably already guessing: The answer is in the Clouds.

Having used Amazon EC2 in a couple of customer projects, we suddenly realized this is the answer to our problems. For those of you not completely familiar with the concept, the general idea of Amazon EC2 is that you configure one or several machine images, installing whatever software and data you might need on each image. You will then start an instance from one of these pre-configured images, which will in effect start up a virtual computer somewhere in the amazon cloud, a computer that will then be yours to play around with in any way you might like until you're finished with it and just shut the instance down. All of this is available at a very reasonable pricing - you pay only (a very modest amount) for the time that your instances have been running.

The concept suits us perfectly: we want a number of isolated environments, each with a known start state where we can run our test suite against a particular server setup. So that's what we've started to do: we have now created an EC2 image with an Open LDAP installation, pre-loaded with the data that our test cases expect. We then devised support classes to have the JUnit test cases automatically start an appropriate instance (using the excellent typica library), run the tests against the started virtual machines, and shut down the instance after the tests are finished (regardless of the outcome - we don't want any stray instances running around costing us money :)). We still have some more work to do with setting up more images for other server setups, but we're hoping to get that work going as we move on...

I'm planning to dig a little bit deeper into the details of the setup and the code involved in a later post. In the meantime: if you're really interested, feel free to check the code out from the svn repo and have a look at what we've done so far. The relevant code for this is in the test/integration-tests-openldap directory.