Stop the war

Stand with Ukraine flag

Support Ukraine

Try it now Pricing
Professional 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 > X.509 Certificate based authentication
Getting Started
Devices Library 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.


In particular, there are two strategies that can be used for establishing connection between client and ThingsBoard:

  • X.509 Certificate chain - recommended.
    Configure ThingsBoard to trust all client certificates from a specific trust anchor (intermediate certificate). The device name is automatically discovered from the certificate Common Name using configurable regular expression. This feature eliminates the need for manual certificate updates on each device when certificate rotation occurs. Furthermore, it allows auto-provisioning new devices over MQTT, if Create new devices is enabled in the configuration.
  • X.509 Certificate.
    Configure ThingsBoard to accept connections from the specific devices using pre-configured client certificates.

X.509 Certificate chain:

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 CA root certificate in pem format. This certificate will be used by mqtt client to validate the server certificate. Save the CA root certificate to your working directory as “ca-root.pem”. An example of CA root certificate for mqtt.thingsboard.cloud is located here.

Step 2. Generate Client certificate chain

We should generate a certificate chain with reasonable Common Names (CNs). We will use the intermediate certificate to sign certificates for our devices. For example, the certificate chain CNs might be the following:

  • Root certificate CN: company-name.com;
  • Intermediate certificate: device-group-name.company-name.com;
  • Device certificate: device-name.device-group-name.company-name.com;

Use the following commands to generate the self-signed private keys, certificate signing requests, and x509 certificates for each chain level. The commands are based on the OpenSSL tool, which is most likely already installed on your workstation:

Step 2.1 Generate root certificate

Generate the Root certificate and private key, use the following command. Don’t forget to put the correct CN when prompted:

1
openssl req -x509 -newkey rsa:4096 -keyout rootKey.pem -out rootCert.pem -sha256 -days 365 -nodes
Sample output, referencing *company.com* as CN
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
Generating a RSA private key
writing new private key to 'rootKey.pem'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:
State or Province Name (full name) [Some-State]:
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgits Pty Ltd]:
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []:company.com
Email Address []:


Step 2.2 Generate intermediate certificate

To generate the intermediate key and certificate request, use the following command. Don’t forget to put the correct CN when prompted:

1
openssl req -new -newkey rsa:4096 -keyout intermediateKey.pem -out intermediate.csr -sha256 -nodes
Sample output, referencing *group.company.com* as CN
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
Generating a RSA private key
writing new private key to 'intermediateKey.pem'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:
State or Province Name (full name) [Some-State]:
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgits Pty Ltd]:
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []:group.company.com
Email Address []:

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:


To generate the intermediate certificate, use the following command. Don’t forget to put the correct CN when prompted:

1
openssl x509 -req -in intermediate.csr -out intermediateCert.pem -CA rootCert.pem -CAkey rootKey.pem -days 365 -sha256 -CAcreateserial
Sample output
1
2
3
Signature ok
subject=C = AU, ST = Some-State, O = Internet Widgits Pty Ltd, CN = group.company.com
Getting CA Private Key


Step 2.3 Generate device certificate

To generate the device certificate, use the following command. Don’t forget to put the correct CN when prompted:

1
openssl req -new -newkey rsa:4096 -keyout deviceKey.pem -out device.csr -sha256 -nodes
Sample output, referencing device123.group.company.com as CN
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
Generating a RSA private key
writing new private key to 'deviceKey.pem'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:
State or Province Name (full name) [Some-State]:
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgits Pty Ltd]:device.group.company.com
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []:
Email Address []:

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:


To generate the intermediate certificate, use the following command. Don’t forget to put the correct CN when prompted:

1
openssl x509 -req -in device.csr -out deviceCert.pem -CA intermediateCert.pem -CAkey intermediateKey.pem -days 365 -sha256 -CAcreateserial
Sample output
1
2
3
Signature ok
subject=C = AU, ST = Some-State, O = Internet Widgits Pty Ltd, CN = device.group.company.com
Getting CA Private Key


Finally, you need to concatenate certificates into a chain starting from the device certificate till the root.

1
cat deviceCert.pem intermediateCert.pem rootCert.pem > chain.pem

The output of the commands will be private keys and certificates for each level of chain. In the next steps we will use device key file deviceKey.pem and a chain of certificates chain.pem.

Step 3. Provision Client Intermediate Public Key as Device Profile X509 provision strategy

Go to ThingsBoard Web UI -> Profiles -> Device profiles -> Your Device profile -> Device provisioning. Select X.509 Certificates Chain provision strategy, insert the contents of intermediateCert.pem file and regular expression pattern to fetch common name from deviceCert.pem, choose allow to create new devices or not 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 ca-root.pem -d -q 1 -h "YOUR_TB_HOST" -p "8883" \
-t "v1/devices/me/telemetry" --key deviceKey.pem --cert chain.pem -m {"temperature":25}

Similar command for the self-signed server certificate:

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

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

X.509 Certificate:

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 CA root certificate in pem format. This certificate will be used by mqtt client to validate the server certificate. Save the CA root certificate to your working directory as “ca-root.pem”. An example of CA root certificate 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 -> Entities -> Devices -> Your Device -> Manage 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 ca-root.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.