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:
Enable LDAP server for SSL communication
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.
-
Request a server certificate:
-
Start iPlanet administrator console.
-
Open the console for the targeted directory server instance where you want to setup SSL.
-
From the "Tasks" tab, choose "Manage Certificates" and click "Request..." to start the "Certificate Request Wizard."
-
Follow the instructions, fill out the form and generate the certificate request. Keep the keystore password in a secure place. You will need this password to start the LDAP server after you enable the SSL option.
-
Send the certificate request to a CA (Certificate Authority) vendor, such as Verisign, for certification.
-
-
Install the certified server certificate:
-
After receiving the certified server certificate, go back to the "Manage Certificate" task in the console and choose "Install."
-
Follow the instructions and install the certificate.
-
-
Install the CA certificate if not already installed:
-
Obtain the CA certificate from the CA if it is not available.
-
After receiving the CA certificate from CA, select the "CA Certs" tab from the "Manage Certificate" task console, and click "Install."
-
Follow the instructions to install the CA certificate. Make sure to check "Accepting Connections from Clients" for the Intended Purpose.
-
You should now see the CA certificate in the "CA Certs" list. Close the "Manage Certificate" task console.
-
-
Configure the encryption option:
-
Choose "Configuration," then the "Encryption" tab from the LDAP server console.
-
Check "Enable SSL for this server."
-
Check "Use this cipher family:RSA," select "Security Device: Internal(software)" and select the certificate you just installed.
-
Ensure the "Require client authentication" radio button isnot selected since ColdFusion MX doesn't support the client authentication.
-
Save the settings.
-
Restart the LDAP server.
-
Enable ColdFusion for SSL communication
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.
Create template using CFLDAP secure communication
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:
<cfldap action="query" name="results" start="ou=People,dc=siroe,dc=com" attributes="cn,sn,ou" sort="cn" server="myldapserver" port="636" password="mypassword" username="cn=Directory Manager" secure="CFSSL_BASIC">
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).
Troubleshooting Tip
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.
