Terry : Configure Apache Directory Server for SSL

Configure Apache Directory Server for SSL (LDAPS)

Transport layer security and LDAP

Several requirements related to security can be easily accomplished with the help of SSL technology (Secure Socket Layer) or its standardized successor TLS (Transport Layer Security, RFC 2246). Among these are the protection of data against eavesdropping and modification, when on transit between client and server (data integrity), and the authentication of a server toward a client with the help of a certificate.

There are two approaches to utilize these technologies in the LDAP world.

  1. ldaps (LDAP over SSL/TLS, port 636)
  2. StartTLS (extended operation)

The first option is comparable to HTTPS and inserts an SSL/TLS layer between the TCP/IP protocol and LDAP. Establishing a connection like this is normally provided via a different server port (port 636 is common, it is a well-known port, like port 389 is for LDAP). In URIs the schema "ldaps" is specified (for instance ldaps://fmw11g.vm.oracle.com:636/ ) instead of "ldap". It is possible to write programs which switch between ldap and ldaps without changes in the source, if the connection data is configured external.

In the second option a client establishes at first a "normal" LDAP connection. With a special request (extended operation StartTLS) it tries to switch to secure communication afterwards. It is not necessary to change the port for this, the communication continues on the established connection. The client may go back to the original connection state ("TLS Closure Alert"), in doing so protecting only selected parts of the communication.

Both ways to utilize SSL/TLS within LDAP require the configuration of the server with an appropriate certificate.

Server Configuration

ApacheDS 1.5.x supports both options and requires a JDK 1.5 or above. The feature is enabled by default, but you may need to configure it. There are some steps to follow in order to obtain a SSL enabled server.


In order to keep it simple for beginners, you don't need any certificate to get LDAPS working. The latest version generates its own self signed certificate. From the user point of view, it's just a matter of enabling the ldaps service to get it working.

However, if one wants to use a signed certificate, another configuration is needed, where you tell the server about the keystore to use, and the certificate password to use. 

In case you want ApacheDS to generate the certificate

There is nothing to do but enabling SSL and specifying the port to use in the server.xml configuration file

 | LDAP Service configuration |
 <ldapServer id="ldapServer"
 <tcpTransport address="" port="10389" nbThreads="8" backLog="50" enableSSL="true"/>
 <tcpTransport address="" port="10636" enableSSL="true"/>

That's it, the server is LDAPS capable !

The default server.xml configuration file contains an typo, by default the port is set to 10686.

In case you want to use an external keystore

A certificate is a signed public key (signed normally by a third party, a certificate authority, CA).

There are different options

  • either you buy a certificate from a Certificate Authority (like Verisign, etc.), or you obtain one from your enterprise CA, if available
  • or you ask for a free certificate from CACERT organisation
  • or you create your own certificate, self-signed or signed by your private CA, which will not be trusted.

We will do it the last way (self-signed), primarily because it's easy and fast (you won't have to pay nor to wait to obtain your certificate)

Key creation

First it is necessary to create a key pair (public/private key) for your server, zanzibar in our case. One option is to use the JDK tool keytool for this task. In the following example, we use these options

-genkey command to generate a key pair
-keyalg"RSA"algorithm to be used to generate the key pair, in our case, default is "DSA"
-dname"cn=apacheds, ou=ApacheDS, o=ASF, c=US"the X.500 Distinguished Name to be associated with alias, used as the issuer and subject fields in the self-signed certificate
-aliasapachedsname to refer the entry within the keystore
-keystoreapache.kskeystore file location
-storepasssecretpassword used to protect the integrity of the keystore
-validity365number of days for which the certificate should be considered valid, default is 90

For example

keytool -genkeypair -keyalg RSA -dname "dname" -alias alias -keypass key_password -keystore keystore -storepass keystore_password -validity days_valid

oracle@fmw11g.vm.oracle.com $ /refresh/oracle/sun-jdk/jdk1.6.0_24/bin/./keytool -genkeypair -keyalg RSA -dname "cn=fmw11g,dc=vm,dc=oracle,dc=com" -alias webcenter_wls -keypass welcome1 -keystore webcenter_wls.jks -storepass welcome1 -validity 3650

