DEV Community

Karthik Nayak
Karthik Nayak

Posted on

Securing NATS with NKey Authentication: A Complete Guide

#networking #security #tutorial

Securing NATS with NKey Authentication: A Complete Guide

NATS is a high-performance messaging system that powers modern distributed applications. While NATS offers multiple authentication mechanisms, NKey authentication stands out as a cryptographically secure, decentralized approach that eliminates the need for shared secrets.

What are NKeys?

NKeys are Ed25519 key pairs specifically designed for NATS authentication. Unlike traditional username/password combinations, NKeys use public-key cryptography to verify identity without transmitting secrets over the network.

Key Benefits

  • No shared secrets: Private keys never leave the client
  • Cryptographically secure: Based on Ed25519 signatures
  • Decentralized: No central password database required
  • Revocable: Easy to rotate and revoke keys
  • Auditable: Clear identity tracking

NKey Types

NATS uses different NKey types for various purposes:

  • User Keys (U): For client authentication
  • Account Keys (A): For multi-tenancy
  • Operator Keys (O): For top-level authority
  • Server Keys (N): For server identity
  • Cluster Keys (C): For cluster communication

Generating NKeys

Install the nk tool:

go install github.com/nats-io/nkeys/nk@latest
Enter fullscreen mode Exit fullscreen mode

Generate a user NKey:

nk -gen user -pubout
Enter fullscreen mode Exit fullscreen mode

This outputs:

SUAOL3KQIY... (seed - keep private!)
UDXU4RCVJ... (public key)
Enter fullscreen mode Exit fullscreen mode

Important: Store the seed securely - it's your private key!

Server Configuration

Configure your NATS server to accept NKey authentication:

# nats-server.conf
authorization {
  users = [
    {
      nkey: UDXU4RCVJ5K7MONFUQ2WFP3QZJWLQVZ3AQKJ7HNVQXKFZJQXQZQXQZQX
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Start the server:

nats-server -c nats-server.conf
Enter fullscreen mode Exit fullscreen mode

Client Authentication

Go Client 

package main

import (
    "github.com/nats-io/nats.go"
    "github.com/nats-io/nkeys"
)

func main() {
    seed := []byte("SUAOL3KQIY...") // Your private seed

    opt, _ := nats.Nkey("UDXU4RCVJ...", func(nonce []byte) ([]byte, error) {
        kp, _ := nkeys.FromSeed(seed)
        sig, _ := kp.Sign(nonce)
        return sig, nil
    })

    nc, _ := nats.Connect("nats://localhost:4222", opt)
    defer nc.Close()

    // Use connection
}
Enter fullscreen mode Exit fullscreen mode

JavaScript Client 

const { connect } = require('nats');
const { fromSeed } = require('nkeys.js');

const seed = new TextEncoder().encode('SUAOL3KQIY...');
const kp = fromSeed(seed);

const nc = await connect({
  servers: 'nats://localhost:4222',
  authenticator: (nonce) => {
    return kp.sign(nonce);
  }
});
Enter fullscreen mode Exit fullscreen mode

Python Client 

import nats
from nkeys import from_seed

async def main():
    seed = b'SUAOL3KQIY...'
    kp = from_seed(seed)

    nc = await nats.connect(
        "nats://localhost:4222",
        nkeys_seed=seed
    )

    await nc.close()
Enter fullscreen mode Exit fullscreen mode

Advanced: Account-Based Authentication

For multi-tenant systems, use account-based NKeys:

# operator.conf
operator: OAFEEYZSYYVI4FXLRXJTMM32PQEI3RGOWZJT7Y3YFM4HB7ACPE4RTJPG

resolver: MEMORY

resolver_preload: {
  ABJHLOVMPA4CI6R5KLNGOB4GSLNIY7IOUPAJC4YFNDLQVIOBYQGUWVLA: eyJ0eXAiOiJqd3QiLCJhbGc...
}
Enter fullscreen mode Exit fullscreen mode

Generate account and user:

# Generate account
nk -gen account -pubout

# Generate user for account
nk -gen user -pubout
Enter fullscreen mode Exit fullscreen mode

Security Best Practices

1. Secure Seed Storage

Never hardcode seeds in source code. Use:

  • Environment variables
  • Secure key management systems (Vault, AWS KMS)
  • Encrypted configuration files 
seed := os.Getenv("NATS_NKEY_SEED")
Enter fullscreen mode Exit fullscreen mode

2. Key Rotation

Regularly rotate NKeys:

# Generate new key
nk -gen user -pubout > new_key.txt

# Update server config
# Update client applications
# Revoke old key
Enter fullscreen mode Exit fullscreen mode

3. Principle of Least Privilege

Grant minimal permissions per NKey:

authorization {
  users = [
    {
      nkey: UDXU4RCVJ...
      permissions: {
        publish: ["orders.>"]
        subscribe: ["orders.status"]
      }
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

4. Monitoring and Auditing

Track authentication events:

nats-server -DV  # Debug and trace mode
Enter fullscreen mode Exit fullscreen mode

Troubleshooting

Authentication Failed

Error: "Authorization Violation"

Solutions:

  • Verify public key matches in server config
  • Check seed is correct and not corrupted
  • Ensure signature function is working

Connection Timeout

Error: Connection timeout during auth

Solutions:

  • Check network connectivity
  • Verify server is running with NKey auth enabled
  • Confirm firewall rules allow NATS port (4222)

Comparison with Other Auth Methods

Method Security Complexity Use Case
Token Low Low Development
Username/Password Medium Low Simple deployments
NKey High Medium Production systems
JWT High High Enterprise multi-tenancy

Real-World Example: Microservices 

// Service A (Publisher)
func publisherService() {
    seed := loadSecureSeed("publisher")
    nc := connectWithNKey(seed)

    nc.Publish("orders.new", orderData)
}

// Service B (Subscriber)
func subscriberService() {
    seed := loadSecureSeed("subscriber")
    nc := connectWithNKey(seed)

    nc.Subscribe("orders.new", handleOrder)
}

func connectWithNKey(seed []byte) *nats.Conn {
    kp, _ := nkeys.FromSeed(seed)
    pubKey, _ := kp.PublicKey()

    opt, _ := nats.Nkey(pubKey, func(nonce []byte) ([]byte, error) {
        return kp.Sign(nonce)
    })

    nc, _ := nats.Connect("nats://prod-cluster:4222", opt)
    return nc
}
Enter fullscreen mode Exit fullscreen mode

Conclusion

NKey authentication provides a robust, secure foundation for NATS deployments. By leveraging public-key cryptography, you eliminate password management overhead while gaining strong security guarantees.

Key Takeaways:

  • NKeys use Ed25519 for cryptographic security
  • Private keys never leave the client
  • Perfect for microservices and distributed systems
  • Easy to implement across multiple languages
  • Scales well with account-based multi-tenancy

Start securing your NATS infrastructure with NKeys today!

Resources

Have questions about NATS authentication? Drop a comment below!

Top comments (0)