# Configure listeners and auth

This guide sets the client ports, TLS, and the NATS permissions of the gateway and its clients. NATS, not the gateway, accepts each credential and enforces its permissions.

Before you start, you need:

* A config file, with its streams and buckets [provisioned](/mq-gateway/0.4/how-to/provision-streams-and-buckets.md).
* A `nats-server.conf` that you can edit and reload.

## Choose an auth mode for each port

| Clients on the port                                                                                                  | Mode                                                                                                              |
| -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Each client sends its own NATS username and password, as the MQTT username and password or the SASL PLAIN credential | `passthrough` (the default)                                                                                       |
| Devices that send no credential, or that you do not trust with one. All of them act as one restricted NATS user      | `fixed`                                                                                                           |
| Clients whose credential is a TLS client certificate, which an auth callout service maps to a NATS user              | `cert` (see [Authenticate clients by certificate](/mq-gateway/0.4/how-to/authenticate-clients-by-certificate.md)) |

## 1. List the listeners

```
mqtt:

  listeners:

    - { name: public,    addr: ":1883" }

    - { name: telemetry, addr: ":1884", auth: { mode: fixed, creds: /etc/nats/telemetry.creds } }

    - { name: ws,        addr: ":8080", ws-path: /mqtt }

amqp:

  listeners:

    - { name: amqp,   addr: ":5672" }

    - { name: legacy, addr: ":5673", auth: { mode: fixed, user: legacy, password: env://LEGACY_PASSWORD } }
```

* Each list holds every port for its protocol.
* `ws-path` serves the protocol over WebSocket at that path.
* A `fixed` listener takes one credential: `creds`, `nkey`, `user` and `password`, `jwt` and `seed`, or `context`. Each value can be an `env://` or `file://` location.
* A block with no `listeners` serves one passthrough port: MQTT on `:1883`, AMQP on `:5672`.

## 2. Generate the permissions

```
mq-gateway generate --config gateway.yaml --format nats-server > permissions.conf
```

`permissions.conf` defines one variable for each kind of NATS user:

* `$gateway_permissions`: the user the gateway acts as in an account.

* `$client_permissions`: the users that clients act as.

* `$admin_gateway_permissions` and `$operator_permissions`, commented out: the users of the admin account. See [Set up the admin account](/mq-gateway/0.4/how-to/set-up-the-admin-account.md).

Each account under `accounts` gets its own gateway variable, such as `$FLEET_B_gateway_permissions`. An account with its own bindings also gets its own client variable.

## 3. Narrow the client topics

The config file cannot know which topics each client uses. So each topic list holds all bound subjects, under a `NARROW` comment.

1. In `$client_permissions`, replace each `NARROW` list with the subjects that the user publishes and subscribes to.
2. Add the QoS 0 topics that the user uses outside the bindings.
3. For each subscribe subject that ends in `.>`, keep its parent subject too. For example, keep `orders` with `orders.>`.
4. For users with different topics, copy the variable under a new name for each user.
5. In `$gateway_permissions`, narrow the will topics to the ones your clients set.

An MQTT topic is a subject with `/` replaced by `.`. See [Mapping to NATS](/mq-gateway/0.4/reference/mapping-to-nats.md).

## 4. Give each user its permissions

Include the file in `nats-server.conf` and set `permissions` on each user:

```
include "permissions.conf"



accounts {

  FLEET_A: {

    jetstream: enabled

    users: [

      { user: gateway-a, password: "gw-a-secret", permissions: $gateway_permissions }

      { user: device, password: "device-secret", permissions: $client_permissions }

    ]

  }

  FLEET_B: {

    jetstream: enabled

    users: [

      { user: gateway-b, password: "gw-b-secret", permissions: $FLEET_B_gateway_permissions }

      { user: sensor, password: "sensor-secret", permissions: $client_permissions }

    ]

  }

}
```

* Give each account exactly one gateway user.
* Delete each variable that no user takes. nats-server refuses to load an unused variable.
* Keep the system account. The gateway asks it which account each user is in.
* In operator mode, put the same subjects in the user JWTs.

Reload the server:

```
nats-server --signal reload
```

## 5. Give the gateway its users

Put the gateway user of the gateway's own account under `nats`. Put each other gateway user under `accounts`, with the account name as the key:

```
nats:

  url: nats://nats.example.com:4222

  user: gateway-a

  password: env://GW_A_PASSWORD

accounts:

  FLEET_B: { user: gateway-b, password: env://GW_B_PASSWORD }
```

In operator mode, the key is the public key of the account. The gateway refuses to start if a user is not in the account that its key names.

## Serve TLS

Add a `tls` block. TLS then applies to every listener. A WebSocket listener becomes `wss://` and an AMQP listener becomes `amqps://`:

```
tls:

  cert: server.pem

  key: server-key.pem

  ca: clients-ca.pem     # optional: require client certificates
```

With `tls.ca`, every client on every listener must present a certificate that the CA signed. The certificate only admits the client. The auth mode of the port still sets the NATS user.

On a `cert` listener, the certificate is also the credential of the client.

To serve a plain port and a TLS port, run two gateways.

## Check it works

```
mq-gateway check --config gateway.yaml --verbose

mq-gateway --config gateway.yaml
```

The gateway logs `listener enabled` for each port and `account ready` for each account. Then connect a client on each port:

```
mqttx pub -h 127.0.0.1 -p 1884 -t 'orders/x' -m 'hello'               # fixed: no credential

mqttx sub -h 127.0.0.1 -p 1883 -u device -P device-secret -q 1 -t 'orders/#'
```

The subscriber gets QoS 1. This shows that its user can create its consumer.

## Things to know

* **A passthrough client with no username connects to NATS with no credential.** NATS refuses it, or connects it as the server's `no_auth_user`. Use a `fixed` listener to give these clients one restricted NATS user.

* **Clients cannot use the gateway's own subjects.** The gateway refuses a client publish or subscription on `$MQG.>`, whatever the user's permissions allow. The admin requests are not in the client accounts at all.

* **A client without permission gets Not authorized.** See [Errors](/mq-gateway/0.4/reference/errors.md) for each code and its fix.
