NATS uses cookies to ensure you get the best experience on our website. Continuing to use this site assumes compliance with our Privacy Policy.
Edit on GitHub

Securing Connections

NATS provides several forms of security for your messages. First, you can turn on authorization which limits access to the NATS server. Second, access to specific subjects can be controlled. Third, you can use TLS to encrypt traffic between clients and the server. Finally, TLS can be used to verify client identities using certificates. By combining all of these methods you can protect access to data and data in motion.

The client doesn’t have control over access controls, but clients do provide the configurations required to authenticate with the server and to turn on TLS.

Server Authentication

There are two kinds of authentication in NATS as well as certificate verification discussed below:

  • User/Password
  • Token

While the server can be configured to take either of these via the configuration file, we will use the command line in these examples to make things easy. See the server doc for more details on the configuration file format.

For the user/password examples, start the server using:

> gnatsd --user myname --pass password

You can encrypt passwords to pass to gnatsd using a simple tool provided by the server:

> go run mkpasswd.go -p
> password: password
> bcrypt hash: $2a$11$1oJy/wZYNTxr9jNwMNwS3eUGhBpHT3On8CL9o7ey89mpgo88VG6ba

and use the hashed password in the server config. The client still uses the plain text version.

For the token examples, start the server using:

> gnatsd --auth mytoken

The following examples use localhost:4222 so that you can start the server on your machine to try them out.

Authenticating with a User and Password

When logging in with a password gnatsd will take either a plain text password or an encrypted password.

// Set a user and plain text password
nc, err := nats.Connect("localhost", nats.UserInfo("myname", "password"))
if err != nil {
	log.Fatal(err)
}
defer nc.Close()

// Do something with the connection

Options options = new Options.Builder().
                            server("nats://localhost:4222").
                            userInfo("myname","password"). // Set a user and plain text password
                            build();
Connection nc = Nats.connect(options);

// Do something with the connection

nc.close();
let nc = NATS.connect({url: server.nats, user: "myname", pass: "password"});
nc = NATS()

await nc.connect(servers=["nats://myname:password@demo.nats.io:4222"])

# Do something with the connection.

require 'nats/client'

NATS.start(servers:["nats://myname:password@127.0.0.1:4222"], name: "my-connection") do |nc|
   nc.on_error do |e|
    puts "Error: #{e}"
  end

   nc.on_reconnect do
    puts "Got reconnected to #{nc.connected_server}"
  end

  nc.on_disconnect do |reason|
    puts "Got disconnected! #{reason}"
  end

  nc.close
end
let nc = await connect({url: server.nats, user: "myname", pass: "password"});

Authenticating with a User and Password in the URL

Most clients make it easy to pass the user name and password by accepting them in the URL for the server. This standard format is:

nats://user:password@server:port

Using this format, you can connect to a server using authentication as easily as you connected with a URL:

// Set a user and plain text password
nc, err := nats.Connect("myname:password@localhost")
if err != nil {
	log.Fatal(err)
}
defer nc.Close()

// Do something with the connection

Connection nc = Nats.connect("nats://myname:password@localhost:4222");

// Do something with the connection

nc.close();
let url = `nats://myname:password@127.0.0.1:${port}`;
let nc = NATS.connect(url);
nc = NATS()

await nc.connect(servers=["nats://myname:password@demo.nats.io:4222"])

# Do something with the connection.

require 'nats/client'

NATS.start(servers:["nats://myname:password@127.0.0.1:4222"], name: "my-connection") do |nc|
   nc.on_error do |e|
    puts "Error: #{e}"
  end

   nc.on_reconnect do
    puts "Got reconnected to #{nc.connected_server}"
  end

  nc.on_disconnect do |reason|
    puts "Got disconnected! #{reason}"
  end

  nc.close
end
let url = `nats://myname:password@127.0.0.1:${port}`;
let nc = await connect({url: url});

Authenticating with a Token

Tokens are basically random strings, much like a password.

// Set a token
nc, err := nats.Connect("localhost", nats.Token("mytoken"))
if err != nil {
	log.Fatal(err)
}
defer nc.Close()

// Do something with the connection

Options options = new Options.Builder().
                            server("nats://localhost:4222").
                            token("mytoken"). // Set a token
                            build();
Connection nc = Nats.connect(options);

// Do something with the connection

nc.close();
let nc = NATS.connect({url: `nats://127.0.0.1:${port}`, token: "mytoken!"});
nc = NATS()

await nc.connect(servers=["nats://mytoken@demo.nats.io:4222"])

# Do something with the connection.

NATS.start(token: "deadbeef") do |nc|
  puts "Connected using token"
end
let nc = await connect({url: server.nats, token: "mytoken"});

Authenticating with a Token in the URL

Some client libraries will allow you to pass the token as part of the server URL using the form:

nats://token@server:port

Again, once you construct this URL you can connect as if this was a normal URL.

// Token in URL
nc, err := nats.Connect("mytoken@localhost")
if err != nil {
	log.Fatal(err)
}
defer nc.Close()

// Do something with the connection

Connection nc = Nats.connect("nats://mytoken@localhost:4222");//Token in URL

