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.
List the names and IP addresses that Edge uses to reach the server (the value of CLOUD_RPC_HOST on the Edge) as subject alternative names. Replace the examples with your values:
Terminal window
```
echo "subjectAltName=DNS:tb.example.com,IP:192.168.1.10" | sudo tee san.ext
```
Edge checks the server’s host name or IP address against the subject alternative names of the certificate, not against the common name. If the certificate has no matching entry, the connection fails with No subject alternative names present or a host name mismatch in the Edge log.
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 -extfile san.ext
```
Adjust -days to change the validity period. An expired certificate breaks all Edge connections silently — plan for renewal before expiry.

Give the ThingsBoard service access to the files:
Terminal window
```
sudo chown thingsboard:thingsboard privateKey.pem certFile.crt
```

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
```
Check that the server presents the certificate on the gRPC port:
Terminal window
```
openssl s_client -connect localhost:7070 </dev/null 2>/dev/null | grep subject=
```
The output shows the subject of your certificate. The server log has no SSL-specific line: it reports only Edge/Agent RPC server initialized!.

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:

scp username@server_ip:/etc/thingsboard/conf/certs/certFile.crt /tmp/certFile.crt
sudo mv /tmp/certFile.crt /etc/tb-edge/conf/certFile.crt
sudo chmod 644 /etc/tb-edge/conf/certFile.crt

Replace username and server_ip with your server credentials. Then add the certificate path to the Edge configuration:

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 that Edge connected. In the Edge UI, Edge > Status shows Connected, and the log has a new Configuration received line:
Terminal window
```
grep -E "Configuration received|SSLHandshakeException|subject alternative" /var/log/tb-edge/tb-edge.log | tail -5
```
If you see SSL handshake errors, check that the certificate lists the value of CLOUD_RPC_HOST as a subject alternative name.

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
```
Recreate the Edge container to apply the changes (docker compose restart does not pick up changes to docker-compose.yml):
Terminal window
```
docker compose up -d
```
Verify that Edge connected. In the Edge UI, Edge > Status shows Connected, and the log has a new Configuration received line:
Terminal window
```
docker compose logs mytbedge | grep -E "Configuration received|SSLHandshakeException|subject alternative" | tail -5
```
If you see SSL handshake errors, check that the certificate lists the value of CLOUD_RPC_HOST as a subject alternative name.

Was this helpful?