Skip to main content
Version: 0.13.1

Use MQTT authentication for local broker supports certificate-based authentication when communicating with an MQTT broker. Three levels of security are supported:

  1. No authentication (default)
  2. Server authentication
  3. Server + client authentication

Server authentication

Enabling server authentication causes MQTT clients to require a valid certificate from a broker when connecting. The broker certificate is valid when it is signed by a CA that the clients trust.

To enable server authentication, perform the following:

Step 1: Configure server authenticated listener in Mosquitto broker

Create a file in /etc/mosquitto/conf.d/ with the following content and restart mosquitto service:

listener 8883
  • listener 8883: defines a new listener on port 8883
  • certfile: points to a certificate that will be used by the broker to authenticate itself to connecting clients
  • keyfile: points to a private key of the specified certificate, necessary for encrypted communication

Be sure that mosquitto can read both files, especially the private key, which can only be read by the owner. Set mosquitto:mosquitto as an owner of these files. If you're unsure where to place them, /etc/mosquitto/ca_certificates is the directory intended for them, although you can use other paths if necessary.

The certificates used need to be X.509 v3 certificates with a subjectAltName section containing the hostname that the broker is running on.

Step 2: Configure to connect to the new listener

Execute the following commands:

sudo tedge config set mqtt.client.port 8883
sudo tedge config set mqtt.client.cafile PATH_TO_CA_CERTIFICATE

# optional
sudo tedge config set mqtt.client.cadir PATH_TO_CA_CERTIFICATE_DIRECTORY

mqtt.client.cafile and mqtt.client.cadir options point to trusted CA certificate(s) used to verify the broker. If either is used, server authentication is enabled.

Step 3: Restart services

Now you will need to manually restart all the affected services so that they can pick up the configuration change.

Server + client authentication

Additionally, the server can require connecting clients to present a valid certificate. These client certificates need to be signed by a CA that the server trusts. CA used to sign a server certificate and CA signing client certificates do not have to be the same.

Step 1: Configure server + client authenticated listener in Mosquitto broker

Change the content of the conf file defined previously to the following and restart mosquitto service:

listener 8883
allow_anonymous false
require_certificate true
  • allow_anonymous disables anonymous access to the listener; connecting clients will need to authenticate themselves
  • require_certificate requires clients to provide a certificate as a means of authentication

Step 2: Configure to use a client certificate and private key

sudo tedge config set mqtt.client.auth.cert_file PATH_TO_CLIENT_CERTIFICATE
sudo tedge config set mqtt.client.auth.key_file PATH_TO_CLIENT_PRIVATE_KEY

Both certfile and keyfile are required to enable client authentication. Setting only one of them will result in an error about the second one not being set.

As with the server private key, set tedge:tedge as the owner of the certificate and the private key, so that the private key can be read by thin-edge components.

Step 3: Restart services

Now you will need to manually restart all the affected services so that they can pick up the configuration change.

Generating certificates

You can use the following script to generate all required certificates:

openssl req \
-new \
-x509 \
-days 365 \
-extensions v3_ca \
-nodes \
-subj "/C=US/ST=Denial/L=Springfield/O=Dis/CN=ca" \
-keyout ca.key \
-out ca.crt

openssl genrsa -out server.key 2048

openssl req -out server.csr -key server.key -new \
-subj "/C=US/ST=Denial/L=Springfield/O=Dis/CN=$(hostname)"

cat > v3.ext << EOF
keyUsage = digitalSignature, keyAgreement
subjectAltName=DNS:$(hostname), DNS:localhost

openssl x509 -req \
-in server.csr \
-CA ca.crt \
-CAkey ca.key \
-extfile v3.ext \
-CAcreateserial \
-out server.crt \
-days 365

openssl genrsa -out client.key 2048

openssl req -out client.csr \
-key client.key \
-subj "/C=US/ST=Denial/L=Springfield/O=Dis/CN=client1" \

openssl x509 -req \
-in client.csr \
-CA ca.crt \
-CAkey ca.key \
-CAcreateserial \
-out client.crt \
-days 365

Next steps