// Do something with the connection

nc.close();
let url = `nats://mytoken!@127.0.0.1:${port}`;
let nc = NATS.connect({url: url});
nc = NATS()

await nc.connect(servers=["nats://mytoken@demo.nats.io:4222"])

# Do something with the connection.

NATS.start("deadbeef@127.0.0.1:4222") do |nc|
  puts "Connected using token!"
end
let url = `nats://:mytoken!@127.0.0.1:${port}`;
let nc = await connect({url: url});

Encrypting Connections with TLS

While authentication limits which clients can connect, TLS can be used to check the server’s identity and the client’s identity and will encrypt the traffic between the two. The most secure version of TLS with NATS is to use verified client certificates. In this mode, the client can check that it trusts the certificate sent by gnatsd but the server will also check that it trusts the certificate sent by the client. From an applications perspective connecting to a server that does not verify client certificates may appear identical. Under the covers, disabling TLS verification removes the server side check on the client’s certificate. When started in TLS mode, gnatsd will require all clients to connect with TLS. Moreover, if configured to connect with TLS, client libraries will fail to connect to a server without TLS.

The Java examples repository contains certificates for starting the server in TLS mode.

> gnatsd -c /src/main/resources/tls.conf
 or
> gnatsd -c /src/main/resources/tls_verify.conf

Connecting with TLS

Connecting to a server with TLS is primarily an exercise in setting up the certificate and trust managers. For example:

nc, err := nats.Connect("localhost",
	nats.ClientCert("resources/certs/cert.pem", "resources/certs/key.pem"),
	nats.RootCAs("resources/certs/ca.pem"))
if err != nil {
	log.Fatal(err)
}
defer nc.Close()

// Do something with the connection

class SSLUtils {
    public static String KEYSTORE_PATH = "src/main/resources/keystore.jks";
    public static String TRUSTSTORE_PATH = "src/main/resources/cacerts";
    public static String STORE_PASSWORD = "password";
    public static String KEY_PASSWORD = "password";
    public static String ALGORITHM = "SunX509";

    public static KeyStore loadKeystore(String path) throws Exception {
        KeyStore store = KeyStore.getInstance("JKS");
        BufferedInputStream in = new BufferedInputStream(new FileInputStream(path));

        try {
            store.load(in, STORE_PASSWORD.toCharArray());
        } finally {
            if (in != null) {
                in.close();
            }
        }

        return store;
    }

    public static KeyManager[] createTestKeyManagers() throws Exception {
        KeyStore store = loadKeystore(KEYSTORE_PATH);
        KeyManagerFactory factory = KeyManagerFactory.getInstance(ALGORITHM);
        factory.init(store, KEY_PASSWORD.toCharArray());
        return factory.getKeyManagers();
    }

    public static TrustManager[] createTestTrustManagers() throws Exception {
        KeyStore store = loadKeystore(TRUSTSTORE_PATH);
        TrustManagerFactory factory = TrustManagerFactory.getInstance(ALGORITHM);
        factory.init(store);
        return factory.getTrustManagers();
    }

    public static SSLContext createSSLContext() throws Exception {
        SSLContext ctx = SSLContext.getInstance(Options.DEFAULT_SSL_PROTOCOL);
        ctx.init(createTestKeyManagers(), createTestTrustManagers(), new SecureRandom());
        return ctx;
    }
}

