Skip to main content

​
Authentication Overview

NATS Server supports multiple authentication mechanisms to verify client identities. You can choose the method that best fits your security requirements and infrastructure.

​
Authentication Methods

NATS provides four primary authentication methods:
  1. Token-based authentication - Simple shared secret
  2. Username/password authentication - Traditional credentials
  3. NKeys authentication - Cryptographic public-key authentication
  4. JWT-based authentication - Decentralized authentication with claims

​
Token-Based Authentication

The simplest authentication method using a shared secret token.

​
Server Configuration

authorization {
  token: "secret_token_here"
}
Or via command line: 
nats-server --auth secret_token_here

​
Client Connection

nats-cli pub test "hello" --server="nats://secret_token_here@localhost:4222"
Token authentication is suitable for development but should not be used in production. Prefer NKeys or JWT authentication.

​
Username/Password Authentication

Traditional username and password credentials.

​
Single User

authorization {
  user: "admin"
  password: "$2a$11$W2zko4z4nZC5z6o7FPNbO.4qGOsQWiPCqQ3O0kJLKLQP5WtHLx4KW"
}
Or via command line: 
nats-server --user admin --pass secret_password

​
Multiple Users

authorization {
  users = [
    {
      user: "alice"
      password: "$2a$11$..."
    }
    {
      user: "bob"
      password: "$2a$11$..."
      permissions: {
        publish: ["events.>"]
        subscribe: ["results.bob.>"]
      }
    }
  ]
}

​
Password Hashing with BCrypt

Never store plaintext passwords. Use bcrypt hashing: 
# Generate bcrypt hash
nats server passwd
Enter password: ****
Reenter password: ****
$2a$11$W2zko4z4nZC5z6o7FPNbO.4qGOsQWiPCqQ3O0kJLKLQP5WtHLx4KW
The server warns if plaintext passwords are detected in the configuration.

​
Connection Deadlines

Expire user credentials after a specific time: 
authorization {
  users = [
    {
      user: "temporary"
      password: "$2a$11$..."
      connection_deadline: "2026-12-31T23:59:59Z"
    }
  ]
}

​
NKeys Authentication

Cryptographic authentication using Ed25519 public-key signatures. This is the recommended authentication method.

​
How NKeys Work

  1. Server generates a random nonce
  2. Client signs the nonce with its private NKey
  3. Server verifies the signature using the public NKey
  4. No passwords transmitted over the network

​
Generating NKeys

# Generate a user NKey
nats-server -k user
Output: 
User public key: UCKASD5KPQQYHB6KYD7RC62VZQN7VRU5NN2BKL7UFBQ3UBYAJQPVNHSQ
User private key: SUACSSL3UAHUDXKFSNVUZRF5UHPMWZ6BFDTJ7M6USDXIEDNPPQYYYCU3VY
Store the private key securely. Never commit it to version control.

​
Server Configuration

​
Single NKey User

authorization {
  users = [
    {nkey: "UCKASD5KPQQYHB6KYD7RC62VZQN7VRU5NN2BKL7UFBQ3UBYAJQPVNHSQ"}
  ]
}

​
Multiple NKey Users

authorization {
  users = [
    {
      nkey: "UCKASD5KPQQYHB6KYD7RC62VZQN7VRU5NN2BKL7UFBQ3UBYAJQPVNHSQ"
      permissions: {
        publish: ["orders.>"]
        subscribe: ["results.>"]
      }
    }
    {
      nkey: "UDIBRYX7D2S2IXMOV4ABWSH5TJCF5YLQT3V7KTKSW5MBTXNBD7WKEWXY"
      permissions: {
        publish: ["events.>"]
        subscribe: ["_INBOX.>"]
      }
    }
  ]
}

​
With Account Assignment

accounts {
  ORDERS: {
    users: [
      {nkey: "UCKASD5KPQQYHB6KYD7RC62VZQN7VRU5NN2BKL7UFBQ3UBYAJQPVNHSQ"}
    ]
  }
}

​
Client Configuration

