emqx · Meggielqk · Aug 11, 2025
diff --git a/en_US/access-control/authz/mnesia.md b/en_US/access-control/authz/mnesia.md
@@ -8,7 +8,7 @@ Knowledge about [basic EMQX authorization concepts](./authz.md)
 
 :::
 
-## Configure with Dashboard
+## Create Built-in Database Authorizer via Dashboard
 
 1. On the [EMQX Dashboard](http://127.0.0.1:18083/#/authentication), navigate to **Access Control** > **Authorization** in the left-hand menu to open the **Authorization** page.
 
@@ -26,7 +26,7 @@ Knowledge about [basic EMQX authorization concepts](./authz.md)
 
 4. Click **Create** to complete the setup.
 
-## Configure with Configuration File
+## Create Built-in Database Authorizer via Configuration File
 
 The built-in database authorizer is identified by type `built_in_database`.
 
@@ -51,37 +51,102 @@ You can create authorization rules through the Dashboard or API.
 
 ### Create Authorization Rules via Dashboard
 
-On the **Authorization** page in Dashboard, click the **Permissions** button in the **Actions** column of the **Built-in Database** backend.
+You can define authorization rules directly from the EMQX Dashboard by using the **Permissions** page of the **Built-in Database** backend.
+
+#### Access the Permissions Page
+
+1. In the Dashboard, go to the **Authorization** page.
+2. In the **Actions** column of the **Built-in Database** backend, click **Permissions**.
 
 ![authz-mnesia-rule](./assets/authz-mnesia-rule.png)
 
-You can set authorization checks based on the client ID, username, or topic as needed.
+#### Authorization Rule Scope
+
+Authorization rules can be configured at three scopes:
+
+- **Client ID**: Apply rules to a specific client ID.
+- **Username**: Apply rules to a specific username.
+- **All Users**: Apply rules to all clients/users, optionally filtered by patterns or IP ranges.
+
+#### Common Rule Fields
+
+These fields are available for all rule types:
+
+| Field                | Description                                                  |
+| -------------------- | ------------------------------------------------------------ |
+| **Action**           | The operation type the rule applies to. Options: `Publish`, `Subscribe`, `Publish & Subscribe`. |
+| **Permission**       | Whether to allow or deny the operation. Options: `Allow`, `Deny`. |
+| **Topic**            | The MQTT topic this rule applies to. Wildcards (`+`, `#`) are supported. |
+| **QoS**              | Allowed QoS levels. Multiple values can be selected: `0`, `1`, `2`. |
+| **Retain**           | Whether the rule applies to retained messages. Options: `true`, `false`, `All`. |
+| **IP Address Range** | Specifies the client IP range this rule applies to. Supports CIDR notation (e.g., `192.168.1.0/24`) or exact IPs. |
+| **Listener**         | The listener this rule applies to. Use `{type}:{name}` format, e.g., `tcp:default`, `ws:default`. |
+| **Zone**             | The Zone in which the rule takes effect. Applicable in multi-Zone deployments. |
+
+#### Fields by Rule Scope
+
+| Rule Scope    | Fields                                                       |
+| ------------- | ------------------------------------------------------------ |
+| **Client ID** | **Client ID**: (Required) Exact client ID to which this rule applies.<br />**Username Pattern**: (Optional) A regular expression to match usernames for which this rule is valid. |
+| **Username**  | **Username**: (Required) Exact username to which this rule applies.<br />**Client ID Pattern**: (Optional) A regular expression to match client IDs for which this rule is valid. |
+| **All Users** | **Client ID Pattern**: (Optional) A regular expression to match usernames for which this rule is valid.<br />**Username Pattern**: (Optional) A regular expression to match usernames for which this rule is valid. |
+
+**Example patterns:**
+
+- `^device-user-.*`: Matches usernames starting with `device-user-`.
+- `^sensor-.*`: Matches client IDs starting with `sensor-`.
+
+#### Add a Rule
+
+1. On the **Permissions** page, select the target tab: **Client ID**, **Username**, or **All Users**.
+2. Click **Add**.
+3. Fill in the [common fields](#common-rule-fields) and any [scope-specific fields](#fields-by-rule-scope).
+4. (Optional) Click **Add Permission** to add multiple rules. Use the **Up** and **Down** buttons to adjust rule execution order.
+5. Click **Add** to save the rule.
+
+#### Manage Multiple Rules (All Users Only)
+
+For **All Users** rules, you can change rule order from the **More** menu in the **Actions** column:
+
+- Move Up
+- Move Down
+- Move to Top
+- Move to Bottom
 
-- **Client ID**: See the **Client ID** tab, specify the client that this rule applies to.
-- **Username**: See the **Username** tab, specify the user that this rule applies to.
-- **Permission**: Whether to allow or deny a certain type of operation request from the current client/user; optional values: **Allow**, **Deny**.
-- **Action**: Configure the operation corresponding to this rule; optional values: **Publish**, **Subscribe**, **Publish & Subscribe**.
-- **Topic**: Configure the topic corresponding to this rule.
+Rules are evaluated from top to bottom, so order determines priority.
 
-EMQX supports configuring multiple authorization check rules for a single client or user, and you can adjust the execution order and priority of different rules through the **Move Up** and **Move Down** buttons on the page.
+#### Edit and Manage Rules
 
-If you want to configure authorization check rules for multiple clients or users at the same time, you can import the relevant configuration through the HTTP API.
+On the **Permissions** page, you can edit or delete existing rules:
 
-### Create via REST API
+- In the **Actions** column of the corresponding rule, click the **Edit** button to modify rule fields, matching patterns, or IP range settings.
+- Click the **Delete** button to remove a rule.
 
-Rules are also managed through `/api/v5/authorization/sources/built_in_database` APIs.
+### Create Authorization Rules via REST API
 
-Each rule is applied to:
-* a particular client identified by clientid
+Rules are also managed through `/api/v5/authorization/sources/built_in_database` API endpoints.
+
+Each rule can be applied to:
+* A specific client by client ID
   *  `/api/v5/authorization/sources/built_in_database/clientid`
-* a particular client identified by username
+* A specific client by username
   * `/api/v5/authorization/sources/built_in_database/username` 
 
 * all clients
   *  `/api/v5/authorization/sources/built_in_database/all` 
 
+#### Using Regular Expressions and IP Ranges
+
+In addition to exact matches for client ID or username, you can define rules for groups of clients using regular expressions or IP address ranges. This allows you to apply the same ACLs to multiple clients that share the same naming pattern or network location, avoiding the need to create duplicate rules multiple times.
+
+Two new fields are available for this purpose:
+
+| Field           | Description                                                  |
+| --------------- | ------------------------------------------------------------ |
+| **scope**       | The match type for the rule. Options: `all` (default), `clientid_re` (client ID regex), `username_re` (username regex), `ipaddress` (IP or CIDR). |
+| **scope_value** | The value to match against, based on the `scope` type. For regex, provide a regular expression (e.g., `^emqx-.*`). For `ipaddress`, use exact IP or CIDR notation (e.g., `192.168.1.0/24`). |
 
-Below is a quick example of how to create rules for a client (`client1`):
+Below is an example of how to create rules for a client (`client1`):
 
 ```bash
 curl -X 'POST' \
@@ -91,31 +156,37 @@ curl -X 'POST' \
   -d '[
   {
     "clientid": "client1",
+    "scope": "username_re",
+    "scope_value": "^emqx-.*",
     "rules": [
       {
-        "action": "publish",
         "permission": "allow",
-        "topic": "test/topic/1"
+        "action": "publish",
+        "topic": "v1/devices/#"
       },
       {
-        "action": "subscribe",
-        "permission": "allow",
-        "topic": "test/topic/2"
+        "permission": "deny",
+        "action": "all",
+        "topic": "v1/#"
       },
       {
-        "action": "all",
-        "permission": "deny",
-        "topic": "eq test/#"
+        "permission": "allow",
+        "action": "subscribe",
+        "topic": "v1/devices/+/robot_state"
       }
     ]
   }
 ]'
 ```
 
 Each rule contains:
-* `permission`: Whether to allow or deny a certain type of operation request from current client/user; optional values: `allow` or `deny`;
+
+- `clientid`: Exact Client ID to which this rule applies.
+- `scope`: The additional matching filter. `scope = "username_re"` with `scope_value = "^emqx-.*"` means these rules only apply to usernames starting with `emqx-` *for this client*.
+
+* `permission`: Whether to allow or deny a certain type of operation request from the current client/user; optional values: `allow` or `deny`;
 * `action`: Configure the operation corresponding to this rule; optional values: `publish`, `subscribe`, or `all`;
-* `topic`: Configure the corresponding to this rule, supporting [topic placeholders](./authz.md#topic-placeholders).
-* `qos`: (Optional) A number array used to specify the QoS levels that the rule applies to, e.g. `[0, 1]`, `[1, 2]`. The default is all QoS levels.
+* `topic`: Configure the corresponding topic to this rule, supporting [topic placeholders](./authz.md#topic-placeholders).
+* `qos`: (Optional) A number array used to specify the QoS levels that the rule applies to, e.g., `[0, 1]`, `[1, 2]`. The default is all QoS levels.
 * `retain`: (Optional) Used to specify whether the current rule supports retained messages. Value options are `true`, `false`. Default is to allow retained messages.
 
diff --git a/zh_CN/access-control/authz/mnesia.md b/zh_CN/access-control/authz/mnesia.md
@@ -1,12 +1,13 @@
-# 内置数据库
+# 内置数据库授权
 
 EMQX 通过内置数据库为用户提供了一种低成本、开箱即用的授权规则存储方式。您可以通过 Dashboard 或配置文件设置使用内置数据库作为数据源，通过 Dashboard 或 HTTP API 添加相关授权检查规则。
+
 ::: tip 前置准备
 
 熟悉 [EMQX 授权基本概念](./authz.md)
 :::
 
-## 通过 Dashboard 配置
+## 通过 Dashboard 创建内置数据库授权器
 
 1. 在 [EMQX Dashboard](http://127.0.0.1:18083/#/authentication) 中，点击左侧菜单的**访问控制** > **授权**，进入**授权**页面。
 
@@ -22,9 +23,9 @@ EMQX 通过内置数据库为用户提供了一种低成本、开箱即用的授
 
    :::
 
-4. 点击**创建**完成配置。
+4. 点击**创建**完成设置。
 
-## 通过配置文件配置
+## 通过配置文件创建内置数据库授权器
 
 您也可通过配置文件中的 `authorization` 字段配置通过 EMQX 内置数据库存储授权规则。
 
@@ -44,39 +45,106 @@ EMQX 通过内置数据库为用户提供了一种低成本、开箱即用的授
 
 <!--详细参数列表，请参考 [authz-mnesia](../../configuration/configuration-manual.html#authz-mnesia)。-->
 
-## 配置授权检查规则
+## 创建授权检查规则
+
+您可以通过 Dashboard 或 REST API 创建授权检查规则。
+
+### 通过 Dashboard 创建授权检查规则
 
-您可通过 Dashboard 或 API 配置授权规则。
+您可以在 EMQX Dashboard 中的**内置数据库**后端**权限管理**页面直接定义授权检查规则。
 
-### 通过 Dashboard 配置
+#### 进入权限管理页面
 
-在 Dashboard 的**授权**页面，点击**内置数据库**数据源对应的**操作**栏下的**权限管理**，即可进行授权检查规则的配置。
+1. 在 Dashboard 中，进入**访问控制**页面。
+2. 在已创建的**内置数据库**后端的**操作**列中，点击**权限管理**。
 
 ![authz-mnesia-rule](./assets/authz-mnesia-rule.png)
 
-您可根据需要从客户端 ID、用户名或直接从主题角度设置授权检查。
+#### 授权检查规则作用范围
+
+权限规则可以在以下三个作用范围内配置：
+
+- **客户端 ID**：将规则应用于特定客户端 ID。
+- **用户名**：将规则应用于特定用户名。
+- **全部用户**：将规则应用于所有客户端/用户，可选按匹配模式或 IP 范围进行过滤。
+
+#### 通用规则字段
+
+以下字段适用于所有类型的规则：
+
+| 字段            | 说明                                                         |
+| --------------- | ------------------------------------------------------------ |
+| **操作**        | 规则适用的操作类型，可选：`发布时`、`订阅时`、`发布和订阅时`。 |
+| **权限**        | 是否允许该操作，可选：`允许`、`拒绝`。                       |
+| **主题**        | 规则适用的 MQTT 主题，支持通配符（`+`、`#`）。               |
+| **QoS**         | 允许的 QoS 等级，可多选：`0`、`1`、`2`。                     |
+| **Retain**      | 是否将规则应用于保留消息，可选：`true`、`false`、`全部`。    |
+| **IP 地址范围** | 规则适用的客户端 IP 范围，支持 CIDR 表示法（如 `192.168.1.0/24`）或精确 IP。 |
+| **监听器**      | 规则适用的监听器，格式 `{监听器类型}:{监听器名称}`，如 `tcp:default`、`ws:default`。 |
+| **Zone**        | 规则生效的 Zone 区域，适用于多 Zone 部署。                   |
+
+#### 不同作用范围规则的专用字段
+
+| 作用范围      | 字段                                                         |
+| ------------- | ------------------------------------------------------------ |
+| **客户端 ID** | **客户端 ID**：（必填）规则适用的精确客户端 ID。<br />**用户名表达式**：（可选）匹配用户名的正则表达式。 |
+| **用户名**    | **用户名**：（必填）规则适用的精确用户名。<br />**客户端 ID 表达式**：（可选）匹配客户端 ID 的正则表达式。 |
+| **全部用户**  | **客户端 ID 表达式**：（可选）匹配客户端 ID 的正则表达式。<br/>**用户名表达式**：（可选）匹配用户名的正则表达式。 |
+
+**匹配模式示例：**
+
+- `^device-user-.*`：匹配以 `device-user-` 开头的用户名。
+- `^sensor-.*`：匹配以 `sensor-` 开头的客户端 ID。
+
+#### 创建规则
+
+1. 在**权限管理**页面中，选择目标标签页：**客户端 ID**、**用户名**或**全部用户**。
+2. 点击**添加**。
+3. 填写[通用规则字段](#通用规则字段)以及对应作用范围的[专用字段](#不同作用范围规则的专用字段)。
+4. （可选）点击**添加权限**可一次性新增多条规则（仅适用于”客户端 ID“ 和”用户名“规则）。可使用**上移**或**下移**调整规则执行顺序。
+5. 点击**添加**保存规则。
+
+#### 管理规则顺序（仅适用于“全部用户”）
+
+对于**全部用户**规则，您可以通过**操作**列的**更多**菜单调整规则顺序：
+
+- 上移
+- 下移
+- 移到顶部
+- 移到底部
 
-- **客户端 ID**：见 **客户端 ID** 页签，指定适用此条规则的客户端
-- **用户名**：见 **用户名** 页签，指定适用此条规则的用户名
-- **权限**：是否允许当前客户端/用户的某类操作请求；可选值：**允许**、**拒绝**
-- **操作**：配置该条规则对应的操作；可选值：**发布**、**订阅**、**发布与订阅**
-- **主题**：配置该条规则对应的主题
+规则按从上到下的顺序依次执行，顺序会影响优先级。
 
-EMQX 支持针对单个客户端或用户配置多条授权检查规则，您可通过页面的 **上移**、**下移** 调整不同规则的执行顺序和优先级。
+#### 编辑和管理规则
 
-如希望同时针对多个客户端或用户配置授权检查规则，可通过 HTTP API 传入相关配置。
+在**权限管理**页面，您可以对已有规则进行编辑或删除：
 
-### 通过 API 配置
+- 点击对应规则**操作**列中的**编辑**按钮可修改规则字段、匹配模式或 IP 范围等设置。
+- 点击**删除**按钮可移除规则。
 
-您可通过 REST API 传入以及管理授权规则：
+### 通过 REST API 创建授权检查规则
 
-- 指定适用此条规则的客户端：
-  - `/api/v5/authorization/sources/built_in_database/clientid`
-- 指定适用此条规则的用户名：
-  - `/api/v5/authorization/sources/built_in_database/username`
-- 指定适用此条规则的主题：
-  - `/api/v5/authorization/sources/built_in_database/all`
+您也可以通过 `/api/v5/authorization/sources/built_in_database` 系列 API 接口管理规则。
 
+每条规则可以应用于：
+
+- 按客户端 ID指定的客户端
+   `/api/v5/authorization/sources/built_in_database/clientid`
+- 按用户名指定的客户端
+   `/api/v5/authorization/sources/built_in_database/username`
+- 所有客户端
+   `/api/v5/authorization/sources/built_in_database/all`
+
+#### 使用正则表达式和 IP 地址范围
+
+除了精确匹配客户端 ID 或用户名外，您还可以使用正则表达式或 IP 地址范围为一组客户端定义规则。您可以为具有相同命名模式或处于相同网络位置的多个客户端应用相同 ACL，避免重复多次创建规则。
+
+为此新增了两个字段：
+
+| 字段            | 说明                                                         |
+| --------------- | ------------------------------------------------------------ |
+| **scope**       | 规则的匹配类型。可选值：`all`（默认）、`clientid_re`（客户端 ID 表达式）、`username_re`（用户名表达式）、`ipaddress`（IP 或 CIDR）。 |
+| **scope_value** | 根据 `scope` 类型匹配的值。对于正则表达式，填写正则表达式（例如：`^emqx-.*`）；对于 `ipaddress`，填写精确 IP 或 CIDR 表示法（例如：`192.168.1.0/24`）。 |
 
 比如您可通过如下代码针对 `client1` 客户端创建授权规则：
 
@@ -88,21 +156,23 @@ curl -X 'POST' \
   -d '[
   {
     "clientid": "client1",
+    "scope": "username_re",
+    "scope_value": "^emqx-.*",
     "rules": [
       {
-        "action": "publish",
         "permission": "allow",
-        "topic": "test/topic/1"
+        "action": "publish",
+        "topic": "v1/devices/#"
       },
       {
-        "action": "subscribe",
-        "permission": "allow",
-        "topic": "test/topic/2"
+        "permission": "deny",
+        "action": "all",
+        "topic": "v1/#"
       },
       {
-        "action": "all",
-        "permission": "deny",
-        "topic": "eq test/#"
+        "permission": "allow",
+        "action": "subscribe",
+        "topic": "v1/devices/+/robot_state"
       }
     ]
   }
@@ -111,6 +181,9 @@ curl -X 'POST' \
 
 每条规则应包括如下信息：
 
+- `clientid`：该规则配置所适用的精确客户端 ID。
+- `scope`：额外的匹配过滤条件。`scope = "username_re"` 且 `scope_value = "^emqx-.*"` 表示这些规则仅适用于**该客户端**下用户名以 `emqx-` 开头的连接。
+
 - `permission`：是否允许当前客户端/用户的某类操作请求；可选值：`allow`、`deny`。
 - `action`：配置该条规则对应的操作；可选值: `publish`、`subscribe`、 `all`。
 - `topic`：配置该条规则对应的主题，支持[主题占位符](authz.md#主题占位符)。