Another option is to use graphical tools for key creation like Portecle, which is basically a user-friendly front-end for keytool with comparable functionality.

Learn more about keytool at the manpage or Configuring SSL TLS For WebCenter

Sample output (Create a RSA 2048 bits and SHA256withRSA key pair)

keytool -genkeypair -alias apacheds2 -keyalg RSA -keysize 2048 -dname "cn=wlp,dc=au,dc=oracle,dc=com" -sigalg SHA256withRSA -keypass welcome1 -keystore apacheds2.jks -storepass changeit -validity 3650

List certificates in the keystore

keytool.exe -list -keystore apacheds2.jks
Enter keystore password:
Keystore type: JKS
Keystore provider: SUN
Your keystore contains 1 entry
apacheds2, Jun 7, 2012, PrivateKeyEntry,
Certificate fingerprint (MD5): B9:E7:C5:04:25:24:F3:6C:A6:AF:91:5F:22:C4:EF:D3
Configuring ApacheDS to use this external keystore

Enabling SSL in Apache Directory Server and using the key pair created as above is quite easy. Simply put the keystore file in the conf directory of ApacheDS, and enable ldaps. Here is the fragment from server.xml on how to do so.

 | LDAP Service configuration |
 <ldapServer id="ldapServer"
 <tcpTransport address="" port="10389" nbThreads="8" backLog="50" enableSSL="true"/>
 <tcpTransport address="" port="10636" enableSSL="true"/>

The following properties are used

Propertydefault valueDescription
keystoreFilenonepath of the X509 (or JKS) certificate file for LDAPS
certificatePasswordchangeitpassword which is used to load the LDAPS certificate file
port10636LDAPS TCP/IP port number to listen to
enableSSLtruesets if SSL is enabled or not

After modification of the server.xml, the server has to be restarted in order to take effect.

Verification, Clients

After restarting the server, you should have a server offering both ldap and ldaps.

Optional: Configure SSL Between WebCenter Interaction Identity Service for LDAP and the LDAP Server
  1. Access ldaps:hostname:10636 or https://hostname:10636 using browser (IE in this case), LDAPS will probably trigger LDAP Browser if installed, import (install) the self-signed certificate. 
  2. Export the certificate - in IE - Tools - Inernet Options - Content tab, click Certificates
  3. Find the certificate for the LDAP server just imported and export it as DER encoded binary (.cer), put it in APP_SERVER_JAVA_HOME/jre/lib/security
  4. Use the java keytool to import this certificate to the cacerts file at <APP_SERVER_JAVA_HOME>/jre/lib/security

    keytool -importcert -trustcacerts -alias apacheds2 -file apacheds2.cer -keystore cacerts -storepass changeit
    Owner: CN=wlp, DC=au, DC=oracle, DC=com
    Issuer: CN=wlp, DC=au, DC=oracle, DC=com
    Serial number: 4fd03b2b
    Valid from: Thu Jun 07 13:24:59 GMT+08:00 2012 until: Sun Jun 05 13:24:59 GMT+08
    :00 2022
    Certificate fingerprints:
     MD5: B9:E7:C5:04:25:24:F3:6C:A6:AF:91:5F:22:C4:EF:D3
     SHA1: AC:8F:81:05:F2:8E:52:F8:AE:96:25:B9:BE:4F:90:7A:74:66:C4:4A
     Signature algorithm name: SHA256withRSA
     Version: 3
    Trust this certificate? [no]: yes
    Certificate was added to keystore
  5. When you create the authentication source in the portal, enter 2 as the Security Mode. The standard SSL port is 10636. If your LDAP server is using a different SSL port, enter this in the Alternate Port box.
  6. Restart the IDS - LDAP service, otherwise you'll see "Error connecting over SSL. Check TrustStore for required certificate"
  7. Done


How to enable SSL