EMQX Cloud

简体中文

English
日本語

简体中文

English
日本語

Appearance

联系我们
联系我们

设备接入 mTLS 最佳实践 ​

双向 TLS（mTLS）要求客户端和服务端相互验证证书，从根本上杜绝了未持有有效证书的设备接入。配合关闭端口密码认证，设备连接时无需提供用户名和密码，完全依赖 TLS 客户端证书完成身份验证。

完整配置分为以下三个步骤：

  1. 签发客户端证书：为每台设备签发独立的客户端证书，并在证书 CN 字段中写入设备唯一标识。
  2. 在 EMQX Cloud 中配置 mTLS：上传服务端证书和客户端 CA，开启双向认证，并将证书 CN 字段映射为 Username 或 ClientID。
  3. 关闭端口密码认证：关闭加密端口上的密码认证，设备凭证书即可完成接入。

证书字段映射 ​

EMQX Cloud 支持将客户端证书中的特定字段自动映射为 MQTT 连接的 Username 或 ClientID。开启后，设备无需在连接时手动填写认证信息，EMQX 直接从证书中读取，后续的 ACL 权限规则也可基于该 Username 或 ClientID 进行配置。

可用于映射的字段包括 CN、DN、CRT 等，可在部署设置中按需选择。本文以最常用的 CN（Common Name）字段为例。使用 CN 字段时，建议填写设备序列号、MAC 地址或 UUID 作为设备唯一标识，且每台设备的 CN 必须全局唯一，不得与其他设备共享同一张证书。

准备证书 ​

mTLS 需要以下两套证书：

  • 服务端证书：上传至 EMQX Cloud，用于客户端验证服务端身份。生成步骤请参考生成服务端 CA 证书。
  • 客户端证书：下发至每台设备，用于服务端验证设备身份。生成步骤见下文。

签发客户端证书 ​

生成 Client CA ​

Client CA 用于为每台设备签发客户端证书，只需生成一次。请先确保已安装 OpenSSL。

bash
openssl req \
    -new \
    -newkey rsa:2048 \
    -days 3650 \
    -nodes \
    -x509 \
    -subj "/C=CN/O=EMQX Technologies Co., Ltd/CN=EMQ CA" \
    -keyout client-ca.key \
    -out client-ca.crt

生成的 client-ca.crt 需要在后续步骤中上传至 EMQX Cloud。

为每台设备签发证书 ​

以下步骤为每台设备重复执行，将 device-001 替换为实际的设备标识。

  1. 生成设备私钥。

    bash
    openssl genrsa -out device-001.key 2048

  2. 生成证书请求文件，CN 填写设备唯一标识。

    bash
    openssl req -new -key device-001.key -out device-001.csr \
    -subj "/CN=device-001"

  3. 用 Client CA 签名，生成设备证书。

    bash
    openssl x509 -req -days 3650 -sha256 \
    -in device-001.csr \
    -CA client-ca.crt \
    -CAkey client-ca.key \
    -CAcreateserial \
    -out device-001.crt

  4. 验证证书。

    bash
    openssl verify -CAfile client-ca.crt device-001.crt

在 EMQX Cloud 中配置 mTLS ​

开启双向 TLS ​

在部署的 TLS/SSL 配置面板中上传服务端证书、私钥和客户端 CA 证书。详细的操作步骤请参考在专有版中配置 TLS/SSL。

配置 CN 映射 Username ​

在部署设置中将 CN 字段映射为 MQTT 连接的 Username，后续 ACL 规则可基于该 Username 进行配置。

TIP

仅专有版 v5 部署支持。如果未看到相关配置选项，请提交工单联系我们升级部署版本。

  1. 进入部署详情，点击左侧菜单中的部署设置，选择 MQTT 设置 标签页。
  2. 在使用对端证书作为用户名下拉菜单中选择 cn。
  3. 点击保存。

配置 CN 映射 ClientID ​

如果业务系统需要通过 ClientID 追踪设备，也可以将 CN 映射为 ClientID。

TIP

仅专有版 v5 部署支持。如果未看到相关配置选项，请提交工单联系我们升级部署版本。

  1. 进入部署详情，点击左侧菜单中的部署设置，选择 MQTT 设置 标签页。
  2. 在使用对端证书作为客户端 ID 下拉菜单中选择 cn。
  3. 点击保存。

注意

使用 CN 映射 ClientID 时，必须确保每个设备的 CN 全局唯一。若多台设备共享相同的 CN，将因 ClientID 冲突导致连接相互踢出。

关闭端口密码认证 ​

完成以上配置后，可关闭加密端口上的密码认证，使设备仅凭客户端证书即可接入，无需提供用户名和密码。

注意

关闭密码认证前，请确认所有客户端均已具备有效的客户端证书，并完成端到端的连通性测试，避免影响线上设备连接。同时建议关闭明文端口（1883），仅保留加密端口（8883 / 8084）对外提供服务。

专有版 v5 部署可在控制台自助操作，步骤请参考端口管理 - 管理加密端口的客户端认证。

其他版本部署请提交支持工单，SRE 团队可以帮助您禁用部署中 8883 和 8084 端口上的认证。

客户端连接示例 ​

MQTTX 示例 ​

使用 MQTTX 进行 mTLS 连接测试：

  1. 新建连接，输入连接名称，Client ID 可随机生成。

  2. 选择 Host，填入部署的连接地址和端口：

    • TLS 连接：选择 mqtts://，端口 8883。
    • WebSocket over TLS：选择 wss://，端口 8084。

  3. 端口密码认证已关闭时，无需填写 Username 和 Password。

  4. 启用 SSL/TLS，选择 Self signed。

  5. 填写以下证书文件：

    • CA File：服务端 CA 证书（server-ca.crt）。
    • Client Certificate File：设备客户端证书（device-001.crt）。
    • Client Key File：设备客户端私钥（device-001.key）。

  6. 点击右上角连接。

常见问题 ​

ClientID 冲突导致设备被踢下线 ​

现象： 两台设备共享了相同的 ClientID 或同一张客户端证书，后连接的设备将先连接的设备踢下线。

原因： MQTT 协议规定同一 ClientID 在 Broker 中只能存在一个连接。

解决方案： 确保每台设备持有唯一 CN 的独立证书，避免共享证书。使用 CN 映射 Username 方案可以进一步规避 ClientID 冲突风险。

证书泄露后如何处置 ​

  1. 若已开启 CN 映射 Username，立即将泄露设备的 CN 对应的 Username 添加到黑名单，阻止其重新连接。
  2. 向目标设备补发新证书，更新设备端证书配置。
  3. 在黑名单条目到期或手动删除前，泄露的证书将无法用于连接。

关闭密码认证后是否还需要其他认证手段 ​

关闭端口密码认证后，认证完全依赖 TLS 客户端证书，安全性高于用户名密码方案。如果部分设备暂时无法使用客户端证书，可在过渡期内保留密码认证，待完成全量证书化迁移后再关闭。