Why Use TLS?

Any OpenMRS implementation that contains confidential or protected health information should implement HTTPS/TLS, this means ALL production systems.
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.

HTTPS (HyperText Transfer Protocol Secure) is a way to keep your information safe when you visit websites. It works by encrypting the data sent between your browser and the website, so that no one else—like hackers or snoopers on public Wi-Fi—can read it. You’ll know a site uses HTTPS when you see a padlock icon in the address bar. This is especially important for sites where you enter sensitive information like passwords, health details, or payment info. Without HTTPS, your data travels in plain text and can be intercepted easily. With it, everything is scrambled into unreadable code until it reaches the right place.

Options for Implementing TLS

OpenMRS is currently working on TLS support out-of-the box to automate the setup. However, right now, implementers need to build and maintain an encryption layer between OpenMRS and the internet by providing a certificate.

Options to generate a valid certificate used to involve only paid services, but there are now free options, the most widely used of which is 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, more on that below. It's also necessary that ports 80 and 443 are unblocked.

How to decide your approach

Setting up your site security certificate depends on whether you have internet connection or not. To determine whether you need an online or offline-based approach: If your server can not resolve from a DNS name like emr.cascadia.cs.gov , but is instead a string of numbers (like 192.168.x.x or 10.x.x.x), you MUST use the self signed certificate option.

Self-Signed Certificate approach

A self-signed certificate is created and signed by the same entity that owns the server—essentially saying “trust me because I say so.” It provides encryption but lacks third-party validation, so browsers and clients won’t automatically trust it. In contrast, a certificate from a vendor like Let’s Encrypt is signed by a publicly trusted Certificate Authority (CA), which verifies your identity and domain ownership. These vendor-issued certificates are recognized by all major browsers, making them ideal for public-facing websites and APIs. Both types use the same encryption standards, but only CA-signed certificates offer seamless trust and compatibility.

Let’s Encrypt approach

Let’s Encrypt (or other commercial vendors) requires your server to have a publicly resolvable domain name—meaning your IP address must be part of a DNS record that points to your server. If your server is on a private IP (like 192.168.x.x or 10.x.x.x) and not accessible from the internet, Let’s Encrypt cannot validate it and will refuse to issue a certificate. In this case, you’ll need to use a self-signed certificate. While this works for internal tools and local networks, some browsers may show warnings or block access unless users manually accept the certificate. That might involve clicking through security prompts or importing the certificate into their trusted store. Even with these extra steps, using a self-signed certificate is far better than transmitting sensitive data—like passwords or health records—without encryption.

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/

HTTPS setup: Installation of TLS Certificates for secure communication