# Authenticate clients by certificate

This guide connects clients whose only credential is a TLS client certificate. The gateway checks the certificate and sends it to NATS. Your auth callout service reads it and decides the NATS user and its permissions.

Before you start, you need:

* nats-server with an [auth callout](https://docs.nats.io/running-a-nats-service/configuration/securing_nats/auth_callout) service that you can change.
* The CA that signed the client certificates.
* A `nats-server.conf` that you can edit and reload.

## 1. Create the gateway's proxy key

NATS must know that a certificate comes from the gateway and not from another client. The gateway proves this with an nkey that the servers trust. Create the seed:

```
nats auth nkey gen user --output proxy.nk
```

Keep the seed secret. Each gateway can have its own seed.

## 2. Set up the listener

```
tls:

  cert: server.pem

  key: server-key.pem

  ca: devices-ca.pem

nats:

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

  proxy:

    seed: /etc/mq-gateway/proxy.nk

amqp:

  listeners:

    - { name: devices, addr: ":5671", auth: { mode: cert, username: cn } }
```

* `tls.ca` is the CA of the client certificates. The gateway refuses a client without a certificate that this CA signed.
* `nats.proxy.seed` is the seed from step 1. It can be an `env://` or `file://` location.
* `auth.mode: cert` works on MQTT and AMQP listeners.
* `username` is optional. See [Choose what the callout reads](#choose-what-the-callout-reads).

## 3. Trust the gateway in NATS

1. Start the gateway. It logs `trusted proxy key loaded` with the public key.

2. Add the key to `nats-server.conf`:

   ```
   proxies {

     trusted: [ { key: "UAH3...PUBLIC...KEY" } ]

   }
   ```

3. Reload the server:

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

## 4. Change the callout service

1. Read the client certificate from `auth_token` in the connect options of the request. It is one PEM certificate.
2. Decide the NATS user and its permissions from the certificate.
3. Set `proxy_required: true` in the user JWT that the service returns.
4. Give the user the client permissions from [Configure listeners and auth](/mq-gateway/0.4/how-to/configure-listeners-and-auth.md).

## Choose what the callout reads

The gateway always sends the whole certificate, so the callout can use any field. With `username`, the gateway also sends one field as the NATS username in the connect options:

| `username` | NATS username                                                      |
| ---------- | ------------------------------------------------------------------ |
| not set    | none                                                               |
| `cn`       | The common name of the certificate subject                         |
| `dn`       | The subject as a distinguished name, such as `CN=device-42,O=Acme` |

The gateway refuses a client whose certificate does not have the field.

## Check it works

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

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

Connect a client with its certificate and no username. An AMQP client uses SASL EXTERNAL. Then send the same certificate to NATS without the gateway:

```
nats pub test hello --server tls://nats.example.com:4222 --token "$(cat device.pem)"
```

NATS must refuse this connection. If NATS accepts it, the callout does not set `proxy_required`.

## Things to know

* **`proxy_required` is what makes the certificate safe to trust.** NATS accepts a user with `proxy_required` only on a connection that a trusted proxy key signed. Without it, any client that can reach NATS can send any certificate.
* **The client names no user.** An AMQP listener in `cert` mode offers only SASL EXTERNAL. On an MQTT listener, the gateway ignores the username and password that the client sends.
* **The TLS details in the callout request describe the gateway.** The `client_tls` field is the gateway's connection to NATS, not the client's. Read the client certificate from `auth_token`.
* **The gateway does not check certificate revocation.** To refuse a certificate before it expires, refuse it in the callout service.
* **A renewed certificate opens a new NATS connection**, so the callout sees it.
