MQTT 认证：Password、JWT 与 SCRAM

本文对应 Mqttable 当前的 认证方式控件。先选择 MQTT 5.0；Mqttable 在 MQTT 3.1 和 3.1.1 下不显示此控件，而 SCRAM 本身使用 MQTT 5 增强认证流程。

当 Connection 进入已连接状态、Trace 显示被接受的 CONNACK，并且单独的订阅/发布测试证明该身份具备所需 Topic 权限时，认证验证才算完成。

选择认证方式

新建客户端默认选择 Password。请使用 Broker 运维方配置的认证方式和准确凭据格式。只有方式名称还不够：JWT Claim 与 SCRAM Hash 变体也必须匹配 Listener 策略。

None

只在 Listener 明确允许匿名客户端时使用。连接前清空 Username。 选择 None 会禁用密码控件且不发送密码，已保存的凭据仍会保留；非空 Username 仍可能出现在 CONNECT 中。

Password

使用 Broker 运维方签发的 Username 和 Password。Mqttable 会在 CONNECT 中发送它们，因此应配合 TLS，并优先使用已保存的 SecretRef，而不是反复粘贴明文密码。

JWT

Broker 要求在 MQTT Password 字段中携带 JWT 时使用。签名算法、密钥、Claim、 Audience、Issuer、Subject 和过期策略都由 Broker 规则决定。

SCRAM-SHA-256 或 SCRAM-SHA-512

优先选择 Broker 已启用的准确强 Hash 变体。Mqttable 在本地使用 Username 和 Password 完成 Challenge-Response；密码不会作为普通 CONNECT Password 发送。

SCRAM-SHA-1

只用于兼容明确要求这一旧 Hash 的 Broker。不能随意换成其他 SCRAM 变体：两端必须通告同一种方式。

配置 None 或 Password

1. 保存 Broker，再选择 新建客户端。
2. 保持 MQTT 5.0，并选择 Listener 要求的方式。
3. 使用 None 时，连接前清空 Username 和 Password。
4. 使用 Password 时，填写已签发的 Username，并选择一种密码来源：
   • 明文密码用于一次性测试。
   • 已保存 SecretRef用于长期使用。先在 Credentials 中创建 Password Secret，再回到这里选择其不透明引用。
5. 凭据需要经过不可信网络时，使用 MQTTS、WSS 或 QUIC。认证本身不会加密传输。

123

配置 JWT

如果 Broker 运维方给出的是完整 Token，把它粘贴到 密码，或保存为 Password SecretRef；不要重新签名。

只有在你持有正确签名材料、并明确知道 Broker 所需 Claim 时，才使用 JWT 工具：

1. 把认证方式设为 JWT。
2. 确认 Listener 是否还要求单独填写 Username。
3. 打开 JWT 工具。
4. 按运维方要求选择 HS256 并填写共享 Secret，或选择 RS256 并填写 PEM Private Key。
5. 填写策略要求的准确 Claim。初始的 username、iat 和 exp 只是可编辑默认值，不代表 Broker 一定接受。
6. 点击生成并填入，连接前再到预览中检查 Token。

123

当前源码在内嵌 JWT 工具 中增加了 在 JWT 调试器中打开 入口，保留上图中的生成与预览能力。可带入当前 Token 检查签名和有效期，再选择保留原稿返回，或确认将 Token 填回密码草稿。不会自动保存、连接，也不会读取隐藏的已保存凭据或传入签名密钥。此跳转行为不代表现有安装包已更新；操作和临时数据边界见 本地工具。

不要自行猜测 iss、aud、sub 或签名密钥。结构正确的 JWT 仍可能因签名、Claim 或时间窗口不符合 Broker 策略而被拒绝。

配置 SCRAM

1. 确认 Listener 支持 MQTT 5 增强认证，以及准确方式：SCRAM-SHA-1、SCRAM-SHA-256 或 SCRAM-SHA-512。
2. 保持 MQTT 5.0，再选择完全一致的 SCRAM 变体。
3. 同时填写 Username 和 Password；Mqttable 会校验两者都不是空值。
4. Connection 会重复使用时，密码优先选择已保存 SecretRef。
5. 发起连接。Mqttable 会把 SCRAM Authentication Method 和 Challenge Data 放入 MQTT 5 认证属性；密码只在本地参与计算，不作为普通 CONNECT Password 发送。

123

连接并验证认证结果

Broker 表单中的 Test Connection 只验证端点、传输和 TLS，不会发送新建客户端表单中的认证设置。

1. 在新建客户端表单中点击连接。
2. 确认客户端进入已连接状态。
3. 在 Trace 中找到发出的 CONNECT 和收到的 CONNACK。
4. 期望结果是 Connection Accepted。使用 SCRAM 时，还要把完整的增强认证交换作为证据的一部分。
5. 再完成一次有权限的订阅/发布闭环。已连接只证明 Broker 接受了客户端身份，不证明它拥有 Topic 权限。

按结果排查

表单提示 JWT Token 不能为空

粘贴完整 Token、选择已有内容的 SecretRef，或使用正确密钥与 Claim 生成 Token。表单会在建连前阻止空值。

表单提示 SCRAM 凭据不能为空

同时填写 Username 和 Password，并保持 MQTT 5.0。

0x86 Bad User Name or Password

重新核对客户端身份、Secret 或 Token、JWT 签名与过期时间，以及该凭据是否已在当前 Listener 启用。

0x87 Not authorized

Broker 拒绝了该身份或它的建连权限。如果客户端已经连接、只有 Publish 或 Subscribe 失败，应改查 Topic ACL。

0x8C Bad authentication method

确认 Listener 支持 MQTT 5，并检查准确 SCRAM 方式。SHA-1、SHA-256 和 SHA-512 不能互换。

收到 CONNACK 前 TLS Handshake 已失败

此时尚未进入 MQTT 认证。按照 TLS 证书指南 修复端点、CA 信任、服务器名称或 mTLS 配置。

认证边界与秘密材料处理

认证不等于 TLS

认证向 Broker 证明客户端身份；TLS 保护网络链路并验证服务器，mTLS 还能额外认证客户端证书。Password 与 JWT 仍需要受保护的传输。

认证不等于 Topic 授权

被接受的 CONNACK 只证明客户端可以连接。SUBACK、PUBACK 或 Broker 策略仍可能拒绝 Topic 操作。两个阶段要分别验证，不要在真正问题是 ACL 时替换有效密码。

不要把原始秘密放进截图和共享日志

可重复使用的 Password 或 Token 应使用已保存 SecretRef。不要把 Password、JWT、HMAC Secret 或 RSA Private Key 粘贴到 Issue、聊天或截图。材料一旦暴露，先在 Broker 侧轮换，再替换保存的 Secret。

接下来可继续阅读 TLS 证书、Credentials 或第一条 MQTT 消息教程。