MQTT客户端连接失败：MqttSecurityException提示“无权连接”常见原因有哪些？

Question

MQTT客户端连接失败并抛出 `MqttSecurityException: "无权连接"`，常见原因包括：① **认证凭据错误**——用户名/密码为空、拼写错误、过期或服务端未启用对应认证机制（如EMQX未开启`allow_anonymous = false`且未配置ACL）；② **TLS/SSL配置不当**——客户端未正确配置CA证书、双向mTLS中缺少客户端证书或私钥，或证书域名与Broker地址不匹配；③ **ACL权限拒绝**——服务端ACL规则明确禁止该用户连接（如`connect deny`）、或未显式允许`connect`动作；④ **身份鉴权插件异常**——对接LDAP、JWT、HTTP鉴权时回调超时、返回非200状态或格式错误；⑤ **客户端ID违规**——含非法字符、长度超限，或被服务端策略（如EMQX的`clientid_prefix`限制）拦截。排查建议：启用Broker调试日志（如`log.level = debug`），比对客户端连接参数与服务端安全策略一致性，并优先验证基础凭证有效性。

Answer 1

```html

一、现象层：精准识别异常信号

当客户端抛出 MqttSecurityException: "无权连接" 时，该异常并非网络超时或协议不兼容类错误，而是由服务端在 CONNECT 阶段主动拒绝所致——即 MQTT 协议第3.1节定义的 CONNACK 返回码为 0x05 (Not authorized)。此信号明确指向“鉴权失败”，而非“不可达”。需注意：该异常在 Eclipse Paho、HiveMQ Client、EMQX SDK 等主流客户端中语义一致，但部分旧版客户端可能包裹为 IOException 或 RuntimeException，建议通过 getCause() 向上追溯原始异常类型。

二、凭证层：认证凭据的五维校验

• 空值/空白校验：检查 username 和 password 是否为 null、空字符串或仅含空白符（String.trim().isEmpty()）
• 编码一致性：UTF-8 编码下特殊字符（如中文、emoji、控制符）是否被 URL 编码或 Base64 处理；EMQX 5.x 默认启用 auth.password_hash = bcrypt，明文密码将必然失败
• 服务端开关状态：验证 EMQX 的 allow_anonymous = false（etc/emqx.conf）且 authentication = {enable = true}
• 凭据生命周期：若使用 JWT 认证，检查 exp 时间戳是否过期、nbf 是否未生效、iss 是否匹配 Broker 配置
• 凭据存储一致性：对比客户端传入的凭据与服务端 ACL 文件（acl.conf）、数据库表（如 mqtt_user）或 HTTP 鉴权接口返回的凭据哈希值是否完全一致（含大小写、盐值）

三、传输层：TLS/SSL 配置的链路级验证

配置项	常见错误示例	验证命令
CA 证书信任链	客户端仅加载根 CA，未包含中间 CA；或证书 PEM 文件末尾多出空行	openssl verify -CAfile ca.crt client.crt
双向 TLS 客户端证书	私钥未解密（含 ENCRYPTED 标识）、证书与私钥公钥不匹配	openssl x509 -noout -modulus -in client.crt | openssl md5 openssl rsa -noout -modulus -in client.key | openssl md5
Subject Alternative Name (SAN)	证书中 DNS:broker.example.com 与客户端连接地址 ssl://mqtt.example.com:8883 不符	openssl x509 -in broker.crt -text -noout | grep -A1 "Subject Alternative Name"

四、策略层：ACL 与插件鉴权的执行路径分析

EMQX 的鉴权流程遵循「认证 → 授权 → 插件钩子」三级模型。ACL 规则优先级高于插件结果：
① 若 etc/acl.conf 中存在 {deny, all, subscribe, ["$SYS/#"]} 且未显式声明 {allow, {user, "alice"}, connect, []}，则默认拒绝；
② HTTP 鉴权插件（plugins/emqx_auth_http）需在 /auth 接口返回 {"result": "ok"}（严格 JSON 格式），任意字段缺失、HTTP 状态码非 200、响应体含 BOM 头均触发安全异常；
③ LDAP 鉴权中，user_dn 模板变量若含未转义的 %u 占位符，将导致 DN 构造失败并静默拒绝。

五、标识层：Client ID 的合规性治理

graph TD
  A[Client ID 输入] --> B{长度 ≤ 65535 字节？}
  B -->|否| C[Broker 直接断连，日志含 “clientid too long”]
  B -->|是| D{仅含 UTF-8 可见字符？}
  D -->|否| E[EMQX 5.7+ 默认启用 strict_clientid = on，拒绝含 \\x00、\\t、\\r、\\n 等控制字符]
  D -->|是| F{匹配 clientid_prefix 正则？}
  F -->|否| G[被 emqx_conf 配置的 prefix 策略拦截]
  F -->|是| H[进入鉴权流程]

六、诊断层：日志驱动的根因定位法

在 EMQX 中启用全链路调试需组合以下配置：

log.level = debug
log.file.rotation.enable = true
log.file.rotation.max_size = "100MB"
zone.external.authentication = { enable = true, backend = "http" }
zone.external.http.auth_url = "http://auth-svc/auth"

关键日志关键词检索：
• auth_result：查看鉴权插件返回的原始 JSON 响应
• acl_check：定位 ACL 匹配到哪条规则（allow/deny）
• ssl_handshake：确认 TLS 握手阶段是否完成（若此处中断，则属传输层问题）
• client_connect：记录最终 CONNACK 码及拒绝原因字段

```