# 使用 MySQL 进行密码认证

作为密码认证方式的一种,EMQX 支持通过集成 MySQL 进行密码认证。

提示

前置准备:

# SQL 表结构与查询语句

MySQL 认证器可以支持任何表结构,甚至是多个表联合查询、或从视图中查询。用户需要提供一个查询 SQL 模板,且确保查询结果包含以下字段:

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

示例表结构:

CREATE TABLE `mqtt_user` (
  `id` int(11) unsigned NOT NULL AUTO_INCREMENT,
  `username` varchar(100) DEFAULT NULL,
  `password_hash` varchar(100) DEFAULT NULL,
  `salt` varchar(35) DEFAULT NULL,
  `is_superuser` tinyint(1) DEFAULT 0,
  `created` datetime DEFAULT NULL,
  PRIMARY KEY (`id`),
  UNIQUE KEY `mqtt_username` (`username`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
1
2
3
4
5
6
7
8
9
10

提示

上面的示例创建了一个隐式的 UNIQUE 索引,当系统中有大量用户时,请确保查询使用的表已优化并使用有效的索引,以提升大量连接时的数据查找速度并降低 EMQX 负载。

在此表中使用 username 作为查找条件。

添加用户名为 emqx_u、密码为 public、盐值为 slat_foo123、散列方式为 sha256 且超级用户标志为 true 的用户示例:

mysql> INSERT INTO mqtt_user(username, password_hash, salt, is_superuser) VALUES ('emqx_u', SHA2(concat('public', 'slat_foo123'), 256), 'slat_foo123', 1);
Query OK, 1 row affected (0,01 sec)
1
2

对应的查询语句和密码散列方法配置参数为:

  • 密码加密方式:sha256
  • 加盐方式:suffix
  • SQL:
SELECT password_hash, salt, is_superuser FROM mqtt_user WHERE username = ${username} LIMIT 1
1

# 通过 Dashboard 配置

EMQX Dashboard (opens new window)页面,点击左侧导航栏的访问控制 -> 认证,在随即打开的认证页面,单击创建,依次选择认证方式Password-Based数据源MySQL,进入配置参数页签:

use-mysql-to-authenticate

您可按照如下说明完成相关配置:

**连接:**在此部分完成到 MySQL 数据库的连接设置。

  • 服务:填入 MySQL 服务器地址 (host:port) 。
  • 数据库:填入 MySQL 的数据库名称。
  • 用户名(可选):填入用户名称。
  • 密码(可选):填入用户密码。

TLS 配置:配置是否启用 TLS。

连接配置:在此部分设置并发连接、是否自动重连以及连接超时等待时间。

  • Pool size(可选):填入一个整数用于指定从 EMQX 节点到 MySQL 数据库的并发连接数;默认值:8
  • 自动重连:指定连接中断时 EMQX 是否自动重新连接到 MySQL;可选值:True(自动重连),False(不自动重连);默认值:True
  • 查询超时:填入连接超时等待时长,可选单位:小时分钟毫秒

认证配置:在此部分进行认证加密算法相关的配置。

  • 密码加密方式:选择存储密码时使用的散列算法,如 plain、md5、sha、bcrypt、pbkdf2 等。

    • 选择 plainmd5shasha256sha512 算法,需配置:

      • 加盐方式:用于指定盐和密码的组合方式,除需将访问凭据从外部存储迁移到 EMQX 内置数据库中外,一般不需要更改此选项;可选值:suffix(在密码尾部加盐)、prefix(在密码头部加盐)、disable(不启用)。注意:如选择 plain,加盐方式应设为 disable
    • 选择 bcrypt 算法,无需额外配置。

    • 选择 pkbdf2 算法,需配置:

      • 伪随机函数:指定生成密钥使用的散列函数,如 sha256 等。
      • 迭代次数:指定散列次数,默认值:4096
      • 密钥长度(可选):指定希望得到的密钥长度。如不指定,密钥长度将由伪随机函数确定。
  • SQL:根据表结构填入查询 SQL,具体要求见 SQL 表结构与查询语句