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
  2. ## Secret Key
  3. ##
  4. ## The key to verify the JWT Token using HMAC algorithm
  5. auth.jwt.secret = emqxsecret
  6. ## RSA or ECDSA public key file
  7. ##
  8. ## The public key file to verify the JWT Token using RSA or ECDSA algorithm
  9. #auth.jwt.pubkey = etc/certs/jwt_public_key.pem
  10. ## JWKs server address
  11. ##
  12. ## EMQX will get the key list from JWKs server and use it to verify the Token
  13. ##
  14. ## About the JWKs, see: 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 refresh interval
  17. ##
  18. #auth.jwt.jwks.refresh_interval = 5m
  19. ## The way the client carries the token
  20. ## Value: username | password
  21. auth.jwt.from = password
  22. ## Enable to verify claims fields
  23. ##
  24. ## Value: on | off
  25. auth.jwt.verify_claims = off
  26. ## The checklist of claims to validate
  27. ##
  28. ## Configuration format: auth.jwt.verify_claims.$name = $expected
  29. ## - $name: the name of the field in the JWT payload to be verified
  30. ## - $expected: the expected value
  31. ##
  32. ## The available placeholders for $expected:
  33. ## - %u: username
  34. ## - %c: clientid
  35. ##
  36. ## For example, to verify that the username in the JWT payload is the same
  37. ## as the client (MQTT protocol) username
  38. #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.