Stand with Ukraine flag
Try it now Pricing
Community Edition
Community Edition Professional Edition Cloud Edge PE Edge IoT Gateway License Server Trendz Analytics Mobile Application PE Mobile Application MQTT Broker
Documentation > Security > MQTT Transport > MQTT over SSL
Getting Started
Devices Library Guides Installation Architecture API FAQ
On this page

MQTT over SSL

ThingsBoard provides the ability to run MQTT server over SSL. Both one-way and two-way SSL are supported.

Most of the ThingsBoard environments use the load balancer as a termination point for the SSL connection between the devices and the platform. In other words, MQTT traffic is encrypted between the device and the load balancer, but is decrypted between the load balancer and platform services. The advantage of such an option is the simplicity of configuration. Most of the cloud load balancers (AWS, Google cloud, etc) have built-in certificate generation tools and rich documentation how to configure SSL over TCP. The disadvantage of such an option is that two-way SSL is not possible. The information about client certificate is not passed from the load balancer to the platform services.

Nevertheless, it is possible to configure ThingsBoard to two-way SSL for MQTT and avoid SSL termination on the Load Balancer. We recommend to use valid SSL certificates generated using trusted CA authorities and avoid spending time on resolving issues with self-signed certificates. See instructions below on how to configure SSL for certificates stored in PEM file format or Java Keystore.

SSL configuration using PEM certificates file

Available since TB Version 3.3.2

Configure the following environment variables via configuration file, docker-compose or kubernetes scripts. We will use thingsboard.conf for example:

1
2
3
4
5
6
7

...
export MQTT_SSL_ENABLED=true
export MQTT_SSL_CREDENTIALS_TYPE=PEM
export MQTT_SSL_PEM_CERT=server.pem
export MQTT_SSL_PEM_KEY=server_key.pem
export MQTT_SSL_PEM_KEY_PASSWORD=secret
...

where:

  • MQTT_SSL_ENABLED - Enable/disable SSL support;
  • MQTT_SSL_CREDENTIALS_TYPE - Server credentials type. PEM - pem certificate file; KEYSTORE - java keystore;
  • MQTT_SSL_PEM_CERT - Path to the server certificate file. Holds server certificate or certificate chain, may also include server private key;
  • MQTT_SSL_PEM_KEY - Path to the server certificate private key file. Optional by default. Required if the private key is not present in server certificate file;
  • MQTT_SSL_PEM_KEY_PASSWORD - Optional server certificate private key password.

After completing the setup, start or restart the ThingsBoard server.

doc warn icon

Make sure the certificate files are reachable by ThingsBoard process:

  • Linux: use /etc/thingsboard/conf folder. Make sure the files have same permissions as thingsboard.conf; Use relative file path, e.g. server.pem;
  • Docker Compose: mount or use existing volume to /config folder of the container; Use full file path, e.g. /config/server.pem;
  • K8S: mount separate volume to /https-config or similar folder. Use full file path, e.g. /https-config/server.pem;
  • Windows: use C:\Program Files (x86)\thingsboard\conf\ folder. Make sure the files have same permissions as thingsboard.conf; Use relative file path, e.g. server.pem;

Additional configuration properties

You may configure following additional environment variables via configuration file, docker-compose or kubernetes scripts.

  • MQTT_SSL_BIND_ADDRESS - the bind address for the MQTT server. Default value 0.0.0.0 indicates all interfaces;
  • MQTT_SSL_BIND_PORT - the bind port for the MQTT server. Default value is 8883;
  • MQTT_SSL_PROTOCOL - ssl protocol name. Default value is TLSv1.2. See java doc for more details;
  • MQTT_SSL_SKIP_VALIDITY_CHECK_FOR_CLIENT_CERT - Skip certificate validity check for client certificates. Default value is false.

Self-signed certificates generation

Use instructions below to generate your own certificate files. Useful for tests, but time consuming and not recommended for production.

PEM certificate file

Note This step requires Linux based OS with openssl installed.

To generate a server self-signed PEM certificate and private key, use the following command:

1
2

openssl ecparam -out server_key.pem -name secp256r1 -genkey
openssl req -new -key server_key.pem -x509 -nodes -days 365 -out server.pem

You can also add -nodes (short for no DES) if you don’t want to protect your private key with a passphrase. Otherwise, it will prompt you for “at least a 4 character” password.

The days parameter (365) you can replace with any number to affect the expiration date. It will then prompt you for things like “Country Name”, but you can just hit Enter and accept the defaults.

Add -subj ‘/CN=localhost’ to suppress questions about the contents of the certificate (replace localhost with your desired domain).

Self-signed certificates are not validated with any third party unless you import them to the browsers previously. If you need more security, you should use a certificate signed by a certificate authority (CA).

Client Examples

See following resources: