Cloud SSL Certs - openmrs/openmrs-contrib-itsmresources GitHub Wiki

We are using LetsEncrypt for all services. Ansible is setup to run LetsEncrypt in two modes either webroot (the default) or acmedns (using our ACME DNS server).

To configure a server to use LetsEncrypt, it must be in the [tls] group of the corresponding Ansible inventory (prod-tier1, etc.). Which authentication mode is used depends on the letsencrypt_authenticator Ansible variable for a given host.

By default, this is webroot, which uses standard HTTP-01 challenges. The setup for these should work without issue, assuming the server's DNS entries are correctly setup.

To use DNS-01 challenges (necessary, e.g., for servers protected by CloudFlare or where HTTP-01 is otherwise not an option), we provide an ACME DNS server. To use this change letsencrypt_authenticator to acmedns and acme_dns_server_url to "http://acme-internal.openmrs.org:8080" which will use DNS-01 to obtain a certificate. Note that the ACME DNS setup will require two Ansible runs to be setup successfully.

First, a standard run to setup the server and authenticate it with the ACME DNS server. In this run, ansible-playbook must be run with -e acme_dns_register=true. In the output there will be a step called "Show the CNAME targets to paste into Terraform". The output will look something like this:

"# _acme-challenge CNAME targets for bonga.openmrs.org (bonga.openmrs.org, modules-refapp.openmrs.org).",
"# The fulldomain already ends in the acme-dns zone - paste verbatim into the Terraform",
"# repo (acme_challenge_cnames for openmrs.org names, manual-dns per-zone otherwise).",
"_acme-challenge.bonga.openmrs.org CNAME d754e519-a38f-408e-adf7-e7517b9f7e9b.acme.openmrs.org",
"_acme-challenge.modules-refapp.openmrs.org CNAME 4ddc5d84-b289-4c89-a15c-21b47fa77ad8.acme.openmrs.org"

The lines of interest are the ones like this _acme-challenge.<host> CNAME <UUID>.acme.openmrs.org for each we need the <host> and <UUID>. In the Terraform variables for a stack add the "acme_challenge_cnames" variable like this:

variable "acme_challenge_cnames" {
  default = {
    "bonga"          = "d754e519-a38f-408e-adf7-e7517b9f7e9b.acme.openmrs.org"
    "modules-refapp" = "4ddc5d84-b289-4c89-a15c-21b47fa77ad8.acme.openmrs.org"
  }
}

Where the left is the <host> short name and the right is the <UUID>. Run Terraform on the stack to generate the DNS records. This should be a one-time thing, but the same process needs to be done for any new CNAMES.

After being added to Terraform, you will need to run a ./build.rb plan <host> and ./build.rb apply <host> to generate the necessary CNAME records. Re-run Ansible, this time without any special arguments and the certificates will be generated.

In either mode, renewals should be automatic via a cron scheduled tasks that ensures our certs are up-to-date. Note, however, that if domains are added or moved to a server, it is necessary to go through the same process as the initial setup.