4.3.2 HTTPS & Networking

Watch the videos above to understand the OpenCRVS network and how TLS is configured in OpenCRVS servers

Domain A records

Using your domain management system, A records will need to be created for all the services which are publicly exposed.

This also enables the Traefik SSL cert to be successfully generated by LetsEncrypt when using HTTPS or DNS challenge.

Either use a wildcard or create individual A records for your chosen domain name, with a TTL of 1 hour that forwards the URL to your manager server node's external IP address.

The easiest approach is to use a wildcard. For example: *.<your_domain> although this is not as secure in production.

Option 1: Wildcard required A Records:

2 A Records are required for this option

<your_domain>

*.<your_domain>

Option 2: Individual A Records:

16 A Records are required for this option

<your_domain>

auth.<your_domain>

config.<your_domain>

countryconfig.<your_domain>

documents.<your_domain>

metabase.<your_domain>

minio.<your_domain>

minio-console.<your_domain>

ui-kit.<your_domain>

gateway.<your_domain>

kibana.<your_domain>

login.<your_domain>

openhim-api.<your_domain>

openhim.<your_domain>

register.<your_domain>

webhooks.<your_domain>

If using our Wireguard VPN:

vpn.<your_domain>

Our Wireguard VPN is not designed for use at scale. The Wireguard VPN Admin interface hosted at vpn.<your-domain> uses wg-easy. OpenCRVS accepts no responsibility for the penetration testing or security of the Wireguard VPN or WG Easy. Use at your own risk.

If you are enabling external interoperability access directly to OpenHIM, you will also need this A record for it: api.<your_domain> but be careful to only add this domain if you understand the whitelisting Traefik steps required. Refer to the docker-compose files to see comments regarding how to whitelist OpenHIM.

LetsEncrypt HTTPS Challenge

Traefik config is required to be edited in your docker-compose files for your environment listed here, in order to configure the LetsEncrypt HTTPS challenge mechanism for SSL cert generation in development or qa environments:

- --certificatesresolvers.certResolver.acme.email=<your email address>
- --certificatesresolvers.certResolver.acme.storage=acme.json
- --certificatesresolvers.certResolver.acme.caserver=https://acme-v02.api.letsencrypt.org/directory
- --certificatesresolvers.certResolver.acme.httpchallenge.entrypoint=web
- --certificatesresolvers.certResolver.acme.httpchallenge=true

LetsEncrypt DNS Challenge

Traefik config is required to be edited in your docker-compose files for your environment in order to configure the LetsEncrypt DNS challenge mechanism for SSL cert generation in production or staging environments. LetsEncrypt supports APIs for the following providers:

Traefik Let's Encrypt Documentation - Traefik

In this example, Google Domains is the configured provider. The environment variable GOOGLE_DOMAINS_ACCESS_TOKEN is manually added to the Github environment as a secret.

environment:
 - GOOGLE_DOMAINS_ACCESS_TOKEN=${GOOGLE_DOMAINS_ACCESS_TOKEN}
command:
 - --certificatesresolvers.certResolver.acme.dnschallenge=true
 - --certificatesresolvers.certResolver.acme.dnschallenge.provider=googledomains
 - --certificatesresolvers.certResolver.acme.email=<your email address>
 - --certificatesresolvers.certResolver.acme.storage=acme.json

Pre-existing TLS certificates

Traefik config is required to be edited in your docker-compose files for your environment in order to use pre-existing TLS certificates.

1. Once your environment is provisioned, manually add your certificate files into the /data/traefik/certs directory on your server so that they are picked up.

2. Create a file named certs.yaml in the infrastructure/traefik folder like this:

tls:
  stores:
    default:
      defaultCertificate:
        certFile: /etc/certs/<your combined leaf, intermediate & root, certfile>.crt
        keyFile: /etc/certs/<your cert private key file>.key
  certificates:
    - certFile: /etc/certs/<your combined leaf, intermediate & root, certfile>.crt
      keyFile: /etc/certs/<your cert private key file>.key
      stores:
        - default

3. Use the Traefik config below to access the cert.yaml file, remove any lines that start with "--certificatesresolvers.certResolver.acme" :

volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /data/traefik/certs:/certs
      - /opt/opencrvs/infrastructure/traefik/certs.yaml:/etc/traefik/certs.yaml
    command:
      - --providers.file.directory=/etc/traefik
      - --providers.file.watch=true

4. If the certificate is different for each environment, you will have to edit the "Provision" Github Actions to write the contents of the .crt & .key files in the /data/traefik/certs directory on your server from new Github environment secrets you will manually have to create. In the file infrastructure/server-setup/tasks/traefik.yml, add these lines at the end of the file:

- name: Create crt file with variable content
  copy:
    dest: "/data/traefik/certs/cert.crt"
    content: |
      {{ssl_crt}}
    owner: root
    group: application
    mode: 0644
  when: ssl_crt is defined and ssl_crt | length > 0

- name: Create key file with variable content
  copy:
    dest: "/data/traefik/certs/cert.key"
    content: |
      {{ssl_key}}
    owner: root
    group: application
    mode: 0600
  when: ssl_key is defined and ssl_key | length > 0

5. Add these 2 new Github environment secrets SSL_CRT & SSL_KEY to the "Set variables for ansible in production environments" step in the file .github/workflows/provision.yml

ssl_crt: ${{ secrets.SSL_CRT }}
ssl_key: ${{ secrets.SSL_KEY }}