MQTT 客户端凭据

• 添加MQTT客户端凭据
  • MQTT Basic凭据
    • 认证
    • 授权规则
    • 修改MQTT Basic凭据密码
  • X.509证书链凭据
    • 认证
    • 授权规则
  • SCRAM
    • 认证
    • 授权规则
• 删除客户端凭据
• 检查连接

TBMQ支持通过Web UI和 REST API 管理MQTT客户端凭据的多种方式。

TBMQ支持以下类型的客户端凭据以认证客户端连接：

• Basic - 基于client ID、username和password组合的基础安全措施。
  • 优点： 简单易实现，应用和服务广泛支持，网络开销低。
  • 缺点： 安全性有限。
• X.509 Certificate Chain - 基于X509证书链的高级安全措施，用于验证客户端身份。
  • 优点： 相比基础凭据安全性更高。使用SSL客户端凭据时，客户端与TBMQ可相互认证。 SSL客户端凭据在访问控制上更灵活，可根据证书主题名等属性制定更细粒度的访问控制策略。
  • 缺点： 配置和管理较复杂，成本更高。SSL加密和解密需要更多计算资源。
• SCRAM - 使用Salted Challenge Response Authentication Mechanism (SCRAM) 的高级安全措施，提供基于密码的安全认证（MQTT5.0增强认证特性）。
  • 优点： 比basic认证安全性更高。采用challenge-response交换哈希凭据，确保密码不以明文传输。
  • 缺点： 生成和验证加盐密码哈希需要额外计算资源。

使用上述任一客户端凭据类型前，请确保已启用相应的 Authentication。

更多安全相关说明，请参阅本指南。

添加MQTT客户端凭据

添加新客户端凭据，请按以下步骤操作：

1. 进入 Authentication-Credentials 页面，点击以加号图标表示的Add Client Credentials 按钮。
2. 填写Name字段（不必唯一）。
3. 选择适用的 Client Type：
   • Device。适用于通常发布大量消息、仅订阅少量低频主题的客户端，即IoT设备。
   • Application。适用于订阅高消息率主题且在离线时需消息持久化的客户端，如ThingsBoard、AWS IoT Core等应用。

   有关客户端类型的更多信息，请参阅文档。

4. 选择所需的 Credentials Type，并配置认证参数和授权规则。

MQTT Basic凭据

认证

MQTT Basic认证基于client ID、username和/或password的不同组合：

• Client ID - 验证连接客户端是否具有指定clientId。
• Username - 验证连接客户端是否具有指定username。
• Client ID and username - 验证连接客户端是否同时具有指定clientId和username。
• Username and password - 验证连接客户端是否同时具有指定username和password。
• Client ID and password - 验证连接客户端是否同时具有指定clientId和password。
• Client ID, username and password - 验证连接客户端是否具有指定clientId、username和password。

授权规则

授权规则模式可根据正则表达式语法控制客户端可发布/订阅的主题：

• 允许特定主题 - 规则 country/.* 将使客户端只能发布/订阅以 country/ 开头的主题。
• 允许任意主题 - 规则 .*（默认）将使客户端能发布/订阅任意主题。
• 禁止所有主题 - 若规则为 empty，则禁止客户端发布/订阅任意主题。

修改MQTT Basic凭据密码

Broker管理员可修改MQTT Basic客户端凭据的密码。操作步骤：

1. 进入 Authentication-Client Credentials 页面。
2. 点击对应Credentials行。
3. 点击 Change password 按钮。
4. 输入当前密码、设置新密码并确认。

X.509证书链凭据

X.509 Certificate chain 是一种基于公钥证书链的TLS双向认证方式。

认证

凭据中 “Use certificate CN regex” 参数支持两种认证选项。 根据该参数，TBMQ可使用证书的Common Name (CN) 精确匹配认证客户端，或使用特定正则匹配并授权客户端， 在客户端验证上提供灵活性。

• Certificate common name (CN) 应完全匹配客户端的证书CN，若存在父证书则需匹配其中之一的CN。 若链中任一证书的CN都不相同，认证将失败。
• Certificate common name (CN) regex 应与客户端证书的CN或（若存在）父证书之一的CN匹配。 若链中任一证书的CN都不与该正则匹配，认证将失败。

授权规则

授权规则用于控制认证成功的客户端可发布/订阅的主题，基于以下条件的成功组合：

• Client certificate CN matcher regex-应与客户端证书的CN匹配。
• Publish/subscribe authorization rule patterns-控制匹配Client certificate CN matcher regex的客户端可发布/订阅的主题。

请参考以下示例：

• 若客户端证书的CN为 cn_example_1-将Client certificate CN matcher regex设为 cn_example_1、example_1 或 .*example.*。
• 若Publish authorization rule patterns设为 pub_topic/one/.*, pub_topic/two/.*-客户端只能发布到以 pub_topic/one/ 或 pub_topic/two/ 开头的主题。
• 若Subscribe authorization rule patterns使用默认值 .*-客户端可订阅任意主题。
• 若Publish/Subscribe authorization rules为空-客户端将无法发布/订阅任何主题。

SCRAM

SCRAM（Salted Challenge Response Authentication Mechanism）是MQTT5客户端的增强认证方式，基于 username和password。

认证

• Username-客户端的唯一标识符，与password配合用于认证。
• Password-仅用户和服务器知晓的密钥。密码在存储和认证前会加盐并哈希。

授权规则

授权规则模式可根据正则表达式语法控制客户端可发布/订阅的主题：

• 允许特定主题 - 规则 country/.* 将使客户端只能发布/订阅以 country/ 开头的主题。
• 允许任意主题 - 规则 .*（默认）将使客户端能发布/订阅任意主题。
• 禁止所有主题 - 若规则为 empty，则禁止客户端发布/订阅任意主题。

删除客户端凭据

Broker管理员可通过Web UI或 REST API 从TBMQ系统中移除客户端凭据。

删除客户端凭据的方式：

1. 单条删除。
   • 点击凭据对应行的 Delete 图标并确认。
   • 点击凭据行后点击 Delete Client Credentials 按钮。
2. 批量删除。
   • 勾选复选框选择多条，再点击右上角 Delete 图标并确认。

检查连接

“Check Connectivity” 工具可自动生成用于订阅主题和发布消息的命令。 该功能使用用户配置的host、port和客户端凭据生成所需命令。

仅支持 Basic 凭据。

打开包含命令的窗口步骤：

1. 点击 “Check connectivity” 按钮打开对应窗口。
2. 在窗口中选择操作系统。
3. 按指南中的命令安装所需客户端工具。
4. 复制并执行命令。

若客户端凭据包含密码，请确保将 “$YOUR_PASSWORD” 替换为实际密码。 以下是带密码凭据的示例命令：

1
2
mosquitto_sub -d -q 1 -h localhost -p 1883 -t tbmq/demo/+ -i "tbmq_eJzCIh6r" -u "tbmq_un_VxUVPaF8" -P "$YOUR_PASSWORD" -v
mosquitto_pub -d -q 1 -h localhost -p 1883 -t tbmq/demo/topic -i "tbmq_eJzCIh6r" -u "tbmq_un_VxUVPaF8" -P "$YOUR_PASSWORD" -m 'Hello World'

若客户端配置的subscribe/publish Authorization rule patterns 与默认值 .*（允许任意主题）不同，表示客户端对发布或订阅有主题限制。 此时需将 “$YOUR_TOPIC” 替换为客户端被允许操作的主题。