JWT Authentication

JSON Web Token (JWT) authentication provides a secure mechanism for accessing EMQX Edge’s HTTP APIs using signed tokens. This enables integration with external identity systems and ensures that only authenticated users can access the broker's management endpoints.

Generate Public and Private Keys

Before issuing JWTs, you must generate a pair of RSA keys using OpenSSL:

Note: The iss (issuer) claim in the JWT must match the filename of the public key.

# generate private key
$ openssl genrsa -out nanomq.key 2048
# generate public key
$ openssl rsa -in nanomq.key -out nanomq.pub -pubout

Configuration

JWT is an optional feature in EMQX Edge and is disabled by default. The default HTTP server authentication mode is basic. To enable JWT authentication, set auth_type = jwt and provide the path to the public key in your configuration file.

Use the following HOCON configuration inside nanomq.conf. Changes take effect after restarting EMQX Edge.

For full configuration options, see HTTP Server Configuration.

http_server {
    # # http server port
    # #
    # # Value: 0 - 65535
    port = 8081
    # # parallel for http server
    # # Handle a specified maximum number of outstanding requests
    # #
    # # Value: 1-infinity
    parallel = 32
    # # http server username
    # #
    # # Value: String
    username = admin
    # # http server password
    # #
    # # Value: String
    password = public
    # # http server auth type
    # # If set auth_type=jwt, make sure you have built JWT dependency with `-DENABLE_JWT=ON` first.
    # #
    # # Value: String basic | jwt
    auth_type = jwt
    jwt {
        # # http server jwt public key file
        # # Used together with 'http_server.auth_type=jwt',
        # # Path to the file containing the user's private key.
        # #
        # # Value: File
        public.keyfile = "/etc/certs/jwt/nanomq.pub"
    }
}

Start EMQX Edge with JWT Configuration

To start EMQX Edge with your custom configuration file, run:

nanomq start --conf path/to/nanomq.conf

Replace path/to/nanomq.conf with the actual path to your configuration file.

JWT Token Format

To generate a token for an HTTP client, a valid JWT for EMQX Edge must contain the following structure:

header
{
    "alg": "RS256",
    "typ": "JWT"
}

payload
{
    "iss": "nanomq.pub",
    "iat": "1683281256",
    "exp": "1683283256",
    "bodyEncode": "0"
}

Header Fields

• typ: Must be JWT
• alg: Must be RS256 (RSA SHA-256)

Payload Fields

• iss: Must match the public key filename. For example, if the file name is "nanomq.pub", the iss should be nanomq.pub.
• iat: Issued-at timestamp (in seconds)
• exp: Expiration timestamp (in seconds)
• bodyEncode: Set to 0 (optional use depending on implementation)

Token Generation

You can use JWT official website tool to generate a JWT. Fill in the Decoded section as follows:

• Algorithm: RS256
• Header: Header
• Payload: Payload
• Verify Signature: Fille in public and private key.

Send Request with JWT to EMQX Edge HTTP Server

Use curl to send a GET request with the generated token to EMQX Edge HTTP Server :

$ curl --location 'http://127.0.0.1:8081/api/v4' \
--header 'Authorization: Bearer {TOKEN}'

Replace {TOKEN} with the signed JWT string.