# 默认授权

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

## 添加授权信息

:::tip 提示

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

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

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

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

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

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

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

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

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

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

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

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

![add_acl](./_assets/add_acl_v5_placeholder.png)

占位符只能用于替换主题的整个字段，例如 `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 授权模板为例）如下图所示：

   ![auth_csv](./_assets/authz_csv.png)

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

4. 点击**导入**。

## 查看授权信息

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

## 编辑授权信息

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


## 删除授权信息

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

## 授权模式

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

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

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

::: tip 提示

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

:::

::: caution 注意

出于安全考虑，客户端发起订阅时，订阅主题不能为单独的通配符 `#`。例如，不能订阅 `#`，但可以订阅 `t/#`。此限制仅针对客户端订阅使用的主题过滤器，不影响在授权规则中使用 `#`；例如，可在默认授权中配置拒绝 `#` 作为兜底拒绝规则，以启用白名单模式。

:::

### 切换授权模式（推荐）

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

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

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

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

### 通过规则配置白名单模式

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

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

![acl_deny_all](./_assets/acl_deny_all.png)

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

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

## 查看授权统计

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

![new_authentication](./_assets/authz_statistics.png)