EMQX 企业版

简体中文

English
日本語

简体中文

English
日本語

Appearance

联系我们

使用 Redis 进行密码认证 ​

作为密码认证方式的一种，EMQX 支持通过集成 Redis 进行密码认证。EMQX 支持三种 Redis 部署模式：单节点、Redis Sentinel、Redis Cluster，本节将介绍如何进行相关配置。

前置准备

熟悉 EMQX 认证基本概念

数据结构与查询指令 ​

Redis 认证器支持使用 Redis hashes 存储认证数据，用户需要提供一个查询指令模板，且确保查询结果包含以下字段：

  • password_hash: 必需，数据库中的明文或散列密码字段
  • salt: 可选，为空或不存在时视为空盐（salt = ""）
  • is_superuser: 可选，标记当前客户端是否为超级用户，默认为 false

例如，您希望添加一位名用户名为 emqx_u、密码为 public、盐值为 salt_foo123、散列方式为 sha256 且超级用户标志为 true 的用户：

bash
>redis-cli
127.0.0.1:6379> HSET mqtt_user:emqx_u is_superuser 1 salt slat_foo123 password_hash 44edc2d57cde8d79c98145003e105b90a14f1460b79186ea9cfe83942fc5abb5
(integer) 0

对应的配置参数为：

  • 密码加密方式：sha256
  • 加盐方式：suffix
  • 命令：HMGET mqtt_user:${username} password_hash salt is_superuser

TIP

password_hash 这一字段名称直观表明用户应当在数据库中存储散列密码。但鉴于 Redis 没有类似 MySQL 的 as 语法，我们保留了 4.x 对 password 的兼容。

所以，您也可以将 cmd 配置为 HMGET mqtt_user:${username} password salt is_superuser。

通过 Dashboard 配置 ​

  1. 在 EMQX Dashboard 页面上点击左侧导航栏的访问控制 -> 客户端认证
  2. 在客户端认证页面，点击**+ 创建**。
  3. 依次选择认证方式为 Password-Based，数据源为 Redis，点击下一步进入配置参数页签：
Authentication with redis

  1. 按照以下说明配置数据源：

    • Redis 数据库的连接设置：

  • 部署模式：选择 Redis 数据库的部署模式，可选值：单节点、Sentinel、Cluster。

  • 服务器地址：填入 Redis 服务器地址 (host:port) ；当部署模式选为 Sentinel 或 Cluster，您需在此提供所有相关 Redis 服务器的地址，不同地址之间以 , 分隔，格式为 host1:port1,host2:port2,...。

  • Sentinel 名字（仅需在部署模式设置为 Sentinel 时设置）：指定 Redis Sentinel 配置需要的主服务器名称。

  • 数据库：整数，用于指定 Redis 数据库的 Index。

  • 用户名：指定用于连接 Redis 的用户名。如果您的 Redis 实例启用了 Redis ACL（在 Redis 6.0 引入）进行身份验证，则此字段为必填项。如果您的 Redis 使用默认用户（未启用或未强制使用 ACL），则可以留空此字段。

    提示

    username 字段从 EMQX 5.2.0 版本开始支持。请确保您的部署版本为 5.2.0 或更高，以使用 Redis ACL 功能。

  • 密码：指定用于连接 Redis 的用户密码。若 Redis 实例启用了身份验证，该字段为必填项。

    • 如果填写了用户名，则此密码必须与 Redis ACL 配置中的凭据匹配。

    • 如果未填写用户名，则此密码将用于以 Redis 的 default 用户身份进行身份验证（前提是默认用户已启用）。

    • 认证加密算法相关的配置：

      • 密码加密方式：选择应用于明文密码的哈希算法，在将结果存储到数据库之前对密码进行加密。可选算法包括 plain、md5、sha、sha256、sha512、bcrypt 和 pbkdf2。具体配置取决于所选择的算法：
        • 选择 md5、sha、sha256 或 sha512 算法，需配置：
          • 加盐方式：用于指定盐和密码的组合方式，可选值：suffix（在密码尾部加盐）、prefix（在密码头部加盐）、disable（不启用）。如果您不需要将用户凭据从外部存储迁移到 EMQX 内置数据库，可以保持默认值。
          • 生成的哈希值以十六进制字符串表示，并与存储的凭据进行不区分大小写的比对。
        • 选择 plain：
          • 加盐方式：应设置为 disable。
        • 选择 bcrypt 算法，需配置:
          • Salt Rounds：指定散列需要的计算次数（2^Salt Rounds），也称成本因子。默认值：10，可选值：5 到 10；数值越高，加密的安全性越高，因此建议采用较大的值，但相应的用户验证的耗时也会增加，您可根据业务需求进行配置。
        • 选择 pbkdf2 算法，需配置：
          • 伪随机函数：指定生成密钥使用的散列函数，如 sha256 等。
          • 迭代次数：指定散列次数，默认值：4096。
          • 密钥长度（可选）：指定希望得到的密钥长度。如不指定，密钥长度将由伪随机函数确定。
          • 生成的哈希值以十六进制字符串表示，并与存储的凭据进行不区分大小写的比对。

    • 调用条件：一个 Variform 表达式，用于控制是否将此 Redis 认证器应用于客户端连接。该表达式会根据客户端的属性（例如 username、clientid、listener 等）进行评估。如果表达式的结果为字符串 "true"，则会触发认证器。否则，认证器将被跳过。有关调用条件的更多信息，请参见认证器调用条件。

    • 启用 TLS：如果要启用TLS，请打开切换按钮。有关启用 TLS 的更多信息，请参见网络和 TLS。

  • 密码加密方式：选择应用于明文密码的哈希算法，在将结果存储到数据库之前对密码进行加密。可选算法包括 plain、md5、sha、sha256、sha512、bcrypt 和 pbkdf2。具体配置取决于所选择的算法：

    • 选择 md5、sha、sha256 或 sha512 算法，需配置：
      • 加盐方式：用于指定盐和密码的组合方式，可选值：suffix（在密码尾部加盐）、prefix（在密码头部加盐）、disable（不启用）。如果您不需要将用户凭据从外部存储迁移到 EMQX 内置数据库，可以保持默认值。
      • 生成的哈希值以十六进制字符串表示，并与存储的凭据进行不区分大小写的比对。
    • 选择 plain：
      • 加盐值方式：应设置为 disable。
    • 选择 bcrypt 算法，需配置:
      • Salt Rounds：指定散列需要的计算次数（2^Salt Rounds），也称成本因子。默认值：10，可选值：5 到 10；数值越高，加密的安全性越高，因此建议采用较大的值，但相应的用户验证的耗时也会增加，您可根据业务需求进行配置。
    • 选择 pbkdf2 算法，需配置：
      • 伪随机函数：指定生成密钥使用的散列函数，如 sha256 等。
      • 迭代次数：指定散列次数，默认值：4096。
      • 密钥长度（可选）：指定希望得到的密钥长度。如不指定，密钥长度将由伪随机函数确定。
      • 生成的哈希值以十六进制字符串表示，并与存储的凭据进行不区分大小写的比对。

  • 命令：Redis 查询命令。

    • 高级设置：在此部分设置并发连接。
      • 连接池大小（可选）：填入一个整数用于指定从 EMQX 节点到 Redis 数据库的并发连接数；默认值：8。
  1. 点击创建完成相关配置。

通过配置文件配置 ​

您可通过配置文件完成相关配置。

以下为各部署模式下的配置文件示例：