Securing MQTT using TLS certificates in Home Assistant

This guide will show you how to secure your MQTT communication in Home Assistant using SSL/TLS certificates.

By following this tutorial, you'll:

  • Create a self-signed SSL certificate
  • Configure secure MQTT on port 8883
  • Enable encrypted communication for your IoT devices without certificate validation

Required Home Assistant Add-ons

Install these add-ons from the Home Assistant Add-on Store:

  • Mosquitto broker - For MQTT communication
  • SSH & Web Terminal - To generate certificates
  • File editor - To download certificates to your computer

Install MQTT Explorer

Step-by-Step Setup

1. Install OpenSSL

Access the Home Assistant SSH add-on and install OpenSSL:

apk add openssl

2. Generate Certificates

Generate the certificate and key with your Home Assistant address or host name:

# Using IP address
openssl req -new -x509 -days 365 -nodes -out mqtt.crt -keyout mqtt.key -subj "/CN=192.168.1.12"
# or Using hostname
openssl req -new -x509 -days 365 -nodes -out mqtt.crt -keyout mqtt.key -subj "/CN=homeassistant.local"

3. Move Certificates

Transfer the generated files to the SSL directory:

mv mqtt.* /ssl/

4. Configure Mosquitto

Update your Mosquitto add-on configuration with:

logins: []
require_certificate: false
certfile: mqtt.crt
keyfile: mqtt.key
customize:
  active: false
  folder: mosquitto

5. Test with an MQTT client

  1. Restart the Mosquitto add-on
  2. Test secure connection on port 8883 using MQTT Explorer without the Validate certificate option

6. Configure your OpenMQTTGateway board

  1. Reset your gateway with a long button press or the Home Assistant command "Erase credentials"
  2. Connect to the WiFi access point generated by the gateway
  3. Go to http://192.168.4.1
  4. Enter your WiFi credentials
  5. Enter your MQTT server
  6. Set "mqtt port" 8883
  7. Enter your MQTT login and password
  8. Set "mqtt secure" to true
  9. Enter a "gateway password" if empty
  10. Save

With MQTT Explorer, you should see the gateway connected. The content of the topic ending by SYStoMQTT will confirm you that the gateways uses port 8883 and a secure connection:

"mqttp": "8883",
"mqtts": true,
"mqttv": false,

Security Notes

  • Due to the large memory required by the secure connection some functions may be degraded
  • Port 1883: Unencrypted connection
  • Port 8883: SSL/TLS encrypted connection
  • Certificate validation protects against man-in-the-middle attacks
Back to blog