Merge pull request #3244 from zmstone/251114-add-new-acl-config-include_mountpoint

docs: add new config doc for authorization (include_mountpoint)

Author: zmstone

en_US/multi-tenancy/namespace-overview.md

@@ -41,21 +41,21 @@ Namespaces are identified by a special client attribute `tns` (tenant namespace)
   Namespaces provide a clean boundary for collecting metrics such as connection count and message throughput per tenant, essential for capacity planning and operational insight.
 
 - **Admin User Isolation**
-   
+  
   Starting from EMQX 6.0, namespaces are extended to Dashboard, CLI, and API users through [namespaced roles](../dashboard/system.md/#namespaced-roles).
 
   - Admin users can be created with roles restricted to a specific namespace, e.g., `ns:team_a::administrator`.
   - Namespaced users only see and operate on resources within their assigned namespace.
    - Cluster-level configurations not yet namespace-aware are visible but read-only for namespaced users, and only modifiable by global administrators.
    - This ensures secure, tenant-specific administrative access alongside data isolation.
-   
+  
 - **Multi-Tenant Management**
 
   System administrators can manage multiple namespaces within the same cluster, while each tenant operates in a self-contained environment with isolated resources and user permissions.
 
 ### Isolation Mechanisms
 
-EMQX offers high flexibility and has supported various isolation methods even before the namespace feature. The namespace feature provides a unified tenant identifier field (`client_attrs.tns`), allowing configurations like client ID and topic mount points to be organized and managed around unified tenant information.
+EMQX offers high flexibility and has supported various isolation methods even before the namespace feature. The namespace feature provides a unified tenant identifier field (`client_attrs.tns`), allowing configurations like client ID and topic mountpoints to be organized and managed around unified tenant information.
 
 However, note that isolation strategies still require **manual configuration** by users based on business needs; the system will not automatically enable client ID or topic isolation features.
 
@@ -69,17 +69,17 @@ However, note that isolation strategies still require **manual configuration** b
 
 ​       This rule adds the namespace as a prefix to the client ID to avoid conflicts.
 
-- **Topic Isolation Using Mount Points**
+- **Topic Isolation Using Mountpoints**
 
-  If clients in different namespaces need to publish or subscribe to the same topic names without affecting each other, you can use mount points to automatically add namespace prefixes:
+  If clients in different namespaces need to publish or subscribe to the same topic names without affecting each other, you can use mountpoints to automatically add namespace prefixes:
 
   ```
   listener.{TYPE}.{NAME}.mountpoint = "${client_attrs.tns}/"
   ```
 
   This setting adds a namespace prefix to the topic name.
 
-As of version 5.9, namespaces are only applicable to MQTT clients. The Dashboard and REST API are not yet isolated based on namespaces. EMQX plans to implement unified management namespaces and MQTT namespaces in future versions. For details, see the [Multi-Tenancy Roadmap](#multi-tenancy-roadmap).
+  For backward compatibility, the Authorization (ACL) checks do **NOT** include the mountpoint prefix by default. Starting from EMQX 6.1, you can set `authorization.include_mountpoint=true` to allow authorization backends to receive topics with a mountpoint prefix.
 
 ## Enable Namespaces
 
@@ -109,11 +109,11 @@ You can also enable namespaces using the EMQX Dashboard:
 
 The following features are being rolled out progressively:
 
-- Unify management namespaces and MQTT namespaces.
-- Implement isolation for built-in database authentication.
-- Implement isolation for built-in database authorization.
+- Unify management namespaces and MQTT namespaces. (6.0)
+- Implement isolation for built-in database authentication. (6.1)
+- Implement isolation for built-in database authorization. (6.1)
+- Implement isolation for Prometheus metrics. (6.1)
 - Implement quota isolation for retained messages.
-- Implement isolation for Prometheus metrics.
 
 ::: tip Update
 

en_US/multi-tenancy/namespace-quick-start.md

@@ -1,6 +1,6 @@
 # Quick Start: Experience Namespaces
 
-This section guides you through using the [MQTTX client](https://mqttx.app) to connect to EMQX and quickly experience the core capabilities of the namespace feature: tenant identification, client isolation, and topic isolation.
+This section guides you through using the [MQTTX client](https://mqttx.app) to connect to EMQX and quickly experience the core capabilities of the namespace feature: tenant identification, client and topic isolation, and ACL isolation.
 
 ## Enable the `tns` Attribute for Namespace Identification
 
@@ -68,4 +68,28 @@ This section guides you through using the [MQTTX client](https://mqttx.app) to c
    - Even though both clients use the same topic (`test/topic`), Client A will **not receive** messages published by Client B because they are isolated by namespace.
    - In the **Monitoring** -> **Clients** page:
      - Client A's subscribed topic appears as `tenantA/test/topic`.
-     - Client B's published topic appears as `tenantB/test/topic`.
+     - Client B's published topic appears as `tenantB/test/topic`.
+
+## Enable Mountpoint-Based ACL Checks
+
+By default, authorization (ACL) checks do not include the mountpoint prefix to preserve backward compatibility. This means that ACL rules are evaluated against the original topic name (e.g., `test/topic`) rather than the namespaced topic (e.g., `tenantA/test/topic`).
+
+Starting from EMQX 6.1, you can enable mountpoint-aware authorization to achieve namespace-level ACL isolation.
+
+To enable this feature, add the following configuration to `base.hocon`:
+
+```hocon
+authorization.include_mountpoint = true
+```
+
+Alternatively, enable it in the Dashboard:
+
+1. Navigate to **Access Control** -> **Authorization** -> **Settings**.
+2. Enable **Include Mountpoint in Authorization Check**.
+3. Click **Save Changes**.
+
+::: tip Note
+
+When `authorization.include_mountpoint=true` is enabled, all ACL rules must include the mountpoint in the topic pattern. For example, if a client connects to a listener with mountpoint `tenantA/` wants to subscribe to `test/topic`, the corresponding ACL rule must be configured as `tenantA/test/topic`.
+
+:::

zh_CN/multi-tenancy/namespace-overview.md

@@ -36,7 +36,7 @@
 
 - **管理员用户隔离**
 
-  从 EMQX 6.0 起，命名空间机制也扩展到了 Dashboard、CLI 与 API 层面的用户管理，通过[命名空间角色](../dashboard/system.md/#命名空间角色) 实现租户级权限控制：
+  从 EMQX 6.0 起，命名空间机制也扩展到了 Dashboard、CLI 与 API 层面的用户管理，通过[命名空间角色](../dashboard/system.md/#命名空间角色)实现租户级权限控制：
 
   - 管理员用户可被指定为仅限访问特定命名空间的角色，例如：`ns:team_a::administrator`。
   - 命名空间用户仅能查看与操作其所属命名空间内的资源。
@@ -62,8 +62,8 @@ EMQX 拥有极高的灵活性，在命名空间功能实现之前，就已支持
   若不同命名空间的客户端需要发布或订阅相同的主题名称，而又不希望互相影响，可使用挂载点自动添加命名空间前缀：
 
   `listener.{TYPE}.{NAME}.mountpoint="${client_attrs.tns}/"`，该设置会为主题名称添加命名空间前缀。
-
-截至 5.9 版本，命名空间仅适用于 MQTT 客户端，Dashboard 和 REST API 尚未基于命名空间进行隔离。EMQX 计划在未来版本中实现统一的管理命名空间与 MQTT 命名空间，详情请参见[多租户功能路线图](#multi-tenancy-roadmap)。
+  
+  为保持向后兼容性，默认情况下授权（ACL）检查**不会**包含挂载点前缀。从 EMQX 6.1 开始，你可以通过设置 `authorization.include_mountpoint=true`，让授权后端能够接收到带有挂载点前缀的主题。
 
 ## 启用命名空间
 
@@ -93,11 +93,11 @@ mqtt.client_attrs_init = [{expression = username, set_as_attr = tns}]
 
 以下多租户相关特性正在逐步推出：
 
-- 将管理命名空间与 MQTT 命名空间统一。
-- 实现内置数据库身份认证的隔离。
-- 实现内置数据库权限认证的隔离。
+- 将管理命名空间与 MQTT 命名空间统一。（6.0）
+- 实现内置数据库身份认证的隔离。（6.1）
+- 实现内置数据库权限认证的隔离。（6.1）
+- 实现 Prometheus 指标的隔离。（6.1）
 - 实现保留消息配额的隔离。
-- 实现 Prometheus 指标的隔离。
 
 ::: tip 更新提示
 

zh_CN/multi-tenancy/namespace-quick-start.md

@@ -1,6 +1,6 @@
 # 快速体验命名空间功能
 
-本节将引导您使用 [MQTTX 客户端](https://mqttx.app/zh)连接 EMQX，并快速体验命名空间功能的关键能力：租户识别、客户端隔离与主题隔离。
+本节将引导您使用 [MQTTX 客户端](https://mqttx.app/zh)连接 EMQX，并快速体验命名空间功能的关键能力：租户识别、客户端与主题隔离，和 ACL 隔离。
 
 ## 启用 `tns` 属性作为命名空间识别字段
 
@@ -36,7 +36,7 @@
    上述配置会：
 
    - 自动为客户端 ID 添加租户前缀，避免冲突；
-   - 自动为主题添加挂载点，实现租户间的主题隔离。
+   - 自动为主题添加主题前缀，实现租户间的主题隔离。
 
    或者，您也可以在 Dashboard 中进行设置：
 
@@ -72,4 +72,28 @@
 
      - 客户端 A 的订阅主题变为 `tenantA/test/topic`。
 
-     - 客户端 B 的发布主题变为 `tenantB/test/topic`。
+     - 客户端 B 的发布主题变为 `tenantB/test/topic`。
+
+## 启用基于主题前缀的授权检查
+
+默认情况下，为保持向后兼容性，授权（ACL）检查不会包含主题前缀（mountpoint）。这意味着授权规则会根据原始主题名称（例如 `test/topic`）进行匹配，而不是带命名空间的主题名称（例如 `tenantA/test/topic`）。
+
+从 EMQX 6.1 开始，您可以启用基于主题前缀的授权检查，以实现命名空间级别的 ACL 隔离。
+
+要启用此功能，可以在 `base.hocon` 中添加以下配置：
+
+```hocon
+authorization.include_mountpoint = true
+```
+
+您也可以在 Dashboard 中启用该功能：
+
+1. 导航至**访问控制** -> **客户端授权** -> **设置**。
+2. 启用**包含主题前缀的授权检查**。
+3. 点击**保存**。
+
+::: tip 注意
+
+当启用 `authorization.include_mountpoint=true` 时，所有授权规则都必须在主题匹配模式中包含主题前缀。例如，如果客户端通过带有主题前缀 `tenantA/` 的监听器连接并希望订阅 `test/topic`，对应的授权规则应配置为 `tenantA/test/topic`。
+
+:::