Installation of TLS Certificates
- Isaac Sears
Why Use TLS?
Any OpenMRS implementation that is accessible from the public internet should implement TLS. Without the encryption that TLS provides, the OpenMRS system's incoming and outgoing traffic is easily readable by anyone with access to any part of the network infrastructure between the server and its clients. This traffic may include a variety of sensitive information, including passwords and patients' health information.
Options for Implementing TLS
Unfortunately, OpenMRS does not provide TLS support out-of-the box. It's up to implementers to build and maintain an encryption layer between OpenMRS and the internet. In the past, this used to involve regular fees to a certificate authority as well as burdensome manual configurations and maintenance. Now, however, that process has been automated and made completely free by Letsencrypt, a nonprofit dedicated to building a more secure internet. There are several ways to implement letsencrypt free certificates, but they all require that a globally routable domain name has been configured on the server first. It is impossible to register a letsencrypt certificate to an IP address. It's also necessary that ports 80 and 443 are unblocked.
Letsencrypt on the Linuxserver.io Docker Image
The easiest way to take advantage of Letsencrypt's free service and automation tooling is to use linuxserver's nginx reverse proxy docker image for installing TLS certificates: https://hub.docker.com/r/linuxserver/swag. Many configuration options are documented on the project's dockerhub page, but for OpenMRS implementers, the main concern will be creating a reverse-proxy configuration within the docker image that points to an OpenMRS installation that's either running on the same machine or elsewhere on the local network. For example, if the OpenMRS instance and the docker container are running on the same server, the reverse proxy configuration may look something like this:
# main server block
server {
listen 443 ssl default_server;
root /config/www;
index index.html index.htm index.php;
server_name _;
# enable subfolder method reverse proxy confs
include /config/nginx/proxy-confs/*.subfolder.conf;
# all ssl related config moved to ssl.conf
include /config/nginx/ssl.conf;
client_max_body_size 0;
location / {
return 301 https://$http_host/openmrs$request_uri;
}
location /openmrs {
include /config/nginx/proxy.conf;
proxy_pass http://localhost:8080/openmrs;
}
}
# Redirect HTTP requests to HTTPS
server {
listen 80;
return 301 https://$host/openmrs$request_uri;
}
The nginx configuration can then be added to the docker container as a volume at the following path: /config/nginx/site-confs/default. The goal is for the letsencrypt docker container to intercept all traffic between the internet and the OpenMRS instance. It will encrypt outgoing traffic and decrypt incoming traffic transparently, so that no modifications to the OpenMRS server itself are needed.
Using Letsencrypt's Certbot Tool and Manually Configuring Tomcat
If, for whatever reason, docker is unavailable, the letsencrypt certificate can be manually configured with the Electronic Frontier Foundation's "certbot" tool: . Certbot automates the creation and maintenance of the TLS certificate itself, but (as of Dec. 2020) does not automate the installation of the certificate into tomcat. Once the letsencrypt certificate has been obtained by certbot, documentation on how to use it with tomcat can be found here: https://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html
Verifying TLS Configuration
It's important to make sure that everything has been configured correctly after setting up TLS certificates. The strength of the TLS configuration can be checked by using a free ssl-checker service. For example: https://www.ssllabs.com/ssltest/