Introduction

• LDAP authentication for the JOC Cockpit is offered from the JS7 - LDAP Identity Service and relies on a connection between

...

• the JS7 - REST Web Service API 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).
• This article describes the configuration of STARTTLS for use with the JS7 REST Web Service API and and a certificate truststore, as well as providing an example for use with LDAPS. Users wishing to configure their server to use LDAPS should refer to their LDAP server administrator.

Secure Connection Schemes

Connection Content Encryption with

...

STARTTLS

StartTLS STARTTLS in an extension to the LDAP protocol which that 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 service 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 as a fallback. 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 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 LDAP server 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:

  Code Block
  language text
  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

...

Configuration

Anchor
configuration_ldap_tls configuration_ldap_tls

Configuration for LDAP over TLS

When managing the LDAP Identity Service the following settings are offered:

Image Added

Explanation:

• LDAP Server URL: The LDAP Server URL specifies the protocol ldap:// for the TLS connection. The protocol is added the hostname (FQDN) and port of the LDAP Server. No IP address can be used as it would not match the LDAP server certificate.
• LDAP Start TLS: This switch makes TLS the protocol for the connection to the LDAP Server.
• LDAP Host Name Verification: This switch has to be active to check if hostnames in the LDAP Server URL and in the LDAP Server certificate match.
• LDAP Truststore Path: The TLS protocol requires a truststore to be used that holds an X.509 certificate specified for the Extended Key Usage of Server Authentication.
  • The truststore can include a self-signed certificate or a CA-signed certificate. Typically the Root CA certificate is used as otherwise the complete certificate chain involved in signing the Server Authentication certificate has to be available with the truststore.
  • If this setting is not specified then JOC Cockpit will use the truststore that is configured with the JETTY_BASE/resources/joc/joc.properties configuration file. This includes use of settings for the truststore password and truststore type.
  • The path to the truststore is specified relative to the JETTY_BASE/resources/joc directory. If the truststore is located in this directory then specify the file name only, typically with a .p12 extension. Other relative locations can be specified using e.g. ../../joc-truststore.p12 if the truststore is located in the JETTY_BASE directory. No absolute path can be specified and no path can be specified that lies before the JETTY_BASE directory in the file system hierarchy.
• LDAP Truststore Password: If the LDAP truststore is protected by a password, then the password has to be specified.
• LDAP Truststore Type: The type of the indicated truststore has to be specified being either PKCS12 or JKS (deprecated).

Anchor
configuration_ldap_ssl configuration_ldap_ssl

Configuration for LDAP over SSL

When managing the LDAP Identity Service the following settings are offered:

Image Added

Explanation:

• LDAP Server URL: The LDAP Server URL specifies the protocol ldaps:// for the SSL connection. The protocol is added the hostname (FQDN) and port of the LDAP Server. No IP address can be used as it would not match the LDAP server certificate.
• LDAP Start TLS: This switch is not used as it would make TLS the protocol for the connection to the LDAP Server.
• For the remaining settings see explanations from chapter Configuration for LDAP over TLS.

Certificate Management

For use with both TLS and SSL protocols the certificates are distributed in a similar way.

Use with CA signed Certificates

JOC [label="   JOC Cockpit   ",fillcolor="lightskyblue",fontname="Arial",fontsize="10pt"]
LDAP [label="   LDAP Server   ",fillcolor="lightskyblue",fontname="Arial",fontsize="10pt"]
 
JOC_Truststore [label="JOC Cockpit Truststore\n./jetty_base/resource/etcjoc/joc.jksp12\nCA certificates\nLDAP server public certificate",fillcolor="orange",fontname="Arial",fontsize="10pt"]
LDAP_Keystore [label="LDAP Server Keystore\nLDAP Server Private Key\nLDAP Server Certificate",fillcolor="orange",fontname="Arial",fontsize="10pt"]

CA_RootCertificate [shape="ellipse",shape="ellipse",label="CA Root Certificate",fillcolor="white",fontname="Arial",fontsize="10pt"]
CA_IntermediateCertificate [shape="ellipse",label="CA Intermediate Certificate",fillcolor="white",fontname="Arial",fontsize="10pt"]

LDAP_PrivateKey [shape="ellipse",label="LDAP Server Private Key",fillcolor="white",fontname="Arial",fontsize="10pt"]
LDAP_Keystore_Certificate [shape="ellipse",label="LDAP Server Public Certificate",fillcolor="white",fontname="Arial",fontsize="10pt"]

LDAP -> LDAP_Keystore 
LDAP_Keystore -> LDAP_PrivateKey -> LDAP_TruststoreKeystore_Certificate [shapelabel="ellipse in keystore ",labelfontname="LDAP Server Public CertificateArial",fillcolorfontsize="white10pt"]

LDAPJOC -> JOC_Truststore
JOC_Truststore -> CA_RootCertificate -> LDAP_Keystore 
LDAPCA_IntermediateCertificate [label=" add to truststore ",fontname="Arial",fontsize="10pt"]
CA_IntermediateCertificate -> LDAP_TruststoreKeystore_Certificate [label=" transferverify to JOC Cockpitin handshake ",fontname="Arial",fontsize="10pt"]

Use with self-signed Certificates

JOC [label="   JOC Cockpit   ",fillcolor="lightskyblue",fontname="Arial",fontsize="10pt"]
LDAP [label="   LDAP Server   ",fillcolor="lightskyblue",fontname="Arial",fontsize="10pt"]
 
