Skip to main content

MongoDB TLS Connection Configuration

This guide describes how to configure HAP to trust the CA certificate for the MongoDB server and establish an encrypted TLS connection.

HAP currently supports one-way TLS authentication for MongoDB. mTLS (mutual TLS authentication) is not currently supported.

Before configuring the connection, ensure that TLS is enabled on MongoDB.

Prepare Certificates​

Prepare the CA certificate that issued the MongoDB server certificate in PEM format:

FileDescription
custom-ca.crtCA certificate used to verify the MongoDB server certificate

Multiple CA certificates can be placed sequentially in the same custom-ca.crt file.

  • The file must contain only public CA certificates, not private keys. A file containing a private key will be rejected in its entirety.
  • The MongoDB connection address must match a domain name or IP address in the server certificate.

Mount Certificates​

HAP supports importing custom CA certificates starting with v7.4.0.

Mount the CA certificate inside the container. It will be imported automatically when the container starts.

  1. On the HAP server, place the CA certificate in /data/mingdao/script/volume/cafile/custom-ca.crt.

  2. Check the volumes configuration of the app service in /data/mingdao/script/docker-compose.yaml and mount the certificate in the container. For example:

    services:
    app:
    volumes:
    - ./volume/cafile/custom-ca.crt:/Housekeeper/cafile/custom-ca.crt:ro

If the corresponding mount already exists, do not add it again.

Configure the Connection​

Modify the configuration file for your deployment mode:

Configure the app service in /data/mingdao/script/docker-compose.yaml.

Add tls=true to ENV_MONGODB_OPTIONS, retain any existing parameters, and update the MongoDB addresses, ports, and account details as needed:

ENV_MONGODB_URI: 'mongodb://hap:YOUR_PASSWORD@192.0.2.10:27017,192.0.2.11:27017,192.0.2.12:27017'
ENV_MONGODB_OPTIONS: '?tls=true'

ENV_MONGODB_OPTIONS starts with ?; separate multiple parameters with &.

After configuring, run the following command from the installation manager directory in standalone mode to recreate the app container and apply the Compose configuration:

docker compose -f docker-compose.yaml up -d --no-deps --force-recreate app

Then restart the HAP microservices. In cluster mode, apply the configuration and restart the HAP microservices.