A bug was introduced in JNDI that affects all Java versions above 8. The bug will manifest as a NullPointerException when LDAPS is used, but it affects all JNDI connections. In particular, all functions that perform bind operations will orphan an open connection.

Another bug was introduced more recently in a subset of Java 8 versions that in some cases may be the latest versions available on particular platforms, and this bug is completely fatal to all TLS usage because it causes hostname verification failures.

Unless JNDI is fixed the following instructions can be used to work around the bug.

1. Ensure you have no JNDI-specific properties set in your LDAPConnector or JAASAuthnConfiguration files. JNDI properties typically would have "jndi" in the property name. Where necessary, they can usually be converted to generic settings, but feel free to ask if you can't find the documented equivalents.
   
   1. In particular, if you have any attributes defined as binary via "java.naming.ldap.attributes.binary", you will need to replace that with the <BinaryAttributes> element within the LDAPConnector.
2. Ensure that
   • your ldaps URL, if any, does not end in a slash, as this seems to be something the UnboundID provided doesn't handle that JNDI did. Unclear which one is strictly correct, but it's a simple workaround.
   • your LDAP filters do not contain blanks, there was a case (with Active Directory) when the UnboundID provider would not accept such filters

Then follow one of the two sections below, as appropriate.

This configuration should then use the UnboundID library for all LDAP operations. You can log on DEBUG and observe the connection handling in the log and verify this.

V3.4.4+

We now include, and will maintain, the necessary jars in the distribution and have embedded a new property that can be set via ldap.properties (or any other property file loaded):

idp.ldaptive.provider=org.ldaptive.provider.unboundid.UnboundIDProvider

Prior to V3.4.4

1. Add -Dorg.ldaptive.provider=org.ldaptive.provider.unboundid.UnboundIDProvider as a runtime switch to Java.
   • For example, on Jetty, it can be added to start.ini or another ini file loaded from the start.d directory.

   • On Windows if you are running procrun (includes the Jetty software installed by the Shibboleth Windows Installer), you set this via the "Java Options" table of the "Java" tab of the "Commons Daemon Service Manager" (C:\Program Files (x86)\Shibboleth\ProcRun\shibd_idpw.exe for a Shibboleth Windows installation, and tomcatw.exe for a Tomcat installation).

2. Add the ldaptive-unboundid-1.0.13.jar and unboundid-ldapsdk-4.0.9.jar libraries to your classpath
   • Typically this is done by adding them to the edit-webapp directory and rebuilding your warfile via bin/build.sh or bin/built.bat

References

https://bugs.openjdk.java.net/browse/JDK-8217606

https://mail.openjdk.java.net/pipermail/jdk8u-dev/2020-October/012887.html