...
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 to, for example, e.g. to man-in-the-middle attacks.
The web services - LDAP server connection can be secured using two commonly available protocols "LDAP over TLS" (STARTTLS) and "LDAP over SSL" (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 in with the security certificate. See here for more information.
...
- 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 calling using LDAPS from the shiro.ini file. Users wishing to configure their server to use LDAPS should refer to their LDAP server administrator.
...
- 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 containldapRealm.useStartTls=true
as shown in the following code 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:
Code Block | ||
---|---|---|
| ||
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:
Flowchart |
---|
JOC [label=" JOC Cockpit ",fillcolor="lightskyblue"]
LDAP [label=" LDAP Server ",fillcolor="lightskyblue"]
JOC_Truststore [label="JOC Cockpit Truststore\n./jetty_base/etc/joc.jks\nCA certificates\nLDAP server public certificate",fillcolor="orange"]
LDAP_Keystore [label="LDAP Server Keystore\nLDAP Server Private Key",fillcolor="orange"]
CA_RootCertificate [shape="ellipse",shape="ellipse",label="CA Root Certificate",fillcolor="white"]
CA_IntermediateCertificate [shape="ellipse",label="CA Intermediate Certificate",fillcolor="white"]
LDAP_PrivateKey [shape="ellipse",label="LDAP Server Private Key",fillcolor="white"]
LDAP_Keystore_Certificate [shape="ellipse",label="LDAP Server Public Certificate",fillcolor="white"]
LDAP_Truststore_Certificate [shape="ellipse",label="LDAP Server Public Certificate",fillcolor="white"]
LDAP -> LDAP_Keystore
LDAP -> LDAP_Truststore_Certificate [label=" transfer to JOC Cockpit "]
LDAP_Keystore -> LDAP_PrivateKey -> LDAP_Keystore_Certificate [label=" in keystore "]
JOC -> JOC_Truststore
JOC_Truststore -> CA_RootCertificate -> CA_IntermediateCertificate [label=" add to truststore "]
CA_IntermediateCertificate -> LDAP_Truststore_Certificate [label=" add to truststore "]
|
Set up a secure connection to your LDAP Server 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
/jettyJETTY_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 Keystore Keytstore that will be created with the private key for the HTTPS support in Jetty. Note that you will probably , 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:
Code Block language bash title Sample Exmple for import master certificateof 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 "my_LDAP_Certificate.pem "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:
Code Block language bash title 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 "my_aliasldap" -keystore "JETTY_BASE/etc/joc.jksp12" -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 file my_LDAP_Certificate.pem has been created on public certificate file
ldap-ertificate.crt
should be available from the LDAP server. Transfer this file to the local machine.certutil -S -n "SOS_LDAP" -s "cn=myCn" -c "SOS_LDAP CA certificate" -t "u,u,u" -m 1001 -v 120 -d . -k rsa
certutil -L -d . -n "SOS_LDAP CA certificate" -a > my_LDAP_Certificate.pem
...
- JOC Cockpit server. Alternatively the public certificate can be requested on-the-fly.
Example for request of public certificate:
Code Block language bash title 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:
Code Block language bash title 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 KeystoreTruststore:- Example for use of a Truststore in JKS format:
Code Block language text title Example for joc.properties setting for a Truststore in JKS format truststore_path = ../../etc/joc.jks
- Specify the location of the Truststore with the
truststore_path
setting. A location relative to theJETTY_BASE
directory can be specified.
- Example for use of a Truststore in JKS format:
Configuration for LDAP over SSL
The LDAP server must be configured to use SSL.
...
truststore_type = jks 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 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 theJETTY_BASE
directory can be specified.
- Specify the location of the Truststore with the