JOC_Truststore [label="JOC Cockpit Truststore\n./jetty_base/resource/joc/joc.p12\nLDAP Server Certificate",fillcolor="orange",fontname="Arial",fontsize="10pt"]
LDAP_Keystore [label="LDAP Server Keystore\nLDAP Server Private Key\nLDAP Server Certificate",fillcolor="orange",fontname="Arial",fontsize="10pt"]

LDAP_PrivateKey [shape="ellipse",label="LDAP Server Private Key",fillcolor="white",fontname="Arial",fontsize="10pt"]
LDAP_Keystore_Certificate [shape="ellipse",label="LDAP Server Certificate",fillcolor="white",fontname="Arial",fontsize="10pt"]
LDAP_Truststore_Certificate [shape="ellipse",label="LDAP Server Certificate",fillcolor="white",fontname="Arial",fontsize="10pt"]

LDAP -> LDAP_Keystore 
LDAP -> LDAP_Truststore_Certificate [label=" transfer to\nJOC Cockpit\ntruststore ",fontname="Arial",fontsize="10pt"]
LDAP_Keystore -> LDAP_PrivateKey -> LDAP_Keystore_Certificate [label=" in keystore ",fontname="Arial",fontsize="10pt"]

JOC -> JOC_Truststore
JOC_Truststore -> CA_RootCertificate -> CA_IntermediateCertificateLDAP_Truststore_Certificate [label=" add to truststore ",fontname="Arial",fontsize="10pt"]
CALDAP_Truststore_IntermediateCertificateCertificate -> LDAP_TruststoreKeystore_Certificate [label=" addverify toin truststorehandshake ",fontname="Arial",fontsize="10pt"]

Set up

...

JOC Cockpit Truststore and import Certificates

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

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

• JETTY_
• 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 that 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.

Consider information from the JS7 - JOC Cockpit HTTPS Connections articles about truststores.

Example how to import Certificates

The following examples suggest use of the Java keytool utility, however, other tools might be applicable such as the OpenSSL CLI, Keystore Explorer etcYou 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

• truststore in

JKS

• PKCS12 format:

  Code Block
  language bash title

Exmple

• Example for import of LDAP Server

public certificate

• Certificate to

JKS

• PKCS12 Keystore

  # import LDAP server

public

• certificate to a truststore (joc.

jks

• 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/resources/

etc

• joc/joc.

jks

• p12" -storetype pkcs12 -storepass secret_store -trustcacerts

• Example for import of a

public

• certificate to a JOC Cockpit

Truststore

• truststore in

PKCS12

• JKS format:

  Code Block
  language bash title Exmple for import of LDAP Server

public

• certificate to

PKCS12

• JKS Keystore

  # import LDAP server

public

• certificate to a truststore (joc.

p12

• 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/resources/

etc

• joc/joc.

p12

• jks" -storetype

pkcs12

• jks -storepass secret_store -trustcacerts

• Explanation
  • The -keystore option specifies the location of
  your Truststore
  • the truststore file.
  • The -storepass option specifies the password for access to
  your Truststore file
  • the truststore.
  • 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
  • server certificate can be requested on-the-fly.

    • Example for request of

    public

    • server certificate:
       

      Code Block
      language bash title Example for request of

    public

    • server 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 -showcerts -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:
      
      

      Code Block
      language bash title Example for

  export

  • • use of

  public

  • • a certificate chain

      # concatenate CA root certificate and CA intermediate certificate as provided from the LDAP server to a single CA Bundle certificate file (ca-bundle.crt) cat RootCACertificate.crt >

  certificates

  • • ca-bundle.crt cat

  CACertificate

  • • IntermediateCACertificate.crt >>

  certificates.crt cat ldap-certificate.crt >> certificates.crt

  • • ca-bundle.crt # import LDAP server

  public

  • • certificate and certificate chain to a truststore (joc.

  jks

  • • p12) by specifying the certificate file (ldap-certificate.crt) and alias name (ldap) keytool -importcert -noprompt -file "

  certificates

  • • ca-bundle.crt" -alias "ldap" -keystore "JETTY_BASE/resources/

  etc

  • • joc/joc.

  jks

  • • p12" storetype pkcs12 -storepass secret_store -trustcacerts

...

Example how to configure the JOC Cockpit Truststore

• Edit the following Find examples for entries in the JETTY_BASE/resources/joc/joc.properties configuration file corresponding to the Java Truststoreto specify a truststore:

  • Example

    for use of a Truststore in JKS format:

    Code Block
    language text title Example for joc.properties setting for a Truststore truststore in JKS PKCS12 format
    truststore_path = ../../etc/joc.jksp12 truststore_type = jksPKCS12 truststore_password = secret_store

  • Example

    for use of a Truststore in PKCS12 format:

    Code Block
    language text title Example for joc.properties setting for a Truststore truststore in PKCS12 JKS format with relative location
    truststore_path = ../../etc/joc.p12jks truststore_type = pkcs12JKS truststore_password = secret_store

  • ExplanationsExplanation

    • Specify the location of the Truststore truststore with the truststore_path setting. A location relative to the JETTY_BASE/resources/joc directory can be specified. If a file name only is specified as with joc.p12 then this directory is assumed. Use of a relative path as with ../../joc.p12 would locate the truststore file in the JETTY_BASE directory.