Merge pull request #3215 from emqx/20251022-redis-auhn-update

fix(Redis authn&authz): Add `username` field

Author: zmstone

en_US/access-control/authn/assets/authn-redis.png

@@ -1,6 +1,6 @@
 # Integrate with Redis
 
-EMQX supports integrating with Redis for password authentication. EMQX Redis authenticator currently supports connecting to running in three different modes, which are Single, [Redis Sentinel](https://redis.io/docs/manual/sentinel/) and [Redis Cluster](https://redis.io/docs/manual/scaling/). This section gives detailed instructions on the data schema supported and on how to configure with EMQX Dashboard and configuration file. 
+EMQX supports integrating with Redis for password authentication. EMQX Redis authenticator currently supports connecting to Redis running in three different modes, which are Single, [Redis Sentinel](https://redis.io/docs/manual/sentinel/), and [Redis Cluster](https://redis.io/docs/manual/scaling/). This section gives detailed instructions on the data schema supported and on how to configure with EMQX Dashboard and the configuration file. 
 
 ::: tip Prerequisite:
 
@@ -54,10 +54,26 @@ Follow the instructions below on how to configure the authentication:
 **Connect**: Enter the information for connecting to Redis.
 
 - **Redis Mode**: Select how Redis is deployed, including `Single`, `Sentinel` and `Cluster`. 
+
 - **Server(s)**: Specify the Redis server address that EMQX is to connect, if **Redis Mode** is set to `Sentinel` or `Cluster`, you will need to input all Redis servers (separated with a `,`) that EMQX is to connect.
+
 - **Sentinel Name**: Specify the name to use; type: strings; only needed if you set **Redis Mode** to `Sentinel`.
+
 - **Database**: Redis database name; Data type: strings.
-- **Password**: Specify Redis user password. 
+
+- **Username**: Specify the Redis username to connect with. This field is required if your Redis instance uses [Redis ACL](https://redis.io/docs/latest/operate/oss_and_stack/management/security/acl/#create-and-edit-user-acls-with-the-acl-setuser-command) (introduced in Redis 6.0) for authentication. If your Redis server uses the default user (with ACLs disabled or not enforced), you can leave this field blank.
+
+  ::: tip
+
+  The `username` field is supported starting from EMQX 5.2.0. Ensure your deployment is running this version or later to use Redis ACL.
+
+  :::
+
+- **Password**: Specify the password for the Redis user. The field is required for connecting to Redis instances with authentication enabled.
+
+  - If you have entered a username, this password must match the credentials configured in your Redis ACL settings.
+  - If no username is provided, this password will be used to authenticate as the `default` user (if enabled).
+
 
 **TLS Configuration**: Turn on the toggle switch if you want to enable TLS. For more information on enabling TLS, see [Network and TLS](../../network/overview.md).
 

en_US/access-control/authn/redis.md

@@ -55,31 +55,36 @@ All rules added in Redis Authorizer are **allow** rules, which means Redis Autho
 
 You can use EMQX Dashboard to configure how to use Redis for user authorization.
 
-1. On [EMQX Dashboard](http://127.0.0.1:18083/#/authentication), click **Access Control** -> **Authorization** on the left navigation tree to enter the **Authorization** page. 
+1. On the EMQX Dashboard, click **Access Control** -> **Authorization** on the left navigation tree to enter the **Authorization** page. 
 
 2. Click **Create** at the top right corner, then click to select **Redis** as **Backend**. Click **Next**. The **Configuration** tab is shown as below.
 
-   <img src="./assets/authz-Redis_ee.png" alt="authz-Redis_ee" style="zoom:67%;" />
+   <img src="./assets/authz-redis.png" alt="authz-Redis_ee" style="zoom:67%;" />
 
-3. Follow the instructions below to do the configuration.
+3. Follow the instructions below to configure the settings.
 
-   **Connect**: Fill in the information needed to connect Redis.
-
-   - **Redis Mode**: Select how Redis is deployed, including **Single**, **Sentinel** and **Cluster**.
+   - **Redis Mode**: Select how Redis is deployed, including `Single`, `Sentinel` and `Cluster`.
    - **Server**: Specify the server address that EMQX is to connect (`host:port`).
    - **Database**: Redis database name.
-   - **Password**: Specify user password. 
+   - **Username**: Specify the Redis username to connect with. This field is required if your Redis instance uses [Redis ACL](https://redis.io/docs/latest/operate/oss_and_stack/management/security/acl/#create-and-edit-user-acls-with-the-acl-setuser-command) (introduced in Redis 6.0) for authentication. If your Redis server uses the default user (with ACLs disabled or not enforced), you can leave this field blank.
+
+     ::: tip
 
-   **TLS Configuration**: Turn on the toggle switch if you want to enable TLS. 
+     The `username` field is supported starting from EMQX 5.2.0. Ensure your deployment is running this version or later to use Redis ACL.
 
-   **Connection Configuration**: Set the concurrent connections and waiting time before a connection is timed out.
+     :::
+   - **Password**: Specify the password for the Redis user. The field is required for connecting to Redis instances with authentication enabled.
 
-   - **Pool size** (optional): Input an integer value to define the number of concurrent connections from an EMQX node to Redis. Default: **8**. 
+     - If you have entered a username, this password must match the credentials configured in your Redis ACL settings.
+     - If no username is provided, this password will be used to authenticate as the `default` user (if enabled).
 
-   **Authorization configuration**: Fill in the authorization-related settings:
+   - **Enable TLS**: Turn on the toggle switch if you want to enable TLS. 
 
    - **CMD**: Fill in the query command according to the data schema.
 
+   - **Advanced Settings**: Set the concurrent connections and waiting time before a connection is timed out.
+     - **Pool size** (optional): Input an integer value to define the number of concurrent connections from an EMQX node to Redis. Default: `8`. 
+
 4. Click **Create** to finish the settings.
 
 ## Configure with Configuration Items

en_US/access-control/authz/assets/authz-Redis_ee.png

@@ -45,11 +45,26 @@ Redis 认证器支持使用 [Redis hashes](https://redis.io/docs/manual/data-typ
 
 **连接**：在此部分完成到 Redis 数据库的连接设置。
 
-- **部署模式**：选择 Redis 数据库的部署模式，可选值：**单节点**、**Sentinel**、**Cluster**
-- **服务**（**列表**）：填入 Redis 服务器地址 (`host:port`) ；当部署模式选为 Sentinel 或 Cluster，您需在此提供所有相关 Redis 服务器的地址，不同地址之间以 `,` 分隔，格式为 `host1:port1,host2:port2,...`
-- **Sentinel 名字**：指定 Redis Sentinel 配置需要的[主服务器名称](https://redis.io/docs/manual/sentinel/#configuring-sentinel)，仅需在**部署模式**设置为 **Sentinel** 时设置。
+- **部署模式**：选择 Redis 数据库的部署模式，可选值：**单节点**、**Sentinel**、**Cluster**。
+
+- **服务器地址**：填入 Redis 服务器地址 (`host:port`) ；当部署模式选为 Sentinel 或 Cluster，您需在此提供所有相关 Redis 服务器的地址，不同地址之间以 `,` 分隔，格式为 `host1:port1,host2:port2,...`。
+
+- **Sentinel 名字**（仅需在**部署模式**设置为 **Sentinel** 时设置）：指定 Redis Sentinel 配置需要的[主服务器名称](https://redis.io/docs/manual/sentinel/#configuring-sentinel)。
+
 - **数据库**：整数，用于指定 Redis 数据库的 Index。
-- **密码**：填入认证密码。
+
+- **用户名**：指定用于连接 Redis 的用户名。如果您的 Redis 实例启用了 [Redis ACL](https://redis.io/docs/latest/operate/oss_and_stack/management/security/acl/#create-and-edit-user-acls-with-the-acl-setuser-command)（在 Redis 6.0 引入）进行身份验证，则此字段为必填项。如果您的 Redis 使用默认用户（未启用或未强制使用 ACL），则可以留空此字段。
+
+  ::: tip 提示
+
+  `username` 字段从 EMQX 5.2.0 版本开始支持。请确保您的部署版本为 5.2.0 或更高，以使用 Redis ACL 功能。
+
+  :::
+
+- **密码**：指定用于连接 Redis 的用户密码。若 Redis 实例启用了身份验证，该字段为必填项。
+
+  - 如果填写了用户名，则此密码必须与 Redis ACL 配置中的凭据匹配。
+  - 如果未填写用户名，则此密码将用于以 Redis 的 `default` 用户身份进行身份验证（前提是默认用户已启用）。
 
 **TLS 配置**：配置是否启用 TLS。
 
@@ -72,7 +87,7 @@ Redis 认证器支持使用 [Redis hashes](https://redis.io/docs/manual/data-typ
     - **迭代次数**：指定散列次数，默认值：`4096`。<!--后续补充取值范围-->
     - **密钥长度**（可选）：指定希望得到的密钥长度。如不指定，密钥长度将由**伪随机函数**确定。
     - 生成的哈希值以十六进制字符串表示，并与存储的凭据进行不区分大小写的比对。
-- **命令**：Redis 查询命令
+- **命令**：Redis 查询命令。
 
 点击**创建**完成相关配置。
 

en_US/access-control/authz/assets/authz-redis.png

@@ -46,7 +46,47 @@ cmd = "HGETALL mqtt_acl:${username}"
 Redis Authorizer 中添加的所有规则都是**允许**规则，即 Redis Authorizer 需要在白名单模式下使用。
 :::
 
-## 配置项
+## 通过 Dashboard 配置
+
+你可以通过 EMQX Dashboard 配置 Redis 作为用户授权的后端。
+
+1. 在 EMQX Dashboard 中，点击左侧导航栏的**访问控制** -> **客户端权限**，进入**客户端权限控制** 页面。
+
+2. 点击右上角的**创建**按钮，在弹出的对话框中选择 **Redis** 作为**数据源**，然后点击 **下一步**，进入**配置参数**页，如下图所示：
+
+   <img src="./assets/authz-redis.png" alt="authz-Redis_ee" style="zoom:67%;" />
+
+3. 按照以下说明完成配置：
+
+   - **Redis 模式**：选择 Redis 的部署模式，包括`单节点`、`Sentinel` 和`Cluster`。
+
+   - **服务器地址**：输入 Redis 服务器的地址（格式为 `host:port`），EMQX 将连接该地址。
+
+   - **数据库**：填写 Redis 的数据库编号或名称。
+
+   - **用户名**：指定用于连接 Redis 的用户名。如果您的 Redis 实例启用了 [Redis ACL](https://redis.io/docs/latest/operate/oss_and_stack/management/security/acl/#create-and-edit-user-acls-with-the-acl-setuser-command)（在 Redis 6.0 引入），则此字段为必填项。如果您的 Redis 使用默认用户（未启用或未强制启用 ACL），则可以留空此字段。
+
+     ::: tip 提示
+
+     `username` 字段从 EMQX 5.2.0 版本开始支持。请确保您的部署版本为 5.2.0 或更高版本，以支持 Redis ACL。
+
+     :::
+
+   - **密码**：指定用于连接 Redis 用户的密码。若 Redis 实例启用了身份认证，该字段为必填项。
+
+     - 如果填写了用户名，则密码必须与 Redis ACL 中该用户配置的凭据一致。
+     - 如果未填写用户名，则将使用该密码尝试以 `default` 用户身份进行身份认证（前提是该用户未被禁用）。
+   
+   - **启用 TLS**：如果需要启用 TLS，加上开关即可开启。有关 TLS 配置的更多信息，请参阅[网络与 TLS](../../network/overview.md)。
+
+   - **命令**：根据数据结构填写 Redis 查询命令。
+
+   - **高级设置**：设置连接池大小和连接超时时间。
+     - **连接池大小**（可选）：输入一个整数，表示每个 EMQX 节点与 Redis 建立的并发连接数量。默认值为 `8`。
+   
+4. 完成配置后，点击 **创建** 保存设置。
+
+## 使用配置项配置
 
 Redis authorizer 由 `type=redis` 标识。<!--详细配置请参考 [redis_standalone](../../configuration/configuration-manual.html#authz:redis_standalone)、[authz:redis_sentinel](../../configuration/configuration-manual.html#authz:redis_sentinel) 与 [authz:redis_cluster](../../configuration/configuration-manual.html#authz:redis_cluster)。-->