Basic 认证

• Basic认证概述
• 配置provider
• 凭证匹配
• Credentials ID
• 授权
• 基于Client ID、Username和Password的MQTT示例
• 基于Client ID、Username和Password的MQTTS示例
• 下一步

Basic认证因其简单且MQTT协议原生支持，仍是最常用的MQTT客户端认证方式之一。 常用于客户端预置凭证的场景，例如连接私有网络的IoT设备、内部系统集成或访问控制要求简单的部署。 结合安全传输（TLS）使用时，可为多种MQTT场景提供可靠且广泛采用的认证选项。

Basic认证概述

Basic认证允许MQTT客户端使用 CONNECT 包中的凭证（如clientId、username、password）进行认证。 TBMQ使用这些凭证生成唯一的 credentialsId，并通过灵活匹配策略与存储的 MQTT客户端凭证记录匹配。 为优化认证性能，TBMQ在Redis中维护凭证以便快速查找，PostgreSQL负责可靠持久化。 以下各节说明provider配置、凭证匹配、credentialsId 生成以及认证成功后的授权应用。

配置provider

您可直接在TBMQ用户界面中查看认证提供者状态、启用或禁用它们，无需修改配置文件或重启broker即可轻松管理认证行为。

• 在首页的 Broker Settings 卡片中，可找到每个可用认证提供者的快捷切换按钮。 点击目标提供者旁的按钮即可启用或禁用。
• 在 Authentication Providers 页面，可进行更精细的控制和查看：
  • 通过点击表格对应行的Switch按钮，可直接启用或禁用提供者。
  • 如需更细致的管理，点击提供者打开详情页，可修改状态或其他参数。

凭证匹配

以下是Basic凭证匹配器的可选组合：

• clientId - 检查连接客户端是否指定了clientId；
• username - 检查连接客户端是否指定了username；
• clientId和username - 检查连接客户端是否同时指定clientId和username；
• username和password - 检查连接客户端是否同时指定username和password；
• clientId和password - 检查连接客户端是否同时指定clientId和password；
• clientId、username和password - 检查连接客户端是否同时指定clientId、username和password。

Credentials ID

客户端连接时，CONNECT包中的username、password和clientId组合与持久化凭证匹配以进行认证。 匹配基于MQTT客户端凭证中自动生成的 credentialsId 字段。

credentialsId生成规则如下：

• 仅存在username时：credentialsId = username|$CLIENT_USERNAME；
• 仅存在client ID时：credentialsId = client_id|$CLIENT_ID；
• 同时存在username和client ID时：credentialsId = mixed|$CLIENT_USERNAME|$CLIENT_ID。

其中 $CLIENT_USERNAME 指指定username，$CLIENT_ID 指 CONNECT 包中的client ID。

授权

用户认证成功后，可限制客户端对可发布或订阅主题的访问。

TBMQ使用正则表达式提供灵活的授权规则控制。

例如，要允许客户端发布或订阅以 city/ 开头的所有主题，应创建值为 city/.* 的授权规则。

对于Basic类型，授权通过对应MQTT客户端凭证的 pubAuthRulePatterns 和 subAuthRulePatterns 配置。 因此，可为每个Basic MQTT客户端凭证配置这些客户端可访问主题的授权规则。

pubAuthRulePatterns 和 subAuthRulePatterns 基于正则表达式语法。例如：

1
2
3
4
{
    "pubAuthRulePatterns": ["country/.*"],
    "subAuthRulePatterns": ["city/.*"]
}

以下配置允许客户端向以 country/ 开头的主题发布消息，并订阅以 city/ 开头的主题。

基于Client ID、Username和Password的MQTT示例

在此选项中，需在MQTT客户端凭证中填写Client ID、Username和Password。MQTT客户端若指定正确的client ID、username和password组合即可连接。

下面是一条使用MQTT client ID、username和password向TBMQ发布消息的简单命令。该命令使用纯MQTT（无TLS）：

1
mosquitto_pub -d -q 1 -h "YOUR_TBMQ_HOST" -p "1883" -t "sensors/temperature" -i "YOUR_CLIENT_ID" -u "YOUR_CLIENT_USERNAME" -P "YOUR_CLIENT_PASSWORD" -m {"temperature":25}

其中：

• YOUR_TBMQ_HOST-TBMQ实例的主机地址；
• YOUR_CLIENT_ID-客户端ID；
• YOUR_CLIENT_USERNAME、YOUR_CLIENT_PASSWORD-客户端用户名和密码。

基于Client ID、Username和Password的MQTTS示例

单向SSL认证是标准认证模式，客户端通过服务器证书验证服务器身份。 请参阅 MQTT over SSL 指南为TBMQ实例配置服务器证书。

下面是一条使用MQTT client ID、username和password通过MQTTS向TBMQ发布消息的简单命令：

1
mosquitto_pub -d -q 1 --cafile YOUR_PEM_FILE -h "YOUR_TBMQ_HOST" -p 8883 -t "sensors/temperature" -i "YOUR_CLIENT_ID" -u "YOUR_CLIENT_USERNAME" -P "YOUR_CLIENT_PASSWORD" -m {"temperature":25}

其中：

• YOUR_PEM_FILE-CA证书文件路径；
• YOUR_TBMQ_HOST-TBMQ实例的主机地址；
• YOUR_CLIENT_ID-客户端ID；
• YOUR_CLIENT_USERNAME、YOUR_CLIENT_PASSWORD-客户端用户名和密码。

下一步

• 快速入门指南 - 本指南提供 TBMQ 的快速概览。

• 安装指南 - 学习如何使用 Docker 配置 TBMQ 或在 AWS、GCP、Azure 的 K8S 环境中部署。

• 配置指南 - 了解 TBMQ 配置文件和参数。

• MQTT 客户端类型指南 - 了解 TBMQ 客户端类型。

• 与 ThingsBoard 集成 - 了解如何将 TBMQ 与 ThingsBoard 集成。