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.confthat 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.cais the CA of the client certificates. The gateway refuses a client without a certificate that this CA signed.nats.proxy.seedis the seed from step 1. It can be anenv://orfile://location.auth.mode: certworks on MQTT and AMQP listeners.usernameis optional. See Choose what the callout reads.
3. Trust the gateway in NATS
-
Start the gateway. It logs
trusted proxy key loadedwith the public key. -
Add the key to
nats-server.conf:proxies {trusted: [ { key: "UAH3...PUBLIC...KEY" } ]} -
Reload the server:
nats-server --signal reload
4. Change the callout service
- Read the client certificate from
auth_tokenin the connect options of the request. It is one PEM certificate. - Decide the NATS user and its permissions from the certificate.
- Set
proxy_required: truein the user JWT that the service returns. - 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:
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_requiredis what makes the certificate safe to trust. NATS accepts a user withproxy_requiredonly 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
certmode 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_tlsfield is the gateway's connection to NATS, not the client's. Read the client certificate fromauth_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.