Set up secure LDAP over SSL (LDAPS)

The Zylinc Authentication Server runs on Tomcat, which is a Java-based web server. Tomcat in turn runs on Java Virtual Machine (JVM), so when you're going to add a CA certificate to the Authentication Server, you're technically going to add it to the JVM keystore (the place where JVM stores certificates).

1. On the computer that runs your Zylinc Authentication Server, open a command prompt as administrator, and go to C:\Program Files\Java\[version]\bin

   Example: C:\Program Files\Java\jre1.8.0_171\bin

2. Run keytool.exe

3. Run keytool -list -v -keystore "C:\Program Files\Java\jre1.8.0_171\lib\security\cacerts" | findstr "Alias" (if you use another Java version, make sure to use your version number in the string in this and the following steps).

   When you get asked for a default password, just press ENTER.

4. You can now view a list of all CA certificates that are available in your JVM keystore.

   • If the required CA certificate is already there, you can go to Set up LDAPS in Zylinc Administration Portal.
   • If the required CA certificate isn't there, for example because it's a non-public domain certificate, do the following.

Export CA certificate

1. On the computer where you store the required CA certificate, open Certificate Manager (type crtmgr.msc in Windows' search field, and press ENTER).

2. In Certificate Manager, expand Trusted Root Certification Authorities > Certificates.

3. Right-click the domain CA certificate, and select All Tasks > Export ...

4. Click Next, and select DER encoded binary X.509 (.CER). Then click Next.

5. Select required location and name for the certificate (.cer) file export.

   Example: C:\Users\administrator\Desktop\Certs\dmz-ad-ca_20211014.cer

6. Click Next, Finish, and OK.

Import CA Certificate to JVM keystore

1. On the computer that runs your Zylinc Authentication Server, open a command prompt as administrator, and run the following:

   In the following we assume that certificate export from the previous step is placed in C:\Users\administrator\Desktop\Certs\, and that it's called dmz-ad-ca_20211014.cer. You should change the location and name so that it reflects your actual export.

   keytool -import -trustcacerts -file "C:\Users\administrator\Desktop\Certs\dmz-ad-ca_20211014.cer" -alias "dmz-ca" -keystore "C:\Program Files\Java\jre1.8.0_171\lib\security\cacerts" -storepass changeit

   You've now imported the CA certificate, but its password is changeit, and you should change that to a password of your choice:

2. In the command prompt, run the following:

   keytool -storepasswd -keystore "C:\Program Files\Java\jdk1.8.0_171\jre\lib\security\cacerts"

   When you're asked for the keystore password, enter changeit

   Then enter and confirm your new keystore password.

3. Restart Tomcat to make the changes take effect.

When you have your certificate in place in the Authentication Server's JVM keystore, you can enable secure LDAP authentication (LDAPS) in the ZylincAdministration Portal:

1. In the Zylinc Administration Portal menu, select SYSTEM > Interface Configuration, and scroll down to the Authentication section.

2. Select Use Zylinc AuthServer, and then specify the Authentication Server URL.

   Example: http://10.10.10.51:8580/Authentication

3. In LDAP Url, specify the URL of your LDAP server/Domain Controller.

   Because you want to use LDAPS, you should specify ldaps (not just ldap) as the protocol at the beginning of the URL. You should also include the port number 636 in the URL. With port 636, the systems will negotiate SSL before they exchange any LDAP traffic (if you don't include a port number, the Zylinc solution will automatically use the regular LDAP port 389, and we want to avoid that).

   Examples:
   ldaps://ldaps.example.org:636/
   ldaps://ldaps.example.org:636/ou=People,dc=org (where the URL includes directories for limiting the user search to specific LDAP branches)

4. If users want to log in to a Zylinc portal, such as the Administration Portal or the Statistics Portal, they may not be able to use their user names to log in directly with LDAPS. In such scenarios, you can use an LDAP System User.

   If you define an LDAP system user, the Zylinc solution will use the LDAP system user information to create an LDAPS connection and then retrieve the LDAP-defined user name of the user who attempts to login.

   If you don't define an LDAP system user, the Zylinc solution will only use the user-supplied login credentials to authorize the user.

   To define an LDAP system user, specify the User Principal Name or SamAccountName of the required system user.

   Examples: admin@domain.local (user principal name) domain\admin-svc (samaccountname)

   Then specify that system user's Password.

5. By default, authentication will be in plain text. However, you can also use authentication with MD5 (a one-way cryptographic hashing algorithm that works as a checksum by accepting input of any length and returning a fixed-length digest value that's then used to authenticate the original input).

   To use MD5, select Enable MD5 Authentication.

6. In Authenticate using, select which value to use when authenticating users:

   • DN (Distinguished Name)
   • Email
   • SamAccountName
7. Click Save.