Professional Edition
ThingsBoard Documentation
Cloud Professional Edition Community Edition Edge IoT Gateway License Server Trendz Analytics Mobile Application PE Mobile Application
Try it now Pricing
Documentation > Security > MQTT Transport > X.509 Certificate based authentication
Getting Started
Guides Installation Architecture API FAQ

X.509 Certificate Based Authentication

X.509 Certificates are used to setup mutual (two-way) authentication for MQTT over TLS. It is similar to access token authentication, but uses X.509 Certificate instead of token.

Instructions below will describe how to connect MQTT client using X.509 Certificate to ThingsBoard Cloud.

Step 1. Prepare your server and certificate chain

ThingsBoard Team has already provisioned a valid certificate for ThingsBoard Cloud. Follow the MQTT over SSL guide to provision server certificate if you are hosting your own ThingsBoard instance.

Once provisioned, you should prepare a certificate chain in pem format. This chain will be used by mqtt client to validate the server certificate. Save the chain to your working directory as “tb-server-chain.pem”. An example of certificate chain for mqtt.thingsboard.cloud is located here.

Step 2. Generate Client certificate

Use the following command to generate the self-signed private key and x509 certificate. The command is based on the openssl tool which is most likely already installed on your workstation:

To generate the RSA based key and certificate, use:

1
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -sha256 -days 365 -nodes

To generate the EC based key and certificate, use:

1
2
openssl ecparam -out key.pem -name secp256r1 -genkey
openssl req -new -key key.pem -x509 -nodes -days 365 -out cert.pem 

The output of the command will be a private key file key.pem and a public certificate cert.pem. We will use them in next steps.

Step 3. Provision Client Public Key as Device Credentials

Go to ThingsBoard Web UI -> Device Groups -> Group “All” -> Your Device -> Device Credentials.

Select X.509 Certificate device credentials, insert the contents of cert.pem file and click save. Alternatively, the same can be done through the REST API.

Step 4. Test the connection

Execute the following command to upload temperature readings to ThingsBoard Cloud using secure channel:

1
2
mosquitto_pub --cafile tb-server-chain.pem -d -q 1 -h "YOUR_TB_HOST" -p "8883" \
-t "v1/devices/me/telemetry" --key key.pem --cert cert.pem -m {"temperature":25}

Don’t forget to replace YOUR_TB_HOST with the host of your ThingsBoard instance.