Configuring LDAPS with a Self-Signed Certificate¶
This page explains how to configure Fusion Metadata Registry (FMR) to connect to an LDAPS directory when the directory server presents a self-signed certificate, or a certificate issued by a private internal certificate authority that Java does not already trust.
In these environments, LDAP authentication can be configured correctly in FMR and still fail because the Java runtime used by FMR does not trust the certificate presented by the LDAPS server.
When this guidance is needed¶
You will usually need the steps on this page when all of the following are true:
- FMR is configured to use
ldaps - the LDAP server certificate is self-signed, or signed by an internal CA
- the Java runtime used by FMR does not already trust that certificate chain
Typical symptoms include SSL handshake errors, certificate path validation errors, or login failures that only occur when switching from ldap to ldaps.
Before you change Java trust settings¶
Before importing certificates into Java, first confirm the basics with your LDAP administrator:
- the correct LDAP host name
- the correct LDAPS port, commonly
636 - whether the certificate subject or subject alternative name matches the host name you are using
- whether the server sends only a self-signed certificate or a full certificate chain
Where possible, use the server's DNS host name rather than an IP address. Java's TLS checks are normally performed against the host name used for the connection.
Confirm that the LDAPS endpoint is reachable¶
Before making changes to the Java truststore, it is helpful to verify that the LDAPS service is reachable from the environment where FMR runs.
For example:
ldapsearch -H ldaps://<server>:<port> -x -b "<search base>" -D "<bind DN>" -w "<password>" "(objectClass=inetOrgPerson)"
Example:
ldapsearch -H ldaps://localhost:10636 -x -b "ou=people,dc=planetexpress,dc=com" -D "cn=admin,dc=planetexpress,dc=com" -w "GoodNewsEveryone" "(objectClass=inetOrgPerson)"
If this succeeds, it confirms that:
- the host and port are reachable
- the bind account and search base are valid
- the directory is responding over LDAPS
It does not guarantee that the Java runtime used by FMR trusts the certificate, but it helps separate connectivity problems from Java trust problems.
Export the certificate presented by the LDAPS server¶
You can inspect the certificate chain presented by the server with OpenSSL:
For example:
From the output, copy the relevant certificate block, including:
Save it to a file such as ldap-server.crt.
If your directory uses an internal CA, import the CA certificate that issued the LDAP server certificate rather than only importing the leaf certificate, unless your certificate management process specifically requires the leaf certificate to be trusted directly.
Import the certificate into the Java truststore¶
FMR uses the Java runtime truststore when establishing LDAPS connections. The certificate therefore needs to be trusted by the same Java installation that runs FMR or Tomcat.
The default Java truststore is commonly named cacerts.
Before changing it:
- identify which Java runtime is actually being used by FMR
- back up the existing truststore
- choose a clear alias for the imported certificate
Example command:
keytool -importcert -trustcacerts -alias ldap-server -file ldap-server.crt -keystore <path-to-java>/lib/security/cacerts
On some installations the path may be similar to:
or, on older Java layouts:
keytool will prompt for the truststore password unless you provide it explicitly. The default password for the standard Java cacerts file is often changeit, although this may have been changed in your environment.
After importing the certificate, confirm that the alias is present:
Restart the web application server¶
After updating the truststore, restart the web application server so the Java process reloads its trust configuration.
Host name verification and endpoint identification¶
Java does more than check whether a certificate is trusted. It also normally verifies that the certificate presented by the LDAP server matches the host name used in the LDAPS connection.
If the certificate is trusted but the server certificate was issued for a different name, authentication may still fail.
As a temporary troubleshooting measure, Java endpoint identification for LDAP can be disabled with:
If you are using Apache Tomcat, this can be added to setenv.sh or setenv.bat. For example on Windows:
This setting disables LDAP host name verification. It does not make Java trust every certificate automatically, and it should not be treated as the normal solution for production. The preferred fix is to use:
- the correct LDAP host name in FMR
- a certificate whose subject or subject alternative name matches that host name
- a truststore that contains the correct issuing certificate
Debugging SSL problems¶
If LDAPS still fails after importing the certificate, enable Java SSL debugging temporarily:
For Tomcat on Windows:
For Tomcat on Linux:
After restarting FMR or Tomcat, attempt another login and review the logs. This usually helps distinguish between:
- certificate trust failures
- incomplete certificate chains
- host name mismatch problems
- TLS protocol or cipher negotiation issues
Once troubleshooting is complete, remove the debug flag because SSL debugging produces very verbose logs.
Recommended approach¶
For most FMR deployments using LDAPS with self-signed or private CA certificates, the best approach is:
- Confirm the correct LDAPS host name and port.
- Export the certificate, or preferably the issuing CA certificate.
- Import that certificate into the Java truststore used by FMR.
- Restart FMR or Tomcat.
- Only use
-Dcom.sun.jndi.ldap.object.disableEndpointIdentification=truetemporarily while diagnosing host name mismatch issues.
If you have not yet configured LDAP authentication itself, see LDAPConfiguration.md.