JWT 认证

JWTJWT 认证 - 图1 (opens new window) 认证基于 Token 的鉴权机制,不依赖服务端保留客户端的认证信息或者会话信息,在持有密钥的情况下可以批量签发认证信息,是最简便的认证方式。

插件:

  1. emqx_auth_jwt

认证原理

客户端使用 Token 作为用户名或密码(取决于插件配置),发起连接时 EMQ X 使用配置中的密钥、证书进行解密,如果能成功解密则认证成功,否则认证失败。

默认配置下启用 JWT 认证后,你可以通过任意用户名+以下密码进行连接:

  1. eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7ImF1dGhvciI6IndpdndpdiIsInNpdGUiOiJodHRwczovL3dpdndpdi5jb20ifSwiZXhwIjoxNTgyMjU1MzYwNjQyMDAwMCwiaWF0IjoxNTgyMjU1MzYwfQ.FdyAx2fYahm6h3g47m88ttyINzptzKy_speimyUcma4

配置项

要启用 JWT 认证,需要在 etc/plugins/emqx_auth_jwt.conf 中配置以下内容:

  1. # etc/plugins/emqx_auth_jwt.conf
  2. ## 密钥
  3. ##
  4. ## 使用 HMAC 算法校验 Token 的密钥
  5. auth.jwt.secret = emqxsecret
  6. ## RSA 或 ECDSA 公钥文件
  7. ##
  8. ## 使用 RSA 或 ECDSA 算法校验 Token 的公钥
  9. #auth.jwt.pubkey = etc/certs/jwt_public_key.pem
  10. ## JWKs 的服务器地址
  11. ##
  12. ## EMQ X 会从 JWKs 服务器获取密钥列表,并用于验证 Token
  13. ##
  14. ## JWKs 规范见: http://self-issued.info/docs/draft-ietf-jose-json-web-key.html
  15. #auth.jwt.jwks = https://127.0.0.1:8080/jwks
  16. ## JWKs 密钥刷新时间
  17. ##
  18. #auth.jwt.jwks.refresh_interval = 5m
  19. ## 客户端携带 Token 的方式
  20. ##
  21. ## Value: username | password
  22. auth.jwt.from = password
  23. ## 是否校验 JWT 携带的字段
  24. ##
  25. ## Value: on | off
  26. auth.jwt.verify_claims = off
  27. ## 字段校验列表
  28. ##
  29. ## 配置格式:auth.jwt.verify_claims.$name = $expected
  30. ## $name 为需要校验的 JWT 的 payload 中的字段名称
  31. ## $expected 为期待值
  32. ##
  33. ## $expected 可用的占位符为
  34. ## - %u: username
  35. ## - %c: clientid
  36. ##
  37. ## 例如:校验 JWT 的 payload 中的 username 是否与
  38. ## 客户端(MQTT协议)中携带的 username 一致
  39. #auth.jwt.verify_claims.username = %u

auth.jwt.from

客户端携带 JWT 的位置,用于配置客户端 JWT 字符串携带位置,可选 username 与 password。

auth.jwt.verify_claims

如果你启用了 auth.jwt.verify_claims 选项,认证插件在验证 JWT 有效性之后还会进一步验证 Payload 中的数据有效性。

假设你的 Payload 为:

  1. {
  2. "username": "emqx_client_username"
  3. }

你可以使用如下配置,当客户端携带此 Token 时,将验证客户端 username 是否等于 emqx_client_username

  1. ## Variables:
  2. ## - %u: username
  3. ## - %c: clientid
  4. auth.jwt.verify_claims.username = %u

支持使用固定值或当前客户端信息进行验证:

  • %u:当前客户端 username
  • %c:当前客户端 client id

密钥配置和算法支持

JWT 认证支持以三种方式配置密钥,这三种方式分别对应三种类型的算法支持:

  • auth.jwt.secret:对称加密的方式,验证 JWT 的 Token 字段。它支持的算法有:

    • HS256 - HMAC,使用 SHA-256 哈希算法。
    • HS384 - HMAC,使用 SHA-384 哈希算法。
    • HS512 - HMAC,使用 SHA-512 哈希算法。
  • auth.jwt.pubkey:使用非对称加密的方式,验证 JWT 的 Token 字段。它支持的算法有:

    • RS256 - RSA,使用 SHA-256 哈希算法。
    • RS384 - RSA,使用 SHA-384 哈希算法。
    • RS512 - RSA,使用 SHA-512 哈希算法。
    • ES256 - ECDSA,使用 P-256 曲线。
    • ES384 - ECDSA,使用 P-384 曲线。
    • ES512 - ECDSA,使用 P-512 曲线。
  • auth.jwt.jwks:配置为 JWKsJWT 认证 - 图2 (opens new window) 服务器地址,从 JWKs 服务器中获取可用的密钥列表。

该三类密钥允许同时配置。EMQ X 在验证 Token 时会按 auth.jwt.secretauth.jwt.pubkeyauth.jwt.jwks 顺序检查。

WARNING

JWT 本身包含了认证信息,一旦泄露,任何人都可以获得该令牌的所有权限,使用 JWT 时建议启用 TLS 加密传输。 JWT 使用过程中无法在过期前废止某个 Token,请妥善设置有效时长并保管好密钥等加密信息。