Adding Let's Encrypt TLS Certificate to SirsiDynix Horizon Web Serivces Tomcat Server

Following up on my post on How to setup Horizon Web Services I am now going to go over how to secure your connection as much as possible using a Let's Encrypt TLS/SSL Certificate.  Horizon Web Services is an application created by SirsiDynix that uses apache tomcat that allows access to a library ILS via API along with some other things (bookmine, bluecloud connection, etc).

Horizon Web Services can be run on the following Operating Systems in both 32 and 64 bit:

• Microsoft Windows Server 2008 r2 or 2012 r2
• Linux (Red Hat Enterprise 6 or 7; SUSE Enterprise 10 or 11)
• Sun Solaris 10 or 11 (both Intel and Sparc)

This post will be how to secure Horizon Web Services on Windows Server 2012, almost everything will be done by Administrative CMD Prompt.  Sirsidynix recommends working out of your Web Services Directory and this is the order we are going to go though to setup our TLS/SSL certificate.

1. Setup an environmental variable for the pathing to the Java bin directory
2. Create a Certificate Signing Request
3. Get an SSL Certificate from ZeroSSL.com
4. Add the Certificate verification to your DNS
5. Schedule a task every 3 months to update the TLS certificate or find a way to automate it.

Setting up the Environmental Variable in Windows

Everything we need to setup/add the TLS/SSL certificate in apache tomcat is in the Java Directory.  Right click on the computer and get the properties -> Go to the Advanced Tab -> press on the Environment Variables button.

System Properties Dialog Box

Setting Environment Variables

When you go to run the Tomcat TLS/SSL commands you will need to put "$JAVAVAR" in quotes in your command prompt so windows know where to run the commands we are going to run.

Create a CSR (Certificate Signing Request)

Tomcat uses a java keystore for storing all the certificate information.  There are a couple of things you will want to think about and document ahead of time before you start setting up your CSR.  

1. One is the Alias for the keystore
2. Is the name of your keystore file
3. The password for your keystore file

The keystore alias and file name can be literally anything.  See the example below

"$JAVAVAR"\keytool -genkey -alias webservices -keyalg RSA -sigalg SHA256withRSA -keystore supersecrets -keysize 2048

The break down of the above statement is the keystore data is in an "container" called webservices.  This "container/alias" is in a file called supersecrets which is in the webservices directory.  This is protected by a password which you specify when you create the keystore file.  By default the tomcat keystore password is changeme.

NOTE:

the keystore has a .keystore extension associated with it though I found you don't need to put the .keystore behind the keystore file name, but if you want to use something like Portecle to view, edit and maintain your keystore you will need to change your open view to all files.

Make sure your in your Web Services Directory (Typically D:\SirsiDynix\WebServices)

Command to create the keytool for the TLS/SSL Certificate

After you run the command you will see something like this in your WebServices Directory

Files in the WebServices Directory

With your CSR file now created we can go to zerossl.com and start creating our TLS/SSL Certificate

Select the Free SSL Certificate Wizard

I didn't have an IP setup where I could use port 443 to verify the TLS certificate so I used DNS verification.  Paste your CSR in the right hand field and leave the left box blank so it auto generates your Let's Encrypt Key.

When verifying your TLS/SSL Certificate using DNS verification you will need to make an A record and setup a txt record with something like the following.

ACME-CHALLENGE for DNS TXT RECORD

Once you have been verified you will be taken to the confirmation page.

Your Certificate is Ready

Here you download the certs and then you can added it to the keystore.  Your domain and intermediate certs are in the domain-crt.txt file with the domain cert being the first part and the intermediate certs are the second part

Files from zerossl.com

The domain-crt opened in a text editor

Import the Intermediate Cert

Import Domain Cert

Now you need to open the server.xml file typically located in webservices -> conf folder; and edit the keystoreFile, keystorePass, and server.  Once this is done save the file and either reboot or restart the Tomcat Server. 


If you want to have a full look at your keystore you can use Portecle and can dig deep and make changes to the certificates

Portecle GUI

Auto-Renew the Certificate

When I figure out a good way to automate the updating of the TLS Certificate I will definitely update this post in the meantime the best thing I can come up with are a calendar alert and to schedule it into the maintenance cycle, which isn't the worst thing in the world it makes you have a look at the server and make sure it is working and up to date.  You can download the auto-renew portable app for renewing here https://github.com/do-know/Crypt-LE/releases

Update!  Horizon Web Services Released April 3rd!
https://support.sirsidynix.com/alert/81823