权限列表

本页面介绍了 JWT 认证和 HTTP 认证支持的权限列表 (ACL) 规则。目前，JWT 认证和 HTTP 认证支持权限预设，使用 ACL 作为认证结果的可选扩展，例如，JWT 中定义的私有声明 acl，或作为 HTTP 认证响应的一部分返回 acl JSON 属性。客户端连接后的发布和订阅动作将会受到这些 ACL 规则的限制。

通用的 ACL 规则存储在 acl.conf 中。详情请参见acl.conf。更全面的授权方法请参见授权。

TIP

通过认证设置的权限列表，将优先于所有授权检查器被检查，参考授权检查优先级。

权限列表格式

本节介绍了目前 EMQX 支持的 2 种不同格式的权限列表。

新版格式

新版格式从 EMQX v5.5.0 开始支持，使用了权限列表来指定多条权限，更接近 ACL 规则的语义且使用更加灵活。

不同于旧版格式，使用新版格式时，当客户端操作未匹配到任何规则时，EMQX 将继续执行授权检查器的检查。旧版格式仍然是兼容的，但建议使用新版格式。

权限列表包含以下字段：

字段	必选	含义
permission	是	是否允许当前客户端的操作请求；可选值：allow、deny。
action	是	规则对应的操作；可选值: publish、subscribe、 all。
topic	是	规则对应的主题，支持主题占位符。
qos	否	数组，指定规则适用的消息 QoS，如 [0, 1]、[1, 2]，默认为全部 QoS。
retain	否	布尔值，仅用于发布操作，指定当前规则是否支持发布保留消息，可选值有 true、false，默认允许保留消息。
clientid_re (e5.9.0+)	否	用于匹配客户端 ID 的正则表达式，例如 ^client-[0-9]+$。
username_re (e5.9.0+)	否	用于匹配用户名的正则表达式，例如 ^user-[0-9]+$。
ipaddr (e5.9.0+)	否	IP 地址或子网，例如 192.168.5.0/24。
zone (e5.9.0+)	否	区域名称，例如 zone1。
zone_re (e5.9.0+)	否	用于匹配区域名称的正则表达式，例如 ^zone-[0-9]+$。
listener (e5.9.0+)	否	监听器名称，例如 tcp:default。

只有当规则中所有设置的字段都匹配客户端属性时，该规则才会被应用。

示例：

{
  "exp": 1706844358,
  "username": "emqx_u",
  "acl": [
    {
      // 允许客户端发布 t/${clientid} 主题的消息，例如 t/emqx_c
      "permission": "allow",
      "action": "publish",
      "topic": "t/${clientid}"
    },
    {
      "permission": "allow",
      "action": "subscribe",
      // `eq` 前缀意味着该规则仅适用于主题过滤器 t/1/#，但不适用于 t/1/x 或 t/1/y 等
      "topic": "eq t/1/#",
      // 该规则只匹配 QoS 1 但不匹配 QoS 0 或 2
      "qos": [1]
    },
    {
      // 禁止客户端发布 t/2 主题的保留消息，消息为非保留消息则是允许的
      "permission": "deny",
      "action": "publish",
      "topic": "t/2",
      "retain": true
    },
    {
      // 禁止客户端发布或订阅 t/3 主题，包括所有 QoS 级别和保留消息
      "permission": "deny",
      "action": "all",
      "topic": "t/3"
    }
  ]
}

旧版格式

以下 JWT 权限列表示例定义了 pub、sub 和 all 3 个可选字段，分别用于指定发布、订阅以及发布订阅的主题白名单列表。主题中允许使用主题通配符和占位符（目前仅支持 ${clientid} 与 ${username}）。由于可能存在主题内容与占位符语法冲突的情况，我们也提供了 eq 语法来取消占位符插值。

{
  "exp": 1654254601,
  "username": "emqx_u",
  "acl": {
    "pub": [
      "testpub1/${username}",
      "eq testpub2/${username}"
    ],
    "sub": [
      "testsub1/${username}",
      "testsub2/${clientid}",
      "testsub2/#"
    ],
    "all": [
      "testall1/${username}",
      "testall2/${clientid}",
      "testall3/#"
    ]
  }
}

其中，testpub1/${username} 会在运行时被替换为 testpub1/emqx_u，而 eq testpub2/${username} 在运行时仍会按照 testpub2/${username} 处理。

:::

::::