Page History
...
- 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 serverServer. 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 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.
...
STARTTLS in an extension to the LDAP protocol 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 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 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 serverServer. 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 Common Name provided with the LDAP server Server certificate. See here for more information https://shibboleth.net/community/advisories/secadv_20120227.txt for details.
Configuration
Anchor | ||||
---|---|---|---|---|
|
...
LDAP Server URL
: The LDAP Server URL specifies the protocolldap://
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 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 theLDAP 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 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 is specified, typically with a .p12 extension. Other relative locations can be specified using e.g.../../joc-truststore.p12
if the truststore is located in theJETTY_BASE
directory. No absolute path can be specified and no path can be specified that lies before theJETTY_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 eitherPKCS12
orJKS
(deprecated).
...
LDAP Server URL
: The LDAP Server URL specifies the protocolldaps://
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 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.
...
JETTY_BASE
is Jetty's base directory 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)
...
Example for import of a certificate to a JOC Cockpit truststore in PKCS12 format:
Code Block language bash title Example for import of LDAP Server Certificate to PKCS12 Keystore # import LDAP serverServer 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/resources/joc/joc.p12" -storetype pkcs12 -storepass secret_store -trustcacerts
Example for import of a certificate to a JOC Cockpit truststore in JKS format:
Code Block language bash title Exmple for import of LDAP Server certificate to JKS Keystore # import LDAP serverServer 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/resources/joc/joc.jks" -storetype jks -storepass secret_store -trustcacerts
- Explanation
- The
-keystore
option specifies the location of the truststore file. - The
-storepass
option specifies the password for access to the truststore. - The certificate file
ldap-ertificate.crt
should be available from the LDAP serverServer. Transfer this file to the JOC Cockpit server. Alternatively the server certificate can be requested on-the-fly.Example for request of server certificate:
Code Block language bash title Example for request of server certificate from LDAP serverServer # connect to the LDAP serverServer (ldap_server) with the available port (636), in the server response you should find the certificate that you can copy & paste to a certificate file openssl s_client -showcerts -connect ldap_server:636
If the certificate is signed by a CA then the certificate should include the certificate chain of Root CA Certificate and Intermediate CA Certificate. Otherwise it might be required to concatenate the certificates into one file, for example:
Code Block language bash title Example for use of a certificate chain # concatenate Root CA certificate and Intermediate CA certificate as provided from the LDAP serverServer to a single CA Bundle certificate file (ca-bundle.crt) cat RootCACertificate.crt > ca-bundle.crt cat IntermediateCACertificate.crt >> ca-bundle.crt # import LDAP serverServer certificate and certificate chain to a truststore (joc.p12) by specifying the certificate file (ldap-certificate.crt) and alias name (ldap) keytool -importcert -noprompt -file "ca-bundle.crt" -alias "ldap" -keystore "JETTY_BASE/resources/joc/joc.p12" storetype pkcs12 -storepass secret_store -trustcacerts
- The
...
Find examples for entries in the
JETTY_BASE/resources/joc/joc.properties
configuration file to specify a truststore:Example
Code Block language text title Example for joc.properties setting for a truststore in PKCS12 format truststore_path = joc.p12 truststore_type = PKCS12 truststore_password = secret_store
Example
Code Block language text title Example for joc.properties setting for a truststore in JKS format with relative location truststore_path = ../../joc.jks truststore_type = JKS truststore_password = secret_store
Explanation
- Specify the location of the truststore with the
truststore_path
setting. A location relative to theJETTY_BASE/resources/joc
directory can be specified. If a file name only is specified as withjoc.p12
then this directory is assumed. Use of a relative path as with such as../../joc.p12
would locate locates the truststore file in theJETTY_BASE
directory.
- Specify the location of the truststore with the
...