Clients use a credentials file containing the NKey: user.creds: 
-----BEGIN NATS USER JWT-----
eyJ0eXAiOiJKV1QiLCJhbGciOiJlZDI1NTE5LW5rZXkifQ...
------END NATS USER JWT------

************************* IMPORTANT *************************
NKEY Seed printed below can be used to sign and prove identity.
NKEYs are sensitive and should be treated as secrets.

-----BEGIN USER NKEY SEED-----
SUACSL3UAHUDXKFSNVUZRF5UHPMWZ6BFDTJ7M6USDXIEDNPPQYYYCU3VY
------END USER NKEY SEED------

*************************************************************
Connect using credentials: 
nats-cli pub test "hello" --creds=user.creds

​
JWT-Based Authentication

JWT (JSON Web Token) authentication enables decentralized auth with signed claims. This is the most sophisticated authentication method.

​
Operator Mode

Operator mode uses a hierarchical trust model: 
Operator (root trust)
  └── Account (signed by operator)
       └── User (signed by account)

​
Server Configuration

operator: "/path/to/operator.jwt"

resolver: {
  type: full
  dir: "/path/to/jwt/accounts"
}

​
Account JWT Example

Account JWTs define account-level claims: 
{
  "jti": "ACCOUNT_ID",
  "iat": 1234567890,
  "iss": "OPERATOR_KEY",
  "name": "Production",
  "sub": "AAAA...",
  "nats": {
    "limits": {
      "conn": 1000,
      "subs": -1,
      "payload": 1048576,
      "data": -1
    },
    "default_permissions": {
      "pub": {},
      "sub": {}
    }
  }
}

​
User JWT Example

User JWTs define user-level claims and permissions: 
{
  "jti": "USER_ID",
  "iat": 1234567890,
  "iss": "ACCOUNT_KEY",
  "name": "Alice",
  "sub": "UCKA...",
  "nats": {
    "pub": {
      "allow": ["orders.>"]
    },
    "sub": {
      "allow": ["results.>", "_INBOX.>"]
    },
    "subs": -1,
    "data": -1,
    "payload": -1
  }
}

​
Dynamic Updates

JWT authentication supports dynamic updates without server restarts:
  1. Update account or user JWT in the resolver
  2. Server automatically picks up changes
  3. Active connections continue with old credentials
  4. New connections use updated credentials

​
Account Signing Keys

Accounts can delegate user signing to scoped keys: 
accounts {
  PROD: {
    signing_keys: [
      "ADKXVKMR3VF7JXJK7H3KVZJFG7WR7SWZ7GBFZ6U5D4NBJQABTQUWZDJM"
    ]
  }
}

​
Authentication Callouts

Authentication can be delegated to an external service via the callout mechanism.

​
Server Configuration

accounts {
  AUTH: {
    users: [{nkey: "AUTH_SERVICE_NKEY"}]
  }
}

authorization {
  auth_callout: {
    issuer: "AUTH_ACCOUNT_KEY"
    account: "AUTH"
    auth_users: ["AUTH_SERVICE_NKEY"]
  }
}

​
Callout Flow

  1. Client connects to server
  2. Server publishes authentication request to $SYS.REQ.USER.AUTH
  3. Auth service validates credentials
  4. Auth service responds with signed User JWT
  5. Server grants access based on JWT claims

​
Encrypted Callouts

Callout requests and responses can be encrypted: 
authorization {
  auth_callout: {
    issuer: "ACCOUNT_KEY"
    account: "AUTH"
    xkey: "XABC..."  # XKey for encryption
  }
}

​
TLS Certificate Mapping

Map TLS certificate properties to users: 
tls {
  cert_file: "server.pem"
  key_file: "server-key.pem"
  ca_file: "ca.pem"
  verify: true
  map_and_verify: true
}

authorization {
  users = [
    {
      user: "CN=alice,O=Company"
      permissions: {
        publish: ["orders.>"]
      }
    }
  ]
}

​
Authentication Timeouts

Clients must authenticate within the timeout: 
authorization {
  timeout: 2.0  # seconds
}
Or via command line: 
nats-server --auth_timeout 2

Build docs developers (and LLMs) love

Get started for freeTalk to us