# 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:

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.

# etc/plugins/emqx_auth_jwt.conf

## Server address
auth.jwt.acl_claim_name = acl

1
2
3
4
5

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:

{
    # ... payload claims ...
    "acl": {
        "sub": [
            "some/topic/for/sub/1",
            "some/topic/for/sub/2"
        ],
        "pub": [
            "some/topics/for/pub/1",
            "some/topics/for/pub/2"
        ],
        "all": [
            "some/topics/for/pubsub/1",
            "some/topics/for/pubsub/2"
        ]
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
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:

{
    # ... payload claims ...
    "acl": {
        "pub": [
            "some/stats/%c"
        ]
    }
}

1
2
3
4
5
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.

:::

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

← HTTP ACL MySQL ACL →