JWT ACL

JWT ACL uses ACL rules from JWTs provided by a client during authentication. To keep JWTs reasonably small, clients using JWT ACL are not supposed to have many ACL rules.

Plugin:

  1. emqx_auth_jwt

TIP

The emqx_auth_jwt authorization features are tightly coupled with authentication features.

ACL information stored in claims

To enable authorization via JWT one should specify claim name for searching ACL rules.

  1. # etc/plugins/emqx_auth_jwt.conf
  3. ## Server address
  4. auth.jwt.acl_claim_name = acl

If the provided claim is not found in the JWT, no ACL check will be applied for this client, unless there are other ACL plugins or modules enabled.

Data structure

The data structure of ACL rules is the following:

  1. {
  2.     # ... payload claims ...
  3.     "acl": {
  4.         "sub": [
  5.             "some/topic/for/sub/1",
  6.             "some/topic/for/sub/2"
  7.         ],
  8.         "pub": [
  9.             "some/topics/for/pub/1",
  10.             "some/topics/for/pub/2"
  11.         ],
  12.         "all": [
  13.             "some/topics/for/pubsub/1",
  14.             "some/topics/for/pubsub/2"
  15.         ]
  16.     }
  17. }

pub, sub and all lists serve as whitelists for the corresponding operations.

You can use the following placeholders in topic whitelists:

  • %u: Username
  • %c: Client ID

For example:

  1. {
  2.     # ... payload claims ...
  3.     "acl": {
  4.         "pub": [
  5.             "some/stats/%c"
  6.         ]
  7.     }
  8. }

EMQX Broker will automatically interpolate topic names before checking ACL.

ACL expiration

JWT ACL engine will prohibit all operations after the deadline specified in exp JWT claim, so a client with an expired JWT has to reconnect with a fresh JWT.

To make ACL rules valid forever, a client may not provide exp claim at all.

WARING

  1. Using long-living JWTs is not considered secure.
  2. When ACL cache is enabled, the ACL rule’s expiration is either when the cache or JWT expires, whichever is the later.