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 chainThingsBoard 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 ** is located here. Step 2. Generate Client certificate chainWe 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:
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:
Sample output, referencing *company.com* as CN
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:
Sample output, referencing *group.company.com* as CN
To generate the intermediate certificate, use the following command. Don’t forget to put the correct CN when prompted:
Sample output
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:
Sample output, referencing device123.group.company.com as CN
To generate the intermediate certificate, use the following command. Don’t forget to put the correct CN when prompted:
Sample output
Finally, you need to concatenate certificates into a chain starting from the device certificate till the root.
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 strategyGo 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 connectionExecute the following command to upload temperature readings to ThingsBoard Cloud using secure channel:
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 chainThingsBoard 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 ** is located here. Step 2. Generate Client certificateUse 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:
To generate the EC based key and certificate, use:
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 CredentialsGo 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 connectionExecute the following command to upload temperature readings to ThingsBoard Cloud using secure channel:
Don’t forget to replace YOUR_TB_HOST with the host of your ThingsBoard instance. |