Integrating with LDAP/LDAPS server
The LDAP server can be configured in the Portal Dedicated UI if connecting to a LDAP server or a LDAPS server with a valid CA issued certificate.
The format of the server connection is:
ldap://myldapserver.com:389
or for LDAPS:
ldaps://myldapserver.com:636
Note that ports 389 and 636 are the defaults for each protocol.
The connection can be tested via the UI in order to ensure the Portal Dedicated can communicate with the LDAP/LDAPS server.
If the LDAPS communication failed there are certain manual steps that can taken to trust a certificate.
The following steps are not recommended as it indicates an issue with SSL certificate which should be fixed rather than adding workarounds to trust the certificate.
Manually trusting a certificate
To trust a certificate a trust store must be created with the certificate and configured for use by the Portal Dedicated.
The error usually seen when the Portal Dedicated is trying to communicate with a server which has an invalid or self-signed certificate is similar to:
sun.security.validator.ValidatorException: PKIX path
building failed: sun.security.provider.certpath.SunCertPathBuilderException:
unable to find valid certification path to requested target
It is recommended to use a valid CA issued certificate rather than adding a trust store
To create a new truststore with a certificate (provided by the person who is responsible for the LDAPS configuration) we have to execute the following command:-
keytool -keystore truststore.jks -alias clientcert -import -file certificate.crt
Then it will ask you to enter a password for your new truststore and to confirm that you trust to certificate that was provided.
If you already have a truststore and you want to use an existing one, you can import a valid certificate by :-
keytool -importcert -keystore /path/to/truststore.jks -alias clientcert -file certificate.crt
In the Portal Dedicated systemd service script add 2 extra properties for the truststore, for example:
ExecStart=__PORTAL_HOME__/jre/bin/java \
-Djavax.net.ssl.trustStore=/path/to/truststore.jks \
-Djavax.net.ssl.trustStorePassword=passwordProvidedDuringCreationOfTheTruststore \
-jar /path/to/portal.jar
javax.net.ssl.trustStore should point to the location of the JKS trust store containing the trusted Root or other certificate in the chain of trust for the LDAPS server certificate
javax.net.ssl.trustStorePassword refers to the password for the trust store
After editing the service script the daemon needs to be reloaded:
sudo systemctl daemon-reload
And the Portal Dedicated should be restarted and the LDAPS connection retested.
Disabling certificate hostname verification
If the LDAPS certificate doesn’t match the domain name of the server there will be an error during communication.
The specific error message may vary but will be similar to:
javax.naming.CommunicationException: : [Root exception is javax.net.ssl.SSLHandshakeException: java.security.cert.CertificateException: No subject alternative names matching IP address found]
It is recommended to fix the certificate, but to workaround, the Portal Dedicated can be started with an extra property to disable the host verification.
In the Portal Dedicated systemd service script add com.sun.jndi.ldap.object.disableEndpointIdentification=true, for example:
ExecStart=__PORTAL_HOME__/jre/bin/java \
-Dcom.sun.jndi.ldap.object.disableEndpointIdentification=true \
-jar /path/to/portal.jar
...
After editing the service script the daemon needs to be reloaded:
sudo systemctl daemon-reload
And the Portal Dedicated should be restarted and the LDAPS connection retested.