JWT Authentication

JWT (opens new window) Authentication is an authentication mechanism based on Token. It does not rely on the server to retain the authentication information or session information of the client. The authentication information can be issued in batches with the key. The easiest way to authenticate.

Create module

Open EMQX Dashboard (opens new window), click the “Modules” tab on the left, select “Add Module”:

Then select “JWT Authentication” under “Authentication”:

JWT authentication provides the following configuration items:

1. From: The field that stores the JWT when the client connects. It currently supports the selection of username or password.
2. Secret: The key used when issuing the JWT. It will be used to verify whether the JWT received by EMQX is legal and is applicable to the JWT issued by the HMAC algorithm.
3. Pubkey: It will be used to verify whether the JWT received by EMQX is legal, and is applicable to the JWT issued by RSA or ECDSA algorithm.
4. JWKs Addr: EMQX will periodically query the latest public key list from the JWKS server and use it to verify whether the received JWT is legitimate, and is applicable to JWTs issued by RSA or ECDSA algorithms.
5. Verify Claims: Whether to verify that the claims in the JWT payload are consistent with the claims.
6. Claims: A list of claims fields used to verify that the claims in the JWT payload are valid. The most common usage is to add a key-value pair with a key of username and a value of %u, %u as a placeholder that will be replaced at runtime with the Username that the client will actually use when connecting. The replaced value will be used to compare with the value of the same-key claim of the JWT Payload to have a one-to-one correspondence between JWT and Username. The following two placeholders are currently supported in the declaration field list:
   1. %u: It will be replaced at runtime with the Username used by the client when connecting.
   2. %c: It will be replaced at runtime with the Client ID used by the client when connecting.

Note: When verifying JWT the values for Secret, Pubkey, and JWKs Addr are checked in that specific order. Keys with missing values will be ignored.

After the configuration is complete, click the “Add” button to successfully add the JWT authentication module.

Authentication principle

Client carries JWT with username or password field (depending on the module configuration). When initiating a connection, EMQX uses the key and certificate in the configuration for decryption. If the decryption is successful, the authentication is successful, otherwise the authentication fails.

After JWT authentication is enabled in the default configuration, you can connect with any username + the following password:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7ImF1dGhvciI6IndpdndpdiIsInNpdGUiOiJodHRwczovL3dpdndpdi5jb20ifSwiZXhwIjoxNTgyMjU1MzYwNjQyMDAwMCwiaWF0IjoxNTgyMjU1MzYwfQ.FdyAx2fYahm6h3g47m88ttyINzptzKy_speimyUcma4

TIP

The above JWT Token is only for testing and can be generated with related tools according to your own business needs. An online generation tool is provided here: https://www.jsonwebtoken.io/.

ACL information stored in claims

The ‘ACL Claim Name’ field can be used to to specify which JWT token claim is to be used for ACL rules. 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.

ACL 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"
        ]
    }
}

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"
        ]
    }
}

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 omit the exp claim.

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.