Red Hat Training

A Red Hat training course is available for Red Hat Fuse

9.5. Enable SSL/TLS on the LDAP Connection

Overview

This tutorial explains how to enable SSL/TLS security on the connection between the LDAP login module and the Apache Directory Server.
The Apache Directory Server is already configured with an SSL endpoint. The default configuration creates an LDAPS endpoint that listens on the IP port 10636. The directory server automatically generates a self-signed X.509 certificate which it uses to identify itself during the SSL/TLS handshake.
Important
You can use the default SSL configuration for simple demonstrations, but it is not suitable for real deployments. For advice on how to configure a real deployment, see the section called “Tightening up security”.

Procedure

To enable SSL/TLS security on the connection to the Apache Directory Server:
  1. Obtain a copy of the server's self-signed certificate.
    1. Using a Web browser , navigate to the following URL: 
      https://localhost:10636
      Important
      Remember to specify the scheme as https, not just http.
      The Web browser now signals an error, because the certificate it receives from the server is untrusted. In the case of Firefox, you will see the following error in the browser window:

      Figure 9.1. Obtaining the Certificate

      invalid certificate warning
    2. Click I Understand the Risks.
    3. Click Add Exception.
      The Add Security Exception dialog opens.
    4. In the Add Security Exception dialog, click Get Certificate.
    5. Click View.
      The Certificate Viewer dialog opens.
    6. In the Certificate Viewer dialog, select the Details tab.
    7. Click Export.
      The Save Certificate To File dialog opens.
    8. In the Save Certificate To File dialog, use the drop-down list to set the Save as type to X.509 Certificate (DER).
    9. Save the certificate, ApacheDS.der, to a convenient location on the filesystem.
  2. Convert the DER format certificate into a keystore.
    1. From a command prompt, change directory to the directory where you have stored the ApacheDS.der file.
    2. Enter the following keytool command: 
      keytool -import -file ApacheDS.der -alias server -keystore truststore.ks -storepass secret
  3. Copy the newly created keystore file, truststore.ks, into the JBoss Fuse etc/ directory.
  4. Open the ldap-module.xml file you created in Section 9.4, “Enable LDAP Authentication in the OSGi Container” in a text editor.
  5. Edit the connection.url to use ldaps://localhost:10636.
  6. Add the highlighted lines in Example 9.3, “LDAP Configuration for Using SSL/TLS”.

    Example 9.3. LDAP Configuration for Using SSL/TLS

    <?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
  xmlns:jaas="http://karaf.apache.org/xmlns/jaas/v1.0.0"
  xmlns:ext="http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0">

  <!-- Example configuration for using LDAP based authentication.
  	   This example uses an JAAS LoginModule from Karaf. 
  	   It supports authentication of users and also supports
  	   retrieving user roles for authorization.

       Note, this config overwrite the default karaf domain
	   that is defined inside some JAR file
       by using a rank > 99 attribute.
  -->
  <jaas:config name="karaf" rank="200">
    <jaas:module className="org.apache.karaf.jaas.modules.ldap.LDAPLoginModule" flags="required">
      initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory
      connection.username=uid=admin,ou=system
      connection.password=secret
      connection.protocol=
      connection.url = ldaps://localhost:10636
      user.base.dn = ou=users,ou=system
      user.filter = (uid=%u)
      user.search.subtree = true
      role.base.dn = ou=users,ou=system
      role.filter = (uid=%u)
      role.name.attribute = ou
      role.search.subtree = true
      authentication = simple
      ssl.protocol=TLSv1
      ssl.truststore=truststore
      ssl.algorithm=PKIX
    </jaas:module>
  </jaas:config>
  
  <jaas:keystore name="truststore"
        path="file:///InstallDir/etc/truststore.ks" keystorePassword="secret" />
</blueprint>
  7. Copy the ldap-module.xml file into the Red Hat JBoss Fuse deploy/ directory.
    The LDAP module is automatically activated.
  8. Test the new LDAP realm by connecting to the running container using the JBoss Fuse client utility.
    1. Open a new command prompt.
    2. Change to the JBoss Fuse install directory.
    3. Enter the following command to log on to the running container instance using the identity jdoe: 
      client -u jdoe -p secret
      You should successfully log into the container's remote console because jdoe does have the admin role.

Tightening up security

The SSL set-up described here is suitable only as a proof-of-concept demonstration. For a real deployment, you must make the following changes to tighten up security:
  • Delete all entries from the Red Hat JBoss Fuse's etc/users.properties file.
    If the ldap-module.xml bundle fails to start up properly, JAAS authentication reverts to the built-in file-based karaf realm, which takes its user data from the users.properties file.
  • Disable the insecure LDAP endpoint on the Apache Directory Server.
  • Create and deploy a properly signed X.509 certificate on the Apache Directory Server.
    See Appendix A, Managing Certificates.
  • Make sure that the LDAP server is configured to use the TLSv1 protocol (POODLE vulnerability). Do not enable the SSLv3 protocol. For more information, see Poodle vulnerability (CVE-2014-3566).

Apache Directory Server Reference

For more details of how to configure SSL/TLS security on the Apache Directory Server, see How to enable SSL.