HTTPS for Koha's OPAC and staff interface with Let's Encrypt

Give both sites a certificate — patrons log in to the OPAC to see their own borrowing record, and staff log in to everything. On an existing instance that is certbot --apache naming both hostnames, followed by setting OPACBaseURL and staffClientBaseURL to their https:// addresses. Skip that last step and Koha keeps putting http:// links in its notices.

A Koha instance is two websites. Get both names from the site file rather than from memory:

$ grep -i ServerName /etc/apache2/sites-available/library.conf    ServerName library.example.org   ServerName library-intra.example.org

If the staff interface is on a port rather than its own hostname — the default :8080 arrangement — give it a hostname first. A certificate is issued for a name, not for a port, so this is the step that has to happen before any of the rest: see Koha, Apache and port 8080.

$ sudo apt -y install certbot python3-certbot-apache$ sudo a2enmod ssl$ sudo certbot --apache \    -d library.example.org -d library-intra.example.org

Certbot asks for an email address, obtains the certificate and rewrites the virtual hosts to serve it. Answer yes when it offers to redirect HTTP to HTTPS — an OPAC that answers on both is a login page reachable in plain text.

$ sudo apache2ctl configtest Syntax OK$ sudo systemctl reload apache2

This is the step that gets missed, and it is invisible until a patron complains. Koha builds absolute URLs for password resets, hold notices and staff links from two system preferences, and they still say http://.

1. 1In the staff interface, go to Administration → Global system preferences.
2. 2Set OPACBaseURL to https://library.example.org — no trailing slash.
3. 3Set staffClientBaseURL to https://library-intra.example.org.
4. 4Save, then send yourself a password reset from the OPAC and check the link in the mail is https.

Certificates last ninety days. Certbot installs a timer to renew them, and the only way to know it works is to make it try:

$ sudo certbot renew --dry-run Congratulations, all simulated renewals succeeded

Do this on the day you issue, not on the day it expires. A renewal that has never been tested is the most reliable way to have a library catalog go down on a Saturday with a browser warning nobody on site can clear.

If the instance does not exist yet, koha-create can set it up as HTTPS-only from the start:

$ sudo a2enmod ssl$ sudo koha-create --create-db --letsencrypt library

It refuses to run without mod_ssl and installs the Let's Encrypt client itself if it is missing. The DNS records still have to exist first — the same requirement, just earlier in the day.

It is tempting to certificate the staff interface and leave the public catalog alone, on the grounds that a catalog is public information. It is not the catalog that needs protecting — it is the patron. A patron signs in to see what they have borrowed, what they owe and what they have reserved, and over plain HTTP that password and that reading history cross every network between them and the library in the clear. On campus wifi, that is a real exposure.

There is a practical layer too. Browsers mark plain-HTTP login forms as "Not secure" in the address bar, which for a library is a public statement about how it handles member data. Several browser features a modern OPAC theme may use are restricted to secure contexts. And an institution's own security review will eventually reach the catalog, at which point this becomes urgent rather than planned.

The cost is one command and a timer. There is no version of this argument where it is not worth doing.

One last thing to check afterwards, because it fails quietly: if Plack is enabled, restart it so nothing is serving a cached configuration — and if the site starts returning 502 rather than a certificate warning, that is Plack, not TLS.