Let’s Encrypt on Standalone EZproxy Server

by Mike Robinson
Professor & Head of Systems
Consortium Library
University of Alaska Anchorage

This recipe is part of a series about my experiences moving our library servers and services to Let’s Encrypt for TSL/HTTPS certificates.  I will be describing how to install certificates from Let’s Encrypt on a standalone EZproxy server that provides authentication and access to online resources.

Note: if your library uses the hosted EZproxy service, certificate management is provided by OCLC.

ezproxy

letsencryptEZproxy can be configured to use SSL  to provide access  to content from secure URLs that begin with https://.  If your EZproxy configuration uses proxy by hostname you will need a subdomain certificate for each secure URL that can be accessed.  The easiest way to handle this is to install certificates which support wildcard for multiple subdomains. While Let’s Encrypt does not support wildcard certificates at this time, it does support issuing up to 100 subdomains on a single certificate.  This means that Let’s Encrypt is a good solution for standalone Ezproxy servers that access less than 100 secure URLs.    Let’s Encrypt began supporting wildcard certificates in 2018. Yay!   At some point I will work on an updated post to show how this is done.

For our library, we will continue to use purchased certificates that support wildcard for our main EZproxy service and use Let’s Encrypt to install certificates on a second EZproxy service for the Alaska Medical Library, a unit inside the main library, that provides access to content from a handful of providers.

Here are the overall steps on a standalone Linux EZproxy server that you have shell access to with root or appropriate sudo privileges.

  • Get the client application.
  • Use the client application to generate certificates.
  • Configure EZproxy to use the certificates.
  • Set up a routine for renewal of certificates.

Get the Client Application

Let’s Encrypt recommends using a client application called certbot to obtain certificates.   For a number of distros (Ubuntu, ArchLinux, Gentoo, CentOS RHEL 7), the client is available via the common package manager for that distro and can be installed with one command.  Our server is still on CentOS 6, so we have a few extra steps.

  • Enable the EPEL (Extra Packages for Enterprise Linux) repository.  This will make additional dependencies available to the certbot client.
$ sudo yum install epel-release
  • Create a directory for where the certbot client will live, this can be anywhere but I selected /usr/local/ and named the directory letsencrypt.
$ sudo mkdir /usr/local/letsencrypt
$ cd /usr/local/letsencrypt
  • Download the certbot client and make it executable.
$ sudo wget https://dl.eff.org/certbot-auto
$ sudo chmod a+x certbot-auto

 

Generate Certificates

The certbot client is actually a script that performs a number of tasks, see this previous recipe for more details.

  • Stop EZproxy service so that the certbot client can use port 80 to prove to Let’s Encrypt that you control this domain.
$ sudo service ezproxy stop

Note: if this command does not work,  use the ./ezproxy -si command to install the start up scripts.

  • Run the certbot client to install certificates in manual mode for two domain names ( one the EZproxy server, the other for a secure content subdomain).  The –standalone switch tells certbot to bind temporarily to port 443 and install the certificates in the /etc/letsencrypt/ directory.  If we had additional secure content subdomains, we could add them to the line with additional -d switches.
$ cd /usr/local/letsencrypt
$ sudo ./certbot-auto --standalone certonly -d amlproxy.consortiumlibrary.org -d naturalmedicines.therapeuticresearch.com.amlproxy.consortiumlibrary.org
  • Answer the questions the client will ask and wait for it to finish.
email address?
I put in my email address.
  • Start the  EZproxy service again.
$ sudo service ezproxy start

Configure EZproxy to Use the Certificates

  • Enable port 443 for SSL.
Edit config.txt and add the lines:

    LoginPortSSL 443


Restart the EZproxy service $ sudo service ezproxy restart
  • Import certificates into EZproxy.
Login to the EZproxy admin page.

From the EZproxy administration page, under the Miscellaneous heading, 
click on Manage SSL (https) certificates and select Import certificates

Copy & paste the contents of the file
/etc/letsencrypt/live/amlproxy.consortiumlibrary.org/cert.pem 
into the Certificate text box

Copy & paste the contents of the file
/etc/letsencrypt/live/amlproxy.consortiumlibrary.org/privkey.pem 
into the Key text box

Click the Import button

On the Certificate Details page

Copy & paste the contents of the file 
/etc/letsencrypt/live/amlproxy.consortiumlibrary.org/chain.pem
into the Certificate Authority Chain (Intermediate Certificates) text box

Click Save Certificate Authority Chain button

Find the line of text that states 
To make this the active certificate for this server...
Type ACTIVATE in the box and click activate button

Import Existing SSL CertificateSSL Server Test_ amlproxy.consortiumlibrary

  • Test the certificates to make sure they are installed correctly for each domain.
https://www.ssllabs.com/ssltest/analyze.html?d=amlproxy.consortiumlibrary.org&latest
https://www.ssllabs.com/ssltest/analyze.html?d=naturalmedicines.therapeuticresearch.com.amlproxy.consortiumlibrary.org

Note: The grade is a C rating because the version of EZproxy  we are running (5.7.44) does not support TLS 1.2 .  We will probably need to upgrade at some point.

  • Enable secure logins and add directive for secure URL.
Add the following directive to the config.txt file to enable secure login:

     Option ForceHTTPSLogin

Add directive in the config.txt for the secure resources, for example:

     H https://naturalmedicines.therapeuticresearch.com

Restart EZproxy service

     $ sudo service ezproxy restart

That’s it, our EZproxy server is now using free HTTPS certificates issued by Let’s Encrypt for secure logins.

Certificate Renewal

Let’s Encrypt will only issue certificates for 90 days for some good reasons but this comes as quite a shock to administrators who are used to  1-3 year renewal periods.  The idea is that renewal will be automatic so that you will only need to manually deal with certificates when first issuing them or when making changes to domain names.

  • Stop the EZproxy service and perform a dry-run to renew certificates without making a real request.  You should get a message that the test succeeded.
$ sudo service ezproxy stop
$ cd /usr/local/letsencrypt
$ sudo ./certbot-auto renew --dry-run
$ sudo service ezproxy start
  • Add a cron or systemd job to run the commands automatically.  The certificates will only renew if they are going to expire in 30 days or less.  Let’s Encrypt recommends running the renewal command twice a day.  I’m old school so decided to use crontab.

$ sudo crontab -e

Here are example entries to stop EZproxy once a day at 4:20am, run renewal  at 4:25am, and start EZproxy at 4:30am.

20 04 * * * /etc/init.d/ezproxy stop

25 04 * * * /usr/local/letsencrypt/./certbot-auto renew –quiet

30 04 * * * /etc/init.d/ezproxy start

  • Import the certificates into EZproxy and activate them using the steps described earlier in this recipe.  I am not aware of a way to automate this part, so for now I will just set a calendar reminder and do this every 90 days.  NOTE:  a reader shared that they deleted the active files (00000002.key for example) in the Ezproxy directory and replaced them with symbolic links to the certificate files in /etc/letsencrypt/live.   You may need to restart EZproxy service when the certificates change.

Next Recipe

The next recipe in the series will be on installing Let’s Encrypt certificates on a library OPAC (SirsiDynix Enterprise) Tomcat Server on CentOS 5.