guide · mqtt
MQTT ACL 设计指南
将设备身份和主题结构转化为最小权限的发布与订阅规则。
版本、来源核对与技术审阅
- 适用场景
- MQTT:协议、架构与生产实践
- 发布日期
- 版本
- 版本信息见一手来源
- 事实与来源
- 已于 2026年7月14日 对照所引来源核对
- 技术审查
- 暂无独立技术审阅记录
结论先行
一句话决策建议
MQTT ACL 应将每个已认证主体绑定到其角色所需的最小主题操作集合。
直接回答
将每个已认证的 MQTT 主体绑定到其角色所需的最小发布和订阅操作。设备通常只应发布自身的遥测、事件、上报状态和确认,只订阅自身的命令或期望状态分支。拒绝其他一切操作。从可信身份属性中提取租户和设备范围,而非从客户端提供的主题段中获取。
范围与边界
MQTT 授权回答的是已连接主体是否可以发布到某个主题或创建订阅过滤器。它不建立设备身份、不校验负载字段、也不在数据离开代理后执行授权。这些控制属于凭据配置、模式校验和下游服务。
代理 ACL 语法因厂商而异。以下设计是可移植的,但变量替换、规则顺序、保留消息检查、共享订阅和管理绕过必须根据所选实现进行验证。
先构建授权模型
按行为而非组织架构列出主体:设备、代表有限设备集合的网关、租户应用、平台服务、运维人员、网桥和代理管理员。对于每个角色,记录精确的发布主题和精确的订阅过滤器。将发布和订阅分开;观察某个分支的权限不应暗示写入该分支的权限。
建立一个从凭据到租户、设备和角色的权威映射。证书主题、令牌声明或配置记录可以在验证后提供这些属性。当映射缺失或模糊时拒绝连接。不要让客户端以 device-42 认证后在主题中选择 device-17。
设计主题使策略保持清晰。给定 v1/{tenant}/devices/{device}/telemetry,设备规则可以插入可信的租户和设备值。命令服务可以发布到命令分支,但不应发布设备遥测。租户消费者可以跨其租户订阅,而全局分析需要一个独立的、经过审计的角色,而非意外的通配符。
实施步骤
- 为发布、订阅、保留操作和管理 API 设置默认拒绝行为。
- 创建机器可读的矩阵,包含主体角色、操作、主题模板和业务负责人。
- 在产品支持的情况下,从可信身份属性生成代理规则。
- 将宽泛的
+和#过滤器视为特权能力;限制扇出并审查负责人。 - 确定授权检查的是请求的过滤器、每个结果主题还是两者兼有。
- 对保留消息、遗嘱消息、共享订阅、网桥和系统主题应用等效检查。
- 记录被拒绝的操作,包含主体、规则、主题和原因,同时脱敏敏感数据。
- 在每次规则或主题模式变更前,使用真实代理测试策略。
关键否定测试
设备不得以其他设备身份发布、订阅同级设备、写入命令主题或通过通配符逃逸其租户。租户服务不得订阅超出其前缀的范围。过期或吊销的凭据必须在声明的吊销窗口内失去访问权限。网桥不得导入绕过本地策略的主题。遗嘱消息必须在 CONNECT 被接受时就获得授权,而非在非正常断连后才被发现。
同时测试保留消息投递。某些系统在写入保留发布时检查权限,另一些在投递时检查,安全设计需要同时考虑两个边界。测试客户端保持连接时的策略重载;缓存决策的存活时间不得超过安全模型允许的时间。
失败模式
规则顺序可能将一个窄范围拒绝变成宽范围允许之后的无效语句。字符串前缀匹配在主题层级未被解析时可能混淆名称相似的租户。共享订阅前缀可能绕过简单的过滤器检查。管理仪表板和 HTTP 发布 API 可能绕过 MQTT ACL。大型通配符订阅即使合法授权,也可能成为可用性事故。
实施清单
- 认证产生可信的主体、租户、设备和角色映射。
- 发布和订阅策略分离且默认拒绝。
- 没有设备可控的值能扩展其授权范围。
- 通配符、保留消息、遗嘱、网桥和共享订阅均已覆盖。
- 否定测试在实际代理版本上运行。
- 策略变更会失效或刷新缓存决策。
- 拒绝操作可观测且不泄露凭据。
- 非 MQTT 代理 API 执行等效授权。
运维证据
保留经评审的授权矩阵、生成的代理策略、否定测试结果,以及从已认证身份到最终规则决策的追踪链路。按原因抽样被拒绝的操作,关注固件或策略发布后的突增。定期枚举特权服务和网桥账户,将其观察到的主题与批准范围进行比较。紧急覆盖需要负责人、过期时间、审计轨迹和事后移除检查。在事件响应期间,保留生效的策略版本和配置源:如果代理加载了不同的内容,排查预期模板就毫无意义。
主要参考来源
OASIS MQTT 5.0 规范定义了主题过滤器、订阅、保留发布、遗嘱和授权相关的 reason code,但未定义 ACL 语言。需结合所选代理的官方授权文档和 NIST SP 800-207,以基于已验证身份和显式策略而非网络位置进行决策。
上线前必读
实施检查清单
- 从经评审的模板生成按角色的策略。
- 部署前测试否定用例。
- 记录拒绝日志但不泄露凭据。
一手来源
事实核验
- OASIS MQTT Version 5.0访问日期 2026年7月14日
来源核对日期 2026年7月14日 · 下次计划核对: 2027年7月14日
维护记录
更新历史
- 2026年7月14日
- 首次发布
- 2026年7月14日
- 更新内容并核对来源
如有不清晰、不准确或过时的内容,请告诉我们。