JWT

JWTJWT - 图1 (opens new window) is a Token-based authentication mechanism. It does not rely on the server to retain client authentication information or session information. It can issue authentication information in batches while holding keys, which is an easiest authentication method.

Plugin:

  1. emqx_auth_jwt

Authentication principle

The client uses Token as the user name or password (depending on the plugin configuration). When initiating the connection, EMQX Broker uses the key and certificate in the configuration to decrypt. If it can be successfully decrypted, the authentication successes, otherwise the authentication fails.

After JWT authentication is enabled by default, you can connect with the following password and any username:

  1. eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7ImF1dGhvciI6IndpdndpdiIsInNpdGUiOiJodHRwczovL3dpdndpdi5jb20ifSwiZXhwIjoxNTgyMjU1MzYwNjQyMDAwMCwiaWF0IjoxNTgyMjU1MzYwfQ.FdyAx2fYahm6h3g47m88ttyINzptzKy_speimyUcma4

JWT Authorization

JWT authentication plugin can extract ACL rules from authentication tokens. These ACL rules will be later used to authorize client’s actions. See JWT ACL.

Configuration item

If you want to use JWT Auth you need open etc/plugins/emqx_auth_jwt.conf and edit as：

To enable JWT authentication, the following needs to be configured in etc/plugins/emqx_auth_jwt.conf:

  1. # etc/plugins/emqx_auth_jwt.conf
  3. ## Secret Key
  4. ##
  5. ## The key to verify the JWT Token using HMAC algorithm
  6. auth.jwt.secret = emqxsecret
  8. ## RSA or ECDSA public key file
  9. ##
  10. ## The public key file to verify the JWT Token using RSA or ECDSA algorithm
  11. #auth.jwt.pubkey = etc/certs/jwt_public_key.pem
  13. ## JWKs server address
  14. ##
  15. ## EMQX will get the key list from JWKs server and use it to verify the Token
  16. ##
  17. ## About the JWKs, see: http://self-issued.info/docs/draft-ietf-jose-json-web-key.html
  18. #auth.jwt.jwks = https://127.0.0.1:8080/jwks
  20. ## JWKs refresh interval
  21. ##
  22. #auth.jwt.jwks.refresh_interval = 5m
  24. ## The way the client carries the token
  25. ## Value: username | password
  26. auth.jwt.from = password
  28. ## Enable to verify claims fields
  29. ##
  30. ## Value: on | off
  31. auth.jwt.verify_claims = off
  33. ## The checklist of claims to validate
  34. ##
  35. ## Configuration format: auth.jwt.verify_claims.$name = $expected
  36. ##   - $name: the name of the field in the JWT payload to be verified
  37. ##   - $expected: the expected value
  38. ##
  39. ## The available placeholders for $expected:
  40. ##   - %u: username
  41. ##   - %c: clientid
  42. ##
  43. ## For example, to verify that the username in the JWT payload is the same
  44. ## as the client (MQTT protocol) username
  45. #auth.jwt.verify_claims.username = %u

auth.jwt.from

The field where the client carries the JWT Token, used to configure where the client carries the JWT string, optional fields are username and password.

auth.jwt.verify_claims

If you enable the auth.jwt.verify_claims option, EMQXwill verify the validity of the data in the Payload after verifying the validity of the JWT.

suppose your Payload is:

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

You can use the following configuration to verify that client username is equal to emqx_client_username when the client carries this Token.

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

Support for verification using fixed values or current client information:

  • %u: current client username
  • %c: current client client id

Key and Algorithm support

JWT authentication supports three ways to configure keys, which correspond to three types of algorithm support.

  • auth.jwt.secret: a symmetric encryption method that validates the JWT Token field. It supports the following algorithms:

    • HS256 - HMAC, using the SHA-256 hash algorithm.
    • HS384 - HMAC, using the SHA-384 hash algorithm.
    • HS512 - HMAC, using the SHA-512 hash algorithm.

  • auth.jwt.pubkey: authenticates the JWT Token field using asymmetric encryption. It supports the following algorithms.

    • RS256 - RSA, using the SHA-256 hash algorithm.
    • RS384 - RSA, using the SHA-384 hash algorithm.
    • RS512 - RSA, using the SHA-512 hash algorithm.
    • ES256 - ECDSA, using the P-256 curve.
    • ES384 - ECDSA, using the P-384 curve.
    • ES512 - ECDSA, using the P-512 curve.
  • auth.jwt.jwks: configured as JWKsJWT - 图2 (opens new window) server address to get the list of available keys from the JWKs server.

The three types of keys are allowed to be configured simultaneously. EMQX checks the Token in the order of auth.jwt.secret, auth.jwt.pubkey, auth.jwt.jwks.

TIP

JWT contains authentication information by itself. Once leaked, anyone can get all the permissions of the token. It is recommended to enable TLS encrypted transmission when using JWT.

During the use of JWT, a token cannot be invalidated before it expires. Please properly set the validity time and keep the encryption information well.