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

```bash
# 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](../config-description/http-server.md).

```c
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:

```bash
emqx-edge 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:

```bash
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](https://jwt.io/) 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 : 

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

Replace `{TOKEN}` with the signed JWT string.