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.
- ldaps (LDAP over SSL/TLS, port 636)
- 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 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" allowAnonymousAccess="false" saslHost="ldap.example.com" saslPrincipal="ldap/ldap.example.com@EXAMPLE.COM" searchBaseDn="ou=users,ou=system" maxTimeLimit="15000" maxSizeLimit="1000"> <transports> <tcpTransport address="0.0.0.0" port="10389" nbThreads="8" backLog="50" enableSSL="true"/> <tcpTransport address="0.0.0.0" port="10636" enableSSL="true"/> </transports>
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
Option | value | Description |
---|---|---|
-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 |
-alias | apacheds | name to refer the entry within the keystore |
-keystore | apache.ks | keystore file location |
-storepass | secret | password used to protect the integrity of the keystore |
-validity | 365 | number 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" allowAnonymousAccess="false" saslHost="ldap.example.com" saslPrincipal="ldap/ldap.example.com@EXAMPLE.COM" searchBaseDn="ou=users,ou=system" maxTimeLimit="15000" maxSizeLimit="1000" keystoreFile="D:/ApacheDS/conf/apacheds2.jks" certificatePassword="welcome1"> <transports> <tcpTransport address="0.0.0.0" port="10389" nbThreads="8" backLog="50" enableSSL="true"/> <tcpTransport address="0.0.0.0" port="10636" enableSSL="true"/> </transports>
The following properties are used
Property | default value | Description |
---|---|---|
keystoreFile | none | path of the X509 (or JKS) certificate file for LDAPS |
certificatePassword | changeit | password which is used to load the LDAPS certificate file |
port | 10636 | LDAPS TCP/IP port number to listen to |
enableSSL | true | sets 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
- 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.
- Export the certificate - in IE - Tools - Inernet Options - Content tab, click Certificates
- 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
Use the java keytool to import this certificate to the cacerts file at <APP_SERVER_JAVA_HOME>/jre/lib/security
Example: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
- 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.
- Restart the IDS - LDAP service, otherwise you'll see "Error connecting over SSL. Check TrustStore for required certificate"
- Done