Skip to main content
Version: 0.4

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

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.

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:

usernameNATS username
not setnone
cnThe common name of the certificate subject
dnThe 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.