NATS Logo by Example

Configuring the System Account in Authentication and Authorization

NATS has the notion of a system account which is a designated account for operations and monitoring of the server, cluster, or supercluster. Although there is an implicit system account created on the server, there are no users associated with it, by default.

This example showcases the minimal configuration required to define a user associated with the default system account. This will allow us to run administrative commands using the nats CLI.

For the decentralized JWT authentication method, configuring the system account is a slightly different process that will be highlighted in a separate example.

CLI Go Python JavaScript Rust C# .NET V2 Java Ruby Elixir Crystal C
Jump to the output or the recording
$ nbe run auth/sys-account/cli
View the source code or learn how to run this example yourself

Code

#!/bin/sh


set -uo pipefail


NATS_URL=nats://localhost:4222

First, we will create an empty configuration file and startup a server in the background.

touch server.conf


nats-server -c server.conf > /dev/null 2>&1 &


sleep 0.5

If we try to run a command requests server info, we will get back an error indicating we need “system privileges” and “appropriate permissions” 🤔.

nats server info

NATS has this default system account named $SYS which is dedicated for server operations and monitoring. To activate we need to define a user associated with this account. We can do this by updating our config file with the accounts block.

cat <<- EOF > server.conf
accounts: {
  \$SYS: {
    users: [{user: sys, password: pass}]
  }
}
EOF

Simply reload the server with the --signal option.

nats-server --signal reload


nats-server -c server.conf > /dev/null 2>&1 &



For convenience, and so we don’t type the password on the command line, we can save a new sys context.

nats context save sys \
  --user sys \
  --password pass

Now we can try getting the server info again. We need to set the user and password.

nats --context sys server info

There is another option to change the default system account name which is required when using the decentralized JWT auth method. However, we will demonstrate here. We can define a new account and then set the system_account option to the account to use.

cat <<- EOF > server.conf
accounts: {
  MYSYS: {
    users: [{user: sys, password: pass}]
  }
}


system_account: MYSYS
EOF

We will reload again and then run the command again with out custom account system account.

nats-server --signal reload


nats --context sys server info

Output

nats: error: no results received, ensure the account used has system privileges and appropriate permissions
NATS Configuration Context "sys"

  Server URLs: nats://127.0.0.1:4222
     Username: sys
     Password: ****
         Path: /root/.config/nats/context/sys.json

Server information for NAIMXQHGXWTPFMHK5FSHRH7H4SDVTXDUOPJ5AQBE2G6RYNWFHKKVZBBU

Process Details:

           Version: 2.10.1
        Git Commit: 
        Go Version: go1.21.3
        Start Time: 2023-10-23 19:30:16
  Config Load Time: 2023-10-23 19:30:17
            Uptime: 0s

Connection Details:

     Auth Required: true
      TLS Required: false
              Host: 0.0.0.0:4222

Limits:

          Max Conn: 65,536
          Max Subs: 0
       Max Payload: 1.0 MiB
       TLS Timeout: 2.00s
    Write Deadline: 10.00s

Statistics:

         CPU Cores: 8 0.00%
            Memory: 11 MiB
       Connections: 1
     Subscriptions: 55
          Messages: 2 in 0 out
             Bytes: 4 B in 0 B out
    Slow Consumers: 0
Server information for NAIMXQHGXWTPFMHK5FSHRH7H4SDVTXDUOPJ5AQBE2G6RYNWFHKKVZBBU

Process Details:

           Version: 2.10.1
        Git Commit: 
        Go Version: go1.21.3
        Start Time: 2023-10-23 19:30:16
  Config Load Time: 2023-10-23 19:30:17
            Uptime: 0s

Connection Details:

     Auth Required: true
      TLS Required: false
              Host: 0.0.0.0:4222

Limits:

          Max Conn: 65,536
          Max Subs: 0
       Max Payload: 1.0 MiB
       TLS Timeout: 2.00s
    Write Deadline: 10.00s

Statistics:

         CPU Cores: 8 0.00%
            Memory: 11 MiB
       Connections: 1
     Subscriptions: 55
          Messages: 3 in 1 out
             Bytes: 6 B in 1.3 KiB out
    Slow Consumers: 0

Recording

Note, playback is half speed to make it a bit easier to follow.