EMQX Platform 文档

简体中文

English

简体中文

English

Appearance

联系我们

JWT 认证 ​

JWT 认证是基于 Token 的鉴权机制，不依赖服务端保留客户端的认证信息或者会话信息，在持有密钥的情况下可以批量签发认证信息，是最简便的认证方式。

JWT 认证原理 ​

客户端使用用户名或密码字段携带 JWT（取决于模块配置），发起连接时 EMQX Platform 使用配置中的密钥、证书进行解密，如果能成功解密则认证成功，否则认证失败。

如果签名验证成功，JWT 认证器将继续检查声明。JWT 认证器会根据这些声明如 iat（签发时间）、nbf（不早于）和 exp（过期时间）来主动检查 JWT 的有效性。还可以指定额外的自定义声明进行认证。只有当签名和声明的认证都成功时，客户端才被授权访问。

默认配置下启用 JWT 认证后，你可以通过任意用户名+以下密码进行连接，即通过默认的密钥字段 secret 做验证：

bash
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkVNUVggQ2xvdWQiLCJpYXQiOjE1MTYyMzkwMjJ9.wGxZTwkCZtYPzkS854aQ9WCnP8YGIQ_erFh5RIznhYk

上述 JWT Token 仅做测试使用，可根据自己的业务需求用相关工具生成。此处提供一个在线生成工具：https://www.jsonwebtoken.io/ ，也可以结合 JSON Web 密钥 (JWK) 生成器：https://mkjwk.org 进行测试。

权限列表 ​

如果 JWT 中包含 acl 字段，EMQX 将根据该字段指定的权限对客户端进行访问控制。 详情请参考权限列表（ACL）。

客户端属性 ​

从 EMQX v5.7.0 版本开始，您可以在 JWT Payload 中使用可选的 client_attrs 字段设置客户端属性。请注意，键和值都必须是字符串类型。

示例：

json
{
  "exp": 1654254601,
  "username": "emqx_u",
  "client_attrs": {
      "role": "admin",
      "sn": "10c61f1a1f47"
  }
}

认证配置 ​

在部署中点击 访问控制 -> 客户端认证 -> 扩展认证，选择 JWT 认证，点击配置认证。

您可根据如下说明完成相关配置：

如验证方式选择 JWT 时：

  • JWT 来自于：指定客户端连接请求中 JWT 的位置；可选值： password、 username（分别对应于 MQTT 客户端 CONNECT 报文中的 Password 和 Username 字段）

  • 加密方式：指定 JWT 的加密方式，可选值： hmac-based、public-key；

    • 如选择 hmac-based，即 JWT 使用对称密钥生成签名和校验签名（支持 HS256、HS384 和 HS512 算法），还应配置：

      • Secret：用于校验签名的密钥，与生成签名时使用的密钥相同。
      • Secret 使用 Base64 编码：配置 EMQX 在使用 Secret 校验签名时是否需要先对其进行 Base64 解密；可选值：True、False，默认值：False。

    • 如选择 public-key，即 JWT 使用私钥生成签名，同时需要使用公钥校验签名（支持 RS256、RS384、RS512、ES256、ES384 和 ES512 算法），还应配置：

      • Public Key：指定用于校验签名的 PEM 格式的公钥。

  • 过期后断开连接：配置是否在 JWT 过期后断开客户端连接，默认启用。

  • Payload：添加自定义的 Claims 检查；用户需要在 Claim 和 Expected Value 分别添加键和对应的值，支持使用 ${clientid} 和 ${username} 占位符。其中键用于查找 JWT 中对应的 Claim，值则用于与 Claim 的实际值进行比较。

如验证方式选择 JWTS：

除上述配置外，还应配置：

  • JWKS Endpoint：指定 EMQX 查询 JWKS 的服务器端点地址，该端点需要支持 GET 请求，并且返回符合规范的 JWKS。
  • JWKS 刷新间隔：指定 JWKS 的刷新间隔，也就是 EMQX 查询 JWKS 的间隔。默认值：300 单位为秒（s）。 点击创建完成相关配置。
  • 请求头：指定必须包含在对 JWKS 服务器请求中的任何其他 HTTP 请求头。添加这些 HTTP 请求头可以确保对 JWKS 服务器的请求根据服务器的要求进行正确格式化。此配置允许用户添加键值对，例如：
    • 键：Accept
    • 值：application/json

TIP

  • 如果当前部署为专有版，需创建 VPC 对等连接，服务器地址填写内网地址。
  • 如果当前部署为 BYOC 版，需在您的公有云控制台中创建 VPC 对等连接，具体请参考创建 BYOC 部署 - VPC 对等连接配置 章节。服务器地址填写内网地址。
  • 若提示 Init resource failure! 请检查服务器地址是否无误、安全组是否开启。