产品定价 立即试用
社区版
社区版 专业版 云平台 边缘 PE边缘 IoT网关 许可证服务器 Trendz Analytics 移动应用 PE移动应用 MQTT Broker PE MQTT Broker
文档 > 安全 > MQTT传输 > 基于X.509证书的认证
入门
指南 安装 架构 API 常见问题

基于X.509证书的认证

X.509Certificate用于为MQTToverTLS配置双向认证。 与AccessToken认证类似，但使用X.509Certificate替代token。

以下说明如何使用X.509Certificate将MQTT客户端连接至ThingsboardCloud。

客户端与ThingsBoard之间有两种配置策略：

  • X.509Certificatechain — 推荐。
    将ThingsBoard配置为信任来自特定信任锚（intermediatecertificate）的所有客户端证书。 设备名称通过可配置的正则表达式从证书CommonName自动解析。 证书轮换时无需在每台设备上手动更新证书。 若在配置中启用Createnewdevices，还支持通过MQTT自动provision新设备。
  • X.509Certificate。
    将ThingsBoard配置为接受使用预配置客户端证书的指定设备连接。
X.509 Certificate chain (recommended)
X.509 Certificate

X.509 证书链：

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

若自托管 ThingsBoard，请按 MQTT over SSL 指南配置服务器证书。

配置完成后，准备 pem 格式的 CA root 证书。MQTT 客户端将使用该证书校验服务器证书。 将 CA root 证书保存到工作目录，命名为 “ca-root.pem“。 localhost 的 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 "YOUR_TB_HOST" -p "8883" \
-t "v1/devices/me/telemetry" --key deviceKey.pem --cert chain.pem -m {"temperature":25}

自签名 服务器证书的类似命令：

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}

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

X.509 证书：

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

若自托管 ThingsBoard，请按 MQTT over SSL 指南配置服务器证书。

配置完成后，准备 pem 格式的 CA root 证书。MQTT 客户端将使用该证书校验服务器证书。 将 CA root 证书保存到工作目录，命名为 “ca-root.pem“。 localhost 的 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 "YOUR_TB_HOST" -p "8883" \
-t "v1/devices/me/telemetry" --key key.pem --cert cert.pem -m {"temperature":25}

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