默认授权

客户端授权用于控制 MQTT 客户端的发布和订阅权限。默认授权基于内置的数据库，为用户提供了一种低成本、开箱即用的授权方式。本文将详细介绍如何添加或导入授权信息，管理授权信息以及如何使用占位符、白名单实现更高级的权限控制。

添加授权信息

提示

内置授权的最大条目数为部署连接数的两倍，上限是 10w。若超过此限额，请使用外部授权。

点击部署左侧菜单中的访问控制 -> 客户端授权，在客户端授权页面上选择 + 添加，新增授权会根据当前所处的分类来新建授权信息。授权可以在以下三个层级进行权限控制：

1. 客户端 ID：对特定客户端 ID 进行授权验证。
2. 用户名：对特定用户名进行授权验证。
3. 全部用户：对所有用户基于主题进行授权验证。

新增客户端 ID 授权

在客户端 ID 标签下创建指定相关客户端 ID 的授权规则。

• 客户端 ID：适用此条规则的客户端。
• 主题：配置该条规则对应的主题。
• 动作：配置该条规则对应的操作。可选值：发布、订阅、发布 & 订阅。
• 权限：是否允许当前客户端操作请求；可选值：允许、不允许。

新增用户名授权

在用户名标签下创建指定相关用户名授权规则。

• 用户名：适用此条规则的用户名。
• 主题：配置该条规则对应的主题。
• 动作：配置该条规则对应的操作。可选值：发布、订阅、发布 & 订阅。
• 权限：是否允许当前用户操作请求；可选值：允许、不允许。

新增主题授权

在全部用户标签下创建指定主题授权规则。

• 主题：配置该条规则对应的主题。
• 动作：配置该条规则对应的操作。可选值：发布、订阅、发布 & 订阅。
• 权限：是否允许当前主题操作请求；可选值：允许、不允许。

使用占位符

您可以在设置主题时使用占位符，在匹配规则时将当前客户端信息等动态替换到主题中，支持的占位符如下：

• ${clientid}
• ${username}

如果您想要限制所有用户只允许订阅或者发布特定主题，可以类似这样填写：

• 用户名 ${username}，主题 xx/${username}/report
• 客户端ID ${clientid}，主题 xx/${clientid}/report

占位符只能用于替换主题的整个字段，例如 a/b/${username}/c/d，但是不能用于替换字段的一部分，例如 a/b${username}c/d。

批量导入授权信息

您可以使用提供的 CSV 模板批量导入授权信息（对全部用户配置授权时不支持导入）。导入字段说明如下：

• clientid：客户端 ID
• username：用户名
• topic：授权的主题
• action：动作（sub/pub/pubsub）
• access：是否允许（allow/deny）

您可以按以下步骤批量导入授权信息：

1. 点击导入按钮。

2. 下载模板。模板示例文件（client ID 授权模板为例）如下图所示：

   

3. 填写授权信息后上传文件。

4. 点击导入。

查看授权信息

当您完成了授权信息的添加，您可以在客户端授权页面中看到授权信息。授权条目的详细信息可以通过客户端 ID, 用户名，全部用户（主题）的三个维度来查看。

编辑授权信息

点击授权信息右侧的编辑图标，可以修改当前授权信息。

删除授权信息

点击授权信息右侧的删除图标，可以对授权信息进行删除。

授权模式

EMQX 支持黑名单模式和白名单模式两种授权策略：

模式	行为
黑名单模式（默认）	未被明确拒绝的发布和订阅操作都会被允许
白名单模式	默认拒绝所有发布和订阅操作，仅允许被明确允许的规则

授权规则按以下顺序匹配：用户名 / 客户端 ID 权限控制 → 全部用户权限控制。系统优先匹配用户名或客户端 ID 的授权规则；若未命中，则继续匹配“全部用户”规则。若最终仍无匹配规则，结果取决于当前授权模式：黑名单模式下请求被允许，白名单模式下请求被拒绝。

提示

• 在“全部用户”权限控制中，若存在多条规则，系统会按规则添加顺序进行匹配（先添加的规则优先生效）。建议将更具体的允许规则（例如 emqx/#）添加在通用拒绝规则（例如拒绝 #）之前，以避免误拦截合法访问。
• 客户端 ID/用户名与主题的组合是唯一的，对于同一客户端 ID/用户名与主题的多条记录，仅最新一条记录有效。
• 如果您添加了扩展授权数据源，请确保在扩展授权页面的授权排序中将“默认授权”排在最后。若希望启用白名单模式，还必须在“默认授权”中添加一条规则：拒绝所有用户发布和订阅 #，作为最终的兜底拒绝规则。

切换授权模式（推荐）

版本说明

授权模式一键切换功能适用于 EMQX 版本为 5.10.3 及以上的 Dedicated 和 Dedicated Flex 部署。Serverless 部署暂不支持此功能。

在支持的部署版本中，可以直接在控制台切换授权模式，无需配置主题规则。操作步骤如下：

1. 进入客户端授权页面。
2. 点击页面右上角的黑名单模式按钮，选择切换为白名单模式。

切换为白名单模式后，系统将默认拒绝所有客户端的发布和订阅操作，需要为客户端配置允许规则才能访问对应主题。

通过规则配置白名单模式

对于不支持授权模式切换的旧版本部署（EMQX 版本 < v5.10.3 或 Serverless 部署），可通过添加拒绝所有主题的规则来实现白名单效果：

在客户端授权页面的全部用户页签下添加一条授权信息，主题中输入 #，主题动作选择发布 & 订阅，权限选择不允许，点击确认。

该规则将作为兜底拒绝规则，未被其他规则明确允许的主题操作均会被拒绝，从而实现白名单效果。

最佳实践

若部署版本支持，建议优先使用控制台的授权模式切换功能开启白名单模式，避免通过”拒绝 #”规则实现白名单逻辑，从而降低配置复杂度。

查看授权统计

点击页面右上方的授权统计图标可以查看授权的指标统计和速率统计。