发布订阅 ACL

    EMQX 支持通过客户端发布订阅 ACL 进行客户端权限的管理，本章节介绍了 EMQX 支持的发布订阅 ACL 以及对应插件的配置方法。

    EMQX 支持使用配置文件、外部主流数据库和自定义 HTTP API 作为 ACL 数据源。

    连接数据源、进行访问控制功能是通过插件实现的，使用前需要启用相应的插件。

    客户端订阅主题、发布消息时插件通过检查目标主题（Topic）是否在指定数据源允许/禁止列表内来实现对客户端的发布、订阅权限管理。

    配置文件/内置数据源

    使用配置文件提供认证数据源，适用于变动较小的 ACL 管理。

    外部数据库

    外部数据库可以存储大量数据、动态管理 ACL，方便与外部设备管理系统集成。

    其他

    提示

    ACL 功能包含在认证鉴权插件中，更改插件配置后需要重启插件才能生效

    规则详解

    ACL 是允许与拒绝条件的集合，EMQX 中使用以下元素描述 ACL 规则：

    同时具有多条 ACL 规则时，EMQX 将按照规则排序进行合并，以 中的默认 ACL 为例，ACL 文件中配置了默认的 ACL 规则，规则从上至下加载：

    1. 第二条规则允许 ip 地址为 127.0.0.1 的客户端发布/订阅 $SYS/# 与 # 主题。
    2. 第三条规则禁止全部客户端订阅 $SYS/# 与 # 主题。
    3. 第四条规则允许客户端发布订阅所有主题。
    1. {allow, {user, "dashboard"}, subscribe, ["$SYS/#"]}.
    3. {allow, {ipaddr, "127.0.0.1"}, pubsub, ["$SYS/#", "#"]}.
    5. {deny, all, subscribe, ["$SYS/#", {eq, "#"}]}.
    7. {allow, all}.

    任何一次 ACL 授权最终都会返回一个结果：

    • 允许：经过检查允许客户端进行操作
    • 禁止：经过检查禁止客户端操作
    • 忽略（ignore）：未查找到 ACL 权限信息，无法显式判断结果是允许还是禁止，交由下一 ACL 插件或默认 ACL 规则来判断

    全局配置

    默认配置中 ACL 是开放授权的，即授权结果为忽略（ignore）时允许客户端通过授权。

    通过 etc/emqx.conf 中的 ACL 配置可以更改该属性：

    配置默认 ACL 文件，使用文件定义默认 ACL 规则：

    1. # etc/emqx.conf

    配置 ACL 授权结果为禁止的响应动作，为 时将断开设备：

    在 MQTT v3.1 和 v3.1.1 协议中，发布操作被拒绝后服务器无任何报文错误返回，这是协议设计的一个缺陷。但在 MQTT v5.0 协议上已经支持应答一个相应的错误报文。

    客户端可拥有“超级用户”身份，超级用户拥有最高权限不受 ACL 限制。

    1. 认证鉴权插件启用超级用户功能后，发布订阅时 EMQX 将优先检查客户端超级用户身份
    2. 客户端为超级用户时，通过授权并跳过后续 ACL 检查

    ACL 缓存

    ACL 缓存允许客户端在命中某条 ACL 规则后，便将其缓存至内存中，以便下次直接使用，客户端发布、订阅频率较高的情况下开启 ACL 缓存可以提高 ACL 检查性能。

    在 etc/emqx.conf 可以配置 ACL 缓存大小与缓存时间：

    1. # etc/emqx.conf
    3. ## 是否启用
    4. enable_acl_cache = on
    6. ## 单个客户端最大缓存规则数量
    7. acl_cache_max_size = 32
    10. acl_cache_ttl = 1m

    在更新 ACL 规则后，某些客户端由于已经存在缓存，则无法立即生效。若要立即生效，则需手动清除所有的 ACL 缓存：

    参见 HTTP API - 清除 ACL 缓存

    当同时启用多个 ACL 插件时，EMQX 将按照插件开启先后顺序进行链式鉴权：

    • 一通过授权，终止链并允许客户端通过验证
    • 一旦授权失败，终止链并禁止客户端通过验证
    • 直到最后一个 ACL 插件仍未通过，根据默认授权配置判定
      • 默认授权为禁止时，禁止客户端通过验证

    提示