LDAPS Configuration (ActiveDirectory with SSL)

LDAPS Configuration (ActiveDirectory with SSL)

Background

This instruction has been written following the publication of the Microsoft article “2020 LDAP channel binding and LDAP signing requirement for Windows” (https://support.microsoft.com/en-us/help/4520412/2020-ldap-channel-binding-and-ldap-signing-requirement-for-windows ) which suggests that non-secure connections to Active Directory may no longer work after installing the security update scheduled by Microsoft for March 2020.

Introduction

In order to configure a Comflow instance to use secure connections to the Active Directory, you need to:

1. Import certificate
2. Add certificate to truststore (optional)
3. Update sitedef
4. Change Comflow launch configuration
5. Re-start

(1) Acquire a root (or intermediate) certificate for your customer’s organization, (which is installed in the Domain Controllers/DC) that you shall import it into the default JVM truststore on the Comflow instance. The IT responsible at your customer should be able to provide you with such a certificate (.cer file). Find out the host names of all Domain Controllers that will potentially be used for querying the Active Directory from Comflow. Ask the IT responsible if you don’t know.

(2) (Optional) Run the Corzia-supplied tool to get confirmation that a secure connection can be established to each DC server and to clone the JVM default truststore to a Comflow-specific truststore. The idea of not relying on the JVM default truststore in the default location is that you should not accidentally forget the certificates if you install a new version of Java. (In case you do that, you should still re-run the tool to get the latest certs supplied with Java combined with your own, but at least LDAPS will not stop working only because you have switched to a newer JDK.)

(3) Change URL settings in sitedef.xml and deploy it.

(4) If your Java version is 1.8.181 or higher, you need to add an argument to the Java launch configuration

(5) Re-start Comflow

Import Certificate

The IT responsible at your customer should be able to give you a certificate (.cer file) that is signed by a Certification Authority, or alternatively, an ”intermediate certificate”, that has been issued using a CA-signed certificate.

Create a folder called ”Certificates” under the ”Corzia” folder and place the .cer file in that folder.

Then open an elevated command prompt like Windows PowerShell as adminstrator (”Run as Administrator”) Use the cd command to position your current directory to your jvm, like:

$JAVA_HOME/jdk1.8.0_232/bin

(assuming jdk1.8.0_232 is your JDK folder).

Then run the keytool –importcert command. Assuming your cert file is called myCaCert.cer and is in D:\Corzia\Certificates, and that Java is in D:\Corzia\Java, the command would look something like:

keytool –importcert –trustcacerts –file “D:\Corzia\Certificates\myCaCert.cer” –keystore D:\Corzia\Java\jdk1.8.0_232\jre\lib\security\cacerts –alias domaincert

N.B. You may need to use the syntax ”.\keytool” instead of only ”keytool”.

You can choose any value you like for the –alias parameter but if you want to remove it or just see its details in the future, you will need to refer to it by its alias, so choose an alias that will help you tell it from the others, since the JVM default truststore contains some other 140-150 certificates which you might not care so much about.

Before the command executes the import, it will ask for the truststore password. The default password, which most likely has never been changed, is ”changeit”. (You can include the password in the command by adding –storepass changeit.)

If the command fails, it gives you an error message, and if it succeeds, it asks you if you trust it (answer “yes”) and then says “Certificate was added to keystore”.

If you get the error message that command ?importcert is not valid, you probabaly have copied the command to the console and you have to change all minus (“-“) by manually edit them in the console.

View the cert

You can check that the cert is in the JVM default truststore by the command

keytool -list –keystore D:\Corzia\Java\jdk1.8.0_232\jre\lib\security\cacerts -v -alias domaincert

and you can remove it, if necessary, from JVM default truststore by

keytool -delete –keystore D:\Corzia\Java\jdk1.8.0_232\jre\lib\security\cacerts -alias domaincert

Import certificate to truststore

This step is not strictly necessary but still recommended.

Start Eclipse.

Connect to public CVS volume at repository.corzia.com and check out the project com.corzia.ldap.fixtool . It contains three java class files. If you are on older Comflow versions like 2.14, you may need to change logging to System.out.println() to get rid of compilation errors.

One of the class files, Parameters.java, contains settings that you need to adapt to the current installation of Comflow: the domain name, and the complete names of DC hosts. You also might want to change the TrustStores location – if you have several Comflow instances on a server, they can share the truststore as long as you are sure you will not run them on different JDK’s in the future, but with different JDK’s, it would be better to create subfolders, like D:\Corzia\Truststores\9191, D:\Corzia\Truststores\9292 etc.

The target truststore folder must exist before your run the tool, or it will fail.

Once you have your Parameters.java defined, right-click the file AddSambaDCsToTrustStore.java and choose Debug as (or Run as) Application. Watch the console for messages.

If you are not able to connect to the DC (“Unable to connect to host

When it says “No errors, certificate already trusted” it means the certificate is in the truststore already (or that the truststore contains a root or intermediate certificate that makes the server’s certificate trustworthy), and the tool will not bother any more about it.

When it says “Certificate NOT trusted”, it means the import of intermediate cert done in step 2 somehow has not enabled the establishment of a secure connection.

When all DC hosts have been tested, the tool will copy the JVM default truststore to the Comflow truststore location.

If it was not possible to establish a secure connection to one or more of the DC servers, you should check that the root (or intermediate) certificate really is in the JVM default truststore, and that it is valid for these hosts.

Running the tool in import mode

One possible solution could be to re-run the tool in import mode. Then change in Parameters.java the setting IMPORT_CERTIFICATES_FOUND_ON_DC to true and re-run the tool.

– if a host lacks a certificate, it will say “Could not obtain server certificate chain”.

N.B.: depending on circumstances at your customer, such as whether they already use SSL with other applications, there may or may not exist certificates in the DC servers. If a certificate is missing in one or many of the DC servers, you will need to create them or ask the IT responsible to create them for you. If you don’t want to use Corzia’s tool, you can import certificates manually using the keytool command.

You will notice while stepping through the tool that the Subject information of the certificate cannot be blank – it should contain the domain name, otherwise it will not be installed. Ideally, each certificate should state Subject and SANs according to the following model:

Subject:

DN=dc2.mydomain.com

Subject alternative names:

DNS Name: dc2
DNS Name: mydomain.com

Updating sitedef.xml

In the sitedef.xml file, change the property provider.url as follows:

1. Switch “ldap” for “ldaps”
2. If the port number 389 is stated, switch it for the SSL port 636, or just remove completely, including the colon preceding it.
3. Please note that the provider.url property probably appears at several occurrences in the sitedef.xml, for example under Authentication, UserManagement, GroupManagement and, not the least: PrinterHandlers, and it needs to be changed in all places.
4. Copy the provider.url property to provider.url.ssl at all occurrences of provider.url. (This is needed on 2.20 and higher versions of Comflow, if users are allowed to change their AD passwords via Comflow, otherwise not needed.)
5. In JVM properties, you need to include the trust store location as below:

<JVMProperties>
 	<Property name="javax.net.ssl.trustStore" value="D:/Corzia/Truststores/jssecacerts"/>
    <Property name="javax.net.ssl.trustStorePassword" value="changeit"/>
</JVMProperties>

(the default trust store password is changeit – and that is what the tool will use unless you make efforts to actually change it!) If you leave out the above-mentioned JVM properties, it means that the default JVM trust store will be used. In that case, you would probably be best off deleting the trust store file D:/Corzia/Truststores/jssecacerts if the tool has created it, in order not to confuse your peers.

Change Comflow launch configuration

In the Tomcat server launch configuration, add the argument

-Dcom.sun.jndi.ldap.object.disableEndpointIdentification=true

If you don’t add this argument, LDAPS will not work (on java 1.8.0_181 or higher) due to

“javax.net.ssl.SSLHandshakeException: java.security.cert.CertificateException: No subject alternative DNS name matching xxx found”.

In theory, you don’t need to add this argument if your top certificate lists the domain name as a Subject Alternative Name (SAN). We have not seen that working yet, though!

Restart Comflow

When you start Comflow, the connection to AD is in the startup Sequence, so if it starts without errors, everything is OK. Otherwise you will get error messages in the startup log that can guide you for what is wrong.

Questions that you need to ask customer IT responsible

• Are they aware of the Microsoft article?
• What servers do they have with Domain Controller role in the domain we use when querying the their Active Directory?
• Are there already SSL certificates installed on the DC servers?
• Will firewall rules allow socket connection on port 636 from Comflow servers to DC hosts? (If they do not currently use SSL with the DCs, ports might not be open.)
• How much of the job would they like to do themselves and how much should you do? For example, they might want you to fix the first Comflow instance and verify it works, then do to rest on their own.

In coming months and years

You should pay attention to the Valid To date of certificates that your rely on. Once that date has passed, Comflow will not be able to connect securely to the Active Directory, which (worst case) means no-one can log on to Comflow.

The root or intermediate certificate usually has quite an extensive validity period (like 20 years). If you rely on server-specific certificates (but ideally you do not) they may have a shorter validity time, like 12 or 24 months, which means you will need to monitor these dates and install new certificates before expiry.

If you have a certificate available in exported form (.cer file), and you are sure that the certificate of that file is the one you’re running on, you can just click it to open its details. Otherwise you can view it using the keytool -list command, like described above, just pay attention to using the right keystore argument. If you’re looking in the JVM default truststore, the argument is

–keystore D:\Corzia\Java\jdk1.8.0_232\jre\lib\security\cacerts

And if you’re examining the Comflow truststore, it would be something like:

-keystore D:\Corzia\Truststores\jssecacerts

Remember: it is the sitedef.xml property javax.net.ssl.keystore that points out the keystore that Comflow will use. If the property is not present in the sitedef.xml, the JVM default truststore is used.

Please note that you will need to update your truststore whenever certificates are renewed or whenever you change to a newer JDK, and whenever a new DC server is added to the domain (if you rely on server-specific certificates).