产品定价 立即试用
云平台
社区版 专业版 云平台 边缘 PE边缘 IoT网关 许可证服务器 Trendz Analytics 移动应用 PE移动应用 MQTT Broker PE MQTT Broker
欧洲地区
北美地区 弗吉尼亚北部区域 欧洲地区 法兰克福区域
文档 > 安全 > MQTT传输 > 基于X.509证书的认证
入门
指南 API 常见问题

基于X.509证书的认证

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.

文档信息图标

Pay attention! EU ThingsBoard Cloud has a separate domain for MQTT traffic. It cannot be white-labeled. If you want an encrypted traffic via MQTT, the device should refer to the corresponding host — eu.mqtt.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 (recommended)
X.509 Certificate

X.509 证书链：

Step 1. 准备服务器与证书链

ThingsBoard Team 已为 ThingsBoard Cloud 配置有效证书。

配置完成后，准备 pem 格式的 CA root 证书。MQTT 客户端将使用该证书校验服务器证书。 将 CA root 证书保存到工作目录，命名为 “ca-root.pem“。 mqtt.eu.thingsboard.cloud 的 CA root 证书示例见此处。

Step 2. 生成 Client 证书链

需生成具有合理 Common Names (CN) 的证书链。将使用中间证书为设备签发证书。 例如，证书链 CN 可如下：

  • Root 证书 CN: company-name.com；
  • Intermediate 证书: device-group-name.company-name.com；
  • Device 证书: device-name.device-group-name.company-name.com；

使用以下命令为各级链生成自签名私钥、证书签发请求和 x509 证书。 命令基于 OpenSSL 工具，工作机通常已安装：

Step 2.1 生成 root 证书

生成 Root 证书和私钥，使用以下命令。提示时请填写正确的 CN：

1

openssl req -x509 -newkey rsa:4096 -keyout rootKey.pem -out rootCert.pem -sha256 -days 365 -nodes
示例输出，CN 为 *company.com* 
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 生成 intermediate 证书

生成 intermediate 密钥和证书请求，使用以下命令。提示时请填写正确的 CN：

1

openssl req -new -newkey rsa:4096 -keyout intermediateKey.pem -out intermediate.csr -sha256 -nodes
示例输出，CN 为 *group.company.com* 
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 []:


生成 intermediate 证书，使用以下命令。提示时请填写正确的 CN：

1

openssl x509 -req -in intermediate.csr -out intermediateCert.pem -CA rootCert.pem -CAkey rootKey.pem -days 365 -sha256 -CAcreateserial -extfile <(echo "basicConstraints=CA:TRUE")
示例输出 
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 生成 device 证书

生成 device 证书，使用以下命令。提示时请填写正确的 CN：

1

openssl req -new -newkey rsa:4096 -keyout deviceKey.pem -out device.csr -sha256 -nodes
示例输出，CN 为 device123.group.company.com 
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 []:


生成 device 证书，使用以下命令。提示时请填写正确的 CN：

1

openssl x509 -req -in device.csr -out deviceCert.pem -CA intermediateCert.pem -CAkey intermediateKey.pem -days 365 -sha256 -CAcreateserial
示例输出 
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


最后，需将证书自 device 证书至 root 依次拼接为链：

1

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

命令将输出各级链的私钥和证书。后续步骤将使用 device 私钥文件 deviceKey.pem 和证书链 chain.pem。

Step 3. 将 Client Intermediate 公钥配置为 Device Profile 的 X509 provision 策略

进入 ThingsBoard Web UI -> Profiles -> Device profiles -> Your Device profile -> Device provisioning。 选择 X.509 Certificates Chain provision 策略，粘贴 intermediateCert.pem 内容及从 deviceCert.pem 提取 common name 的正则，选择是否允许创建新设备并保存。 也可通过 REST API 完成。

Step 4. 测试连接

执行以下命令，通过安全通道向 ThingsBoard Cloud 上报温度数据：

1
2

mosquitto_pub --cafile ca-root.pem -d -q 1 -h "mqtt.eu.thingsboard.cloud" -p "8883" \
-t "v1/devices/me/telemetry" --key deviceKey.pem --cert chain.pem -m {"temperature":25}

请将 YOUR_TB_HOST 替换为您的 ThingsBoard 实例 host。

X.509 证书：

Step 1. 准备服务器与证书链

ThingsBoard Team 已为 ThingsBoard Cloud 配置有效证书。

配置完成后，准备 pem 格式的 CA root 证书。MQTT 客户端将使用该证书校验服务器证书。 将 CA root 证书保存到工作目录，命名为 “ca-root.pem“。 mqtt.eu.thingsboard.cloud 的 CA root 证书示例见此处。

Step 2. 生成 Client 证书

使用以下命令生成自签名私钥和 x509 证书。 命令基于 openssl 工具，工作机通常已安装：

生成 RSA 密钥和证书：

1

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

生成 EC 密钥和证书：

1
2

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

命令输出为私钥文件 key.pem 和公钥证书 cert.pem。 后续步骤将使用这两个文件。

Step 3. 将 Client 公钥配置为 Device Credentials

进入 ThingsBoard Web UI -> Entities -> Devices -> Your Device -> Manage credentials。 选择 X.509 Certificate 设备凭据，粘贴 cert.pem 内容并保存。 也可通过 REST API 完成。

Step 4. 测试连接

执行以下命令，通过安全通道向 ThingsBoard Cloud 上报温度数据：

1
2

mosquitto_pub --cafile ca-root.pem -d -q 1 -h "mqtt.eu.thingsboard.cloud" -p "8883" \
-t "v1/devices/me/telemetry" --key key.pem --cert cert.pem -m {"temperature":25}

请将 YOUR_TB_HOST 替换为您的 ThingsBoard 实例 host。