Product Knowledge Base

Space shortcuts

Page tree

Introduction

LDAP authentication for the JOC Cockpit relies on a connection between the JOC Cockpit web services and the LDAP server. It is desirable that this connection is secured as it would otherwise be vulnerable e.g. to man-in-the-middle attacks.

The LDAP server connection can be secured using two commonly available protocols "LDAP over TLS" (STARTTLS) and "LDAP over SSL" (LDAPS).

Connection Content Encryption with StartTLS

StartTLS in an extension to the LDAP protocol which uses the TLS protocol to encrypt communication. It works by establishing a normal - i.e. unsecured - connection with the LDAP server before a handshake negotiation between the server and the web services is carried out. Here, the server sends its certificate to prove its identity before the secure connection is established. If negotiation for a secure connection is unsuccessful then a standard LDAP connection may be opened. Whether or not this occurs depends on the LDAP server and its configuration.

Connection Encryption with LDAPS

LDAPS is the non-standardized "LDAP over SSL" protocol that in contrast with StartTLS only allows communication over a secure port such as 636. It establishes the secure connection before there is any communication with the LDAP server. However, as LDAPS is not part of the LDAP standard, there is no guarantee that LDAPS client libraries actually verify the host name against the name provided with the security certificate. See here for more information.

Scope

  • The current article describes the configuration of StartTLS for use with the JOC Cockpit web services and Web Service Truststore, as well as providing a code example for using LDAPS from the shiro.ini file. Users wishing to configure their server to use LDAPS should refer to their LDAP server administrator.

Configuration for LDAP over TLS

  • The Java Keytools is installed with your Java JRE.
  • Your LDAP server is configured to use STARTTLS.

  • When using starttls your LDAP realm configuration in the shiro.ini configuration file should contain ldapRealm.useStartTls=true as in the following example:

    ldapRealm = com.sos.auth.shiro.SOSLdapAuthorizingRealm
ldapRealm.contextFactory.url = ldap://myHost:389
ldapRealm.useStartTls=true
 
securityManager.realms = $ldapRealm

Configuration for LDAP over SSL

The LDAP server must be configured to use SSL.

In the shiro.ini configuration file the LDAPS URL must use a fully qualified domain name (FQDN) as in the following example:

ldapRealm = com.sos.auth.shiro.SOSLdapAuthorizingRealm
ldapRealm.contextFactory.url = ldaps://ldap.myHost.com:636

ldapRealm.contextFactory.environment[java.naming.security.protocol] = ssl
 
securityManager.realms = $ldapRealm

.

Certificate Management

For both TLS and SSL the public certificates should be distributed as follows:


Set up a secure connection to your LDAP Server

In the following the placeholders JOC_HOME, JETTY_HOME and JETTY_BASE are used which locate three directories. If you install Jetty with the JOC installer then

  • JOC_HOME is the installation path which is specified during the JOC Cockpit installation:
    • C:\Program Files\sos-berlin.com\joc (default on Windows)
    • /opt/sos-berlin.com/joc (default on Linux)
  • JETTY_HOME = JOC_HOME/jetty
  • JETTY_BASE is Jetty's base directory which is specified during the JOC Cockpit installation:
    • C:\ProgramData\sos-berlin.com\joc (default on Windows)
    • /home/<setup-user>/sos-berlin.com/joc (default on Linux)

Create a JOC Cockpit Truststore and import public certificates

The following steps are performed on the server that hosts the JOC Cockpit.

You can use the Java Keytstore that will be created with the private key for the HTTPS support in Jetty, see JOC Cockpit - HTTPS Authentication. Otherwise you might have to create the JETTY_BASE/etc directory.

    • Example for import of a public certificate to a JOC Cockpit Truststore in JKS format:

      Exmple for import of LDAP Server public certificate to JKS Keystore
      # import LDAP server public certificate to a truststore (joc.jks) by specifying the certificate file (ldap-certificate.crt) and alias name (ldap)
keytool -importcert -noprompt -file "ldap-certificate.crt" -alias "ldap" -keystore "JETTY_BASE/etc/joc.jks" -storepass secret_store -trustcacerts

    • Example for import of a public certificate to a JOC Cockpit Truststore in PKCS12 format:

      Exmple for import of LDAP Server public certificate to PKCS12 Keystore
      # import LDAP server public certificate to a truststore (joc.p12) by specifying the certificate file (ldap-certificate.crt) and alias name (ldap)
keytool -importcert -noprompt -file "ldap-certificate.crt" -alias "ldap" -keystore "JETTY_BASE/etc/joc.p12" -storetype pkcs12 -storepass secret_store -trustcacerts
  • The -keystore option specifies the location of your Truststore file.
  • The -storepass option specifies the password for access to your Truststore file.
  • The public certificate file ldap-ertificate.crt should be available from the LDAP server. Transfer this file to the JOC Cockpit server. Alternatively the public certificate can be requested on-the-fly.

    • Example for request of public certificate:
       

      Example for request of public certificate from LDAP server
      # connect to the LDAP server (ldap_server) with the available port (636), in the server response you should find the public certificate that you can copy & paste to a certificate file
openssl s_client -connect ldap_server:636
  • If the public certificate is signed by a CA then the certificate should include the certificate chain of CA Root Certificate and CA Intermediate Certificate. Otherwise it might be required to concatenate the certificates into one file, for example:


    Example for export of public certificate
    # concatenate CA root certificate and CA intermediate certificate to a single CA Bundle certificate file (ca-bundle.crt)
cat RootCACertificate.crt > certificates.crt
cat CACertificate.crt >> certificates.crt
cat ldap-certificate.crt >> certificates.crt

# import LDAP server public certificate and certificate chain to a truststore (joc.jks) by specifying the certificate file (ldap-certificate.crt) and alias name (ldap)
keytool -importcert -noprompt -file "certificates.crt" -alias "ldap" -keystore "JETTY_BASE/etc/joc.jks" -storepass secret_store -trustcacerts

Configure JOC Cockpit Truststore

  • Edit the following entries in the JETTY_BASE/resources/joc/joc.properties configuration file corresponding to the Java Truststore:

    • Example for use of a Truststore in JKS format:


      Example for joc.properties setting for a Truststore in JKS format
      truststore_path = ../../etc/joc.jks
truststore_type = jks
truststore_password = secret_store
    • Example for use of a Truststore in PKCS12 format:


      Example for joc.properties setting for a Truststore in PKCS12 format
      truststore_path = ../../etc/joc.p12
truststore_type = pkcs12
truststore_password = secret_store

    • Explanations

      • Specify the location of the Truststore with the truststore_path setting. A location relative to the JETTY_BASE directory can be specified.