ColdFusion MX: Configuring Secure SSL Connection with LDAP Directory Server

The cfldap tag in ColdFusion MX provides a convenient interface for users to access LDAP directory servers. To provide additional security, you may choose to use secure SSL connections between ColdFusion and the LDAP server. This TechNote provides step-by-step instructions for configuring an SSL connection between ColdFusion MX and an LDAP server. These instructions use iPlanet LDAP server 5.0.

There are three steps required to set up and use a secure SSL connection between ColdFusion MX and the LDAP server:

First, you need to prepare the LDAP server and enable the SSL option for the target server. This involves requesting a server certificate, installing certificates, and configuring the LDAP encrypt option.

Now that the LDAP server is ready, you will need to configure the ColdFusion server. Since SSL is a two-way trusted communication, the client, ColdFusion in this case, needs to trust and accept the server certificate. The trust can be established by directly knowing the LDAP server certificate or knowing the CA who cerified the server. In ColdFusion, LDAP SSL is implemented using the JSSE specification. The trust can be achieved by importing either the LDAP server certificate or the CA certificate into the Java trusted key store used by ColdFusion.

The default Java trusted key store is called "cacerts", which is located in the {java.home}/jre/lib/security/ directory (or /System/Library/Frameworks/JavaVM.framework/Versions/CurrentJDK/Home/lib/security/ on Max OS X). You will use the Java keytool utility to manage the key store. You may find the keytool utility under either {java.home}/bin/ or {java.home}/jre/bin (keytool.exe for Windows; keytool for UNIX/Linux). Add the keytool path to your command path first for ease of use.

From DOS prompt on Windows:

set PATH=%PATH%;{java.home}/jre/bin

On UNIX/Linux:

export PATH=%PATH;{java.home}/jre/bin

Note: Replace values in braces { } with your own environment setting.

Enter the following command (type on one line) to import the certificate:

keytool -import -keystore cacerts -file {myldapservercert.cer or CAservercert.cer} -alias ldapserver-cert -storepass changeit

The password for the cacerts truststore is "changeit" by default. After import, you may confirm that you have imported the certificate properly by using the following command (type on one line):

keytool -list -keystore cacerts -alias ldapserver-cert -storepass changeit -v

This will list the content of your certificate.

The certificate must be in a Base64-encoded X.509 format. If you get an "Input not an X.509 certificate" error while importing, this may be due to a bug in the version of JDK/JRE and you try to download JDK 1.4.2_03 or later from Sun. Also remember to switch the JDK/JRE used by ColdFusion by editing the java.home property in the jvm.config file.

If you are using JRun as the underlying J2EE server (either the Server Configuration or the J2EE with JRun Configuration) and have enabled SSL for the internal JRun web server(JWS), you will need to import the certificate to the truststore defined in the jrun.xml file for the Secure JWS rather than the JRE key store. By default, the file is called "trustStore" and is typically located underjrun_root/lib for the J2EE with JRun configuration or cf_root/runtime/lib for the ColdFusion Server configuration. You will use the same Java keytool to manage the trustStore.

Now that the SSL connection is configured, you can write the cfldap code to use that secure connection. You only need to specify the secure attribute as "CFSSL_BASIC" in the cfldap tag and the secure LDAP port (636 by default).

For example:

Unlike ColdFusion 5, the cert7.db file is not needed any more. Also, cfldap provides limited support for SSL v3 client authentication (user certificate authentication) in ColdFusion MX. Due to a limitation in the JSSE implementation only one client certificate can be used for client authentication and that certificate must be the first one in the certificate store. CFMX does provide full support for SSL v2 (basic username/password authentication over SSL).

If you have trouble connecting to your LDAP server using cfldap, it is always a good idea to use a third party tool to verify if the LDAP server is working properly. LDAP browser by Jarek Gawor proves to be a very useful tool. Beginning with build 2.8.1 of the program, it supports SSL as well.

• ColdFusion: Maximum SSL encryption levels by version
• ColdFusion MX: TCP/IP ports used
• Importing RSA 2048- and 4096-bit certificates into cacerts