gRPC over TLS/SSL

By default, the gRPC connection between ThingsBoard Edge and the server is unencrypted. Enabling TLS/SSL secures this channel against interception and tampering. Configuration is split into two parts: the server side and the Edge side — both must be completed for the connection to work.

Server configuration

Choose how SSL termination is handled on the server — either using the built-in certificate mechanism or delegating termination to an external load balancer.

Built-in
Load balancer

The built-in mechanism uses self-signed certificates generated with OpenSSL. This approach is suitable for testing but is not recommended for production environments.

Run all certificate generation commands on the ThingsBoard server. Store the generated files in a dedicated directory, for example /etc/thingsboard/conf/certs/:

sudo mkdir -p /etc/thingsboard/conf/certs
cd /etc/thingsboard/conf/certs

Generate a private key:
Terminal window
```
sudo openssl genpkey -algorithm RSA -out privateKey.pem -pkeyopt rsa_keygen_bits:2048
```
This creates a 2048-bit RSA private key stored in privateKey.pem.
Generate a Certificate Signing Request (CSR):
Terminal window
```
sudo openssl req -new -key privateKey.pem -out certRequest.csr
```
Provide your organization name, common name (domain name), and email address when prompted.

Set the common name to localhost if the ThingsBoard server is running locally, or to the server’s domain name if hosted. SSL connections will fail if the certificate’s common name does not match the server’s hostname.
Generate a self-signed certificate valid for 365 days:
Terminal window
```
sudo openssl x509 -req -in certRequest.csr -signkey privateKey.pem -out certFile.crt -days 365
```
Adjust -days to change the validity period. An expired certificate breaks all Edge connections silently — plan for renewal before expiry.

Enable SSL on the ThingsBoard server. For Ubuntu and CentOS/RHEL installations:

sudo sh -c 'cat <<EOL >> /etc/thingsboard/conf/thingsboard.conf
export EDGES_RPC_SSL_ENABLED=true
export EDGES_RPC_SSL_CERT=/etc/thingsboard/conf/certs/certFile.crt
export EDGES_RPC_SSL_PRIVATE_KEY=/etc/thingsboard/conf/certs/privateKey.pem
EOL'

Restart the server to apply the changes:
Terminal window
```
sudo systemctl restart thingsboard
```
Confirm SSL is active by checking the server logs:
Terminal window
```
sudo journalctl -u thingsboard -n 50 | grep -i ssl
```
Look for a line confirming that the gRPC server started with SSL enabled.

Edge configuration

After configuring the server, enable SSL on the Edge side to match.

Debian-based
Docker

Enable SSL communication on the Edge:

sudo sh -c 'cat <<EOL >> /etc/tb-edge/conf/tb-edge.conf
export CLOUD_RPC_SSL_ENABLED=true
EOL'

If you are using self-signed certificates, transfer the server’s public certificate to the Edge device:
Terminal window
```
scp username@server_ip:/etc/thingsboard/conf/certs/certFile.crt /etc/tb-edge/conf/certFile.crt
```
Replace username and server_ip with your server credentials. Then add the certificate path to the Edge configuration:
Terminal window
```
sudo sh -c 'cat <<EOL >> /etc/tb-edge/conf/tb-edge.conf
export CLOUD_RPC_SSL_CERT=/etc/tb-edge/conf/certFile.crt
EOL'
```
Restart Edge to apply the changes:
Terminal window
```
sudo systemctl restart tb-edge
```
Verify the TLS connection was established:
Terminal window
```
sudo journalctl -u tb-edge -n 100 | grep -i ssl
```
Look for a line confirming that the gRPC channel connected with SSL. If you see SSL handshake errors, confirm the certificate’s common name matches the server’s hostname.

Copy certFile.crt from the server to the Edge device:
Terminal window
```
scp username@server_ip:/etc/thingsboard/conf/certs/certFile.crt /path/to/certs/certFile.crt
```
Replace username, server_ip, and the destination path with your actual values.
Open docker-compose.yml and add the following to the environment block:
```
      CLOUD_RPC_SSL_ENABLED: "true"
      CLOUD_RPC_SSL_CERT: "/etc/tb-edge/certs/certFile.crt"
```
Omit CLOUD_RPC_SSL_CERT if you are using a CA-signed certificate — it is only required for self-signed certificates.

Add a volume entry to mount the certificate into the container:
```
    volumes:
      - /path/to/certs/certFile.crt:/etc/tb-edge/certs/certFile.crt
```
Restart the Edge container:
Terminal window
```
docker compose restart mytbedge
```
Verify the TLS connection was established:
Terminal window
```
docker logs mytbedge 2>&1 | grep -i ssl
```
Look for a line confirming that the gRPC channel connected with SSL. If you see SSL handshake errors, confirm the certificate’s common name matches the server’s hostname.