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.

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

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>
 

Note that although this follows the Internet standard for email addresses (RFC 822), some sites simply ignore this and incorrectly disallows addresses with plus signs.

Read more here. More cool mail tips can be found here.