Security

NATS has a lot of security features and .NET V2 client supports them all. All you need to do is to pass your credentials to the connection.

NatsOpts opts = new NatsOpts
{
    AuthOpts = NatsAuthOpts.Default with
    {
        Username = "bob",
        Password = "s3cr3t",
    },
};

await using NatsClient nats = new NatsClient(opts);

See also user authentication tests for more examples.

Implicit TLS Connections

As of NATS server version 2.10.4 and later, the server supports implicit TLS connections. This means that the client can connect to the server using the default port of 4222 and the server will automatically upgrade the connection to TLS. This is useful for environments where TLS is required by default.

NatsOpts opts = new NatsOpts
{
    TlsOpts = new NatsTlsOpts
    {
        Mode = TlsMode.Implicit,
    },
};

await using NatsClient nats = new NatsClient(opts);

Mutual TLS Connections

The server can require TLS certificates from a client to validate the client certificate matches a known or trusted CA and to provide authentication.

You can set the TLS options to use your client certificates when connecting to a server which requires TLS Mutual authentication.

NatsOpts opts = new NatsOpts
{
    TlsOpts = new NatsTlsOpts
    {
        CertFile = "path/to/cert.pem",
        KeyFile = "path/to/key.pem",
        CaFile = "path/to/ca.pem",
    },
};

await using NatsClient nats = new NatsClient(opts);

Tip

Intermediate CA Certificates

When connecting using intermediate CA certificates, it might not be possible to validate the client certificate and TLS handshake may fail.

Unfortunately, for .NET client applications it isn't possible to pass additional intermediate certificates and the only solution is to add the certificates to the certificate store manually.

See also .NET documentation on Troubleshooting SslStream authentication issues

TLS Modes

The .NET client supports several TLS modes via NatsTlsOpts.Mode:

Mode	Behavior
Auto (default)	Resolves to Prefer for nats:// without certificates, Require for tls:// or when certificates are provided
Prefer	Upgrades to TLS if the server advertises TLS support, otherwise connects in plaintext
Require	Always requires TLS, fails if the server does not support it
Implicit	Connects with TLS immediately, before any protocol exchange
Disable	Never attempts TLS, always connects in plaintext

Note

Only Require and Implicit provide the full protection that TLS can offer. Other modes may fall back to plaintext depending on server configuration.

TLS Behind a Proxy

When the nats-server is behind a TLS-terminating proxy, the server may advertise TLS support (tls_available) even though TLS is handled by the proxy. In this configuration the default Auto/Prefer mode will attempt a TLS upgrade that the nats-server cannot complete, causing the connection to fail.

Set TlsMode.Disable to skip the TLS upgrade:

var opts = new NatsOpts
{
    Url = "nats://my-nats-behind-proxy:4222",
    TlsOpts = new NatsTlsOpts { Mode = TlsMode.Disable },
};
await using var nats = new NatsConnection(opts);

Note

This behavior differs from most other NATS clients, which do not attempt a TLS upgrade when the server only advertises tls_available without tls_required.