public class ConnectTLS {
    public static void main(String[] args) {

        try {
            SSLContext ctx = SSLUtils.createSSLContext();
            Options options = new Options.Builder().
                                server("nats://localhost:4222").
                                sslContext(ctx). // Set the SSL context
                                build();
            Connection nc = Nats.connect(options);
            
            // Do something with the connection

            nc.close();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
let caCert = fs.readFileSync(caCertPath);
let clientCert = fs.readFileSync(clientCertPath);
let clientKey = fs.readFileSync(clientKeyPath);
let nc = NATS.connect({
    url: url,
    tls: {
        ca: [caCert],
        key: [clientKey],
        cert: [clientCert]
    }
});
nc = NATS()

ssl_ctx = ssl.create_default_context(purpose=ssl.Purpose.SERVER_AUTH)
ssl_ctx.load_verify_locations('ca.pem')
ssl_ctx.load_cert_chain(certfile='client-cert.pem',
                        keyfile='client-key.pem')
await nc.connect(io_loop=loop, tls=ssl_ctx)

await nc.connect(servers=["nats://demo.nats.io:4222"], tls=ssl_ctx)

# Do something with the connection.

EM.run do

  options = {
    :servers => [
      'nats://localhost:4222',
    ],
    :tls => {
      :private_key_file => './spec/configs/certs/key.pem',
      :cert_chain_file  => './spec/configs/certs/server.pem'
    }
  }

  NATS.connect(options) do |nc|
    puts "#{Time.now.to_f} - Connected to NATS at #{nc.connected_server}"

    nc.subscribe("hello") do |msg|
      puts "#{Time.now.to_f} - Received: #{msg}"
    end

    nc.flush do
      nc.publish("hello", "world")
    end

    EM.add_periodic_timer(0.1) do
      next unless nc.connected?
      nc.publish("hello", "hello")
    end

    # Set default callbacks
    nc.on_error do |e|
      puts "#{Time.now.to_f } - Error: #{e}"
    end

    nc.on_disconnect do |reason|
      puts "#{Time.now.to_f} - Disconnected: #{reason}"
    end

    nc.on_reconnect do |nc|
      puts "#{Time.now.to_f} - Reconnected to NATS server at #{nc.connected_server}"
    end

    nc.on_close do
      puts "#{Time.now.to_f} - Connection to NATS closed"
      EM.stop
    end
  end
end
let caCert = readFileSync(caCertPath);
let clientCert = readFileSync(clientCertPath);
let clientKey = readFileSync(clientKeyPath);
let nc = await connect({
    url: url,
    tls: {
        ca: [caCert],
        key: [clientKey],
        cert: [clientCert]
    }
});

Connecting with the TLS Protocol

Some clients may support the tls protocol as well as a manual setting to turn on TLS. However, in that case there is likely some form of default or environmental settings to allow the TLS libraries to find certificate and trust stores.

nc, err := nats.Connect("localhost",
	nats.Secure(),
	nats.RootCAs("resources/certs/ca.pem")) // May need this if server is using self-signed certificate
if err != nil {
	log.Fatal(err)
}
defer nc.Close()

// Do something with the connection

class SSLUtils2 {
    public static String KEYSTORE_PATH = "src/main/resources/keystore.jks";
    public static String TRUSTSTORE_PATH = "src/main/resources/cacerts";
    public static String STORE_PASSWORD = "password";
    public static String KEY_PASSWORD = "password";
    public static String ALGORITHM = "SunX509";

    public static KeyStore loadKeystore(String path) throws Exception {
        KeyStore store = KeyStore.getInstance("JKS");
        BufferedInputStream in = new BufferedInputStream(new FileInputStream(path));

        try {
            store.load(in, STORE_PASSWORD.toCharArray());
        } finally {
            if (in != null) {
                in.close();
            }
        }

        return store;
    }

    public static KeyManager[] createTestKeyManagers() throws Exception {
        KeyStore store = loadKeystore(KEYSTORE_PATH);
        KeyManagerFactory factory = KeyManagerFactory.getInstance(ALGORITHM);
        factory.init(store, KEY_PASSWORD.toCharArray());
        return factory.getKeyManagers();
    }

    public static TrustManager[] createTestTrustManagers() throws Exception {
        KeyStore store = loadKeystore(TRUSTSTORE_PATH);
        TrustManagerFactory factory = TrustManagerFactory.getInstance(ALGORITHM);
        factory.init(store);
        return factory.getTrustManagers();
    }

    public static SSLContext createSSLContext() throws Exception {
        SSLContext ctx = SSLContext.getInstance(Options.DEFAULT_SSL_PROTOCOL);
        ctx.init(createTestKeyManagers(), createTestTrustManagers(), new SecureRandom());
        return ctx;
    }
}

public class ConnectTLSURL {
    public static void main(String[] args) {

        try {
            SSLContext.setDefault(SSLUtils2.createSSLContext()); // Set the default context
            Options options = new Options.Builder().
                                server("tls://localhost:4222"). // Use the TLS protocol
                                build();
            Connection nc = Nats.connect(options);
            
            // Do something with the connection

            nc.close();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
let nc = NATS.connect({
    url: "tls://demo.nats.io:4443",
    tls: true
});
import asyncio
import ssl
from nats.aio.client import Client as NATS
from nats.aio.errors import ErrTimeout

async def run(loop):
    nc = NATS()

    # If using Python 3.7 in OS X and getting SSL errors, run first:
    #
    # /Applications/Python\ 3.7/Install\ Certificates.command
    #
    # Setting the tls as the scheme will use same defaults as `ssl.create_default_context()`
    #
    await nc.connect("tls://demo.nats.io:4443", loop=loop, tls=ssl_ctx)

    async def message_handler(msg):
        subject = msg.subject
        reply = msg.reply
        data = msg.data.decode()
        print("Received a message on '{subject} {reply}': {data}".format(
            subject=subject, reply=reply, data=data))

    # Simple publisher and async subscriber via coroutine.
    sid = await nc.subscribe("foo", cb=message_handler)
    await nc.flush()

    # Stop receiving after 2 messages.
    await nc.auto_unsubscribe(sid, 2)
    await nc.publish("foo", b'Hello')
    await nc.publish("foo", b'World')
    await nc.publish("foo", b'!!!!!')
    await asyncio.sleep(1, loop=loop)
    await nc.close()
EM.run do

  # In order to use TLS with the Ruby NATS client, use the :tls option
  # when customizing the connection with an empty block.
  options = {
    :servers => [
      'nats://demo.nats.io:4443',
    ],
    :tls => {}
  }

  NATS.connect(options) do |nc|
    puts :connected
  end
end
// will throw an exception if connection fails
let nc = await connect({
    url: "tls://demo.nats.io:4443"
});

nc.close();