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 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
- 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. Unfortunately for the EZproxy server, we have one step that I have not been able to automate.
- 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.