diff --git a/en_US/access-control/authn/assets/authn-redis.png b/en_US/access-control/authn/assets/authn-redis.png index 91e8c0ab0..acc10f3d4 100644 Binary files a/en_US/access-control/authn/assets/authn-redis.png and b/en_US/access-control/authn/assets/authn-redis.png differ diff --git a/en_US/access-control/authn/redis.md b/en_US/access-control/authn/redis.md index 6b20e59d2..3afb2a989 100644 --- a/en_US/access-control/authn/redis.md +++ b/en_US/access-control/authn/redis.md @@ -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). diff --git a/en_US/access-control/authz/assets/authz-Redis_ee.png b/en_US/access-control/authz/assets/authz-Redis_ee.png deleted file mode 100644 index 80eaa215d..000000000 Binary files a/en_US/access-control/authz/assets/authz-Redis_ee.png and /dev/null differ diff --git a/en_US/access-control/authz/assets/authz-redis.png b/en_US/access-control/authz/assets/authz-redis.png new file mode 100644 index 000000000..30970877e Binary files /dev/null and b/en_US/access-control/authz/assets/authz-redis.png differ diff --git a/en_US/access-control/authz/redis.md b/en_US/access-control/authz/redis.md index 5a7358401..1fc2527ad 100644 --- a/en_US/access-control/authz/redis.md +++ b/en_US/access-control/authz/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. - authz-Redis_ee + authz-Redis_ee -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 diff --git a/zh_CN/access-control/authn/assets/authn-redis.png b/zh_CN/access-control/authn/assets/authn-redis.png index f50594db2..c6e1cb401 100644 Binary files a/zh_CN/access-control/authn/assets/authn-redis.png and b/zh_CN/access-control/authn/assets/authn-redis.png differ diff --git a/zh_CN/access-control/authn/redis.md b/zh_CN/access-control/authn/redis.md index a0fd1b1e1..b0850f11f 100644 --- a/zh_CN/access-control/authn/redis.md +++ b/zh_CN/access-control/authn/redis.md @@ -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 查询命令。 点击**创建**完成相关配置。 diff --git a/zh_CN/access-control/authz/assets/authz-redis.png b/zh_CN/access-control/authz/assets/authz-redis.png new file mode 100644 index 000000000..c7d13f65f Binary files /dev/null and b/zh_CN/access-control/authz/assets/authz-redis.png differ diff --git a/zh_CN/access-control/authz/redis.md b/zh_CN/access-control/authz/redis.md index 0fec448f9..7365ff163 100644 --- a/zh_CN/access-control/authz/redis.md +++ b/zh_CN/access-control/authz/redis.md @@ -46,7 +46,47 @@ cmd = "HGETALL mqtt_acl:${username}" Redis Authorizer 中添加的所有规则都是**允许**规则，即 Redis Authorizer 需要在白名单模式下使用。 ::: -## 配置项 +## 通过 Dashboard 配置 + +你可以通过 EMQX Dashboard 配置 Redis 作为用户授权的后端。 + +1. 在 EMQX Dashboard 中，点击左侧导航栏的**访问控制** -> **客户端权限**，进入**客户端权限控制** 页面。 + +2. 点击右上角的**创建**按钮，在弹出的对话框中选择 **Redis** 作为**数据源**，然后点击 **下一步**，进入**配置参数**页，如下图所示： + + authz-Redis_ee + +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` 标识。