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 Deno Node Rust C# Java Ruby Elixir 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 -xuo pipefail

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

touch server.conf


nats-server -c server.conf -l log.txt & 
SERVER_PID=$!


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=$SERVER_PID

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=$SERVER_PID
nats --context sys server info


kill $SERVER_PID

Output

Network 0e66dc3e_default  Creating
Network 0e66dc3e_default  Created
             _             _               
 _ __   __ _| |_ ___      | |__   _____  __
| '_ \ / _` | __/ __|_____| '_ \ / _ \ \/ /
| | | | (_| | |_\__ \_____| |_) | (_) >  < 
|_| |_|\__,_|\__|___/     |_.__/ \___/_/\_\
                                           
nats-box v0.12.0
+ touch server.conf
+ SERVER_PID=13
+ sleep 0.5
+ nats-server -c server.conf -l log.txt
+ nats server info
nats: error: no results received, ensure the account used has system privileges and appropriate permissions, try --help
+ cat
+ nats-server --signal 'reload=13'
+ nats context save sys --user sys --password pass
NATS Configuration Context "sys"

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

+ nats --context sys server info
Server information for NB2MEK5VEFZGMLMCV35G557VTY3NJVOUIAJC2H42I5PXRLYWDZ4CYRKY

Process Details:

         Version: 2.8.4
      Git Commit: 66524ed
      Go Version: go1.17.10
      Start Time: 2022-08-01 18:55:25.918663239 +0000 UTC
          Uptime: 0s

Connection Details:

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

Limits:

        Max Conn: 65536
        Max Subs: 0
     Max Payload: 1.0 MiB
     TLS Timeout: 2s
  Write Deadline: 10s

Statistics:

       CPU Cores: 2 0.00%
          Memory: 11 MiB
     Connections: 1
   Subscriptions: 37
            Msgs: 1 in 0 out
           Bytes: 2 B in 0 B out
  Slow Consumers: 0

+ cat
+ nats-server --signal 'reload=13'
+ nats --context sys server info
Server information for NB2MEK5VEFZGMLMCV35G557VTY3NJVOUIAJC2H42I5PXRLYWDZ4CYRKY

Process Details:

         Version: 2.8.4
      Git Commit: 66524ed
      Go Version: go1.17.10
      Start Time: 2022-08-01 18:55:25.918663239 +0000 UTC
          Uptime: 0s

Connection Details:

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

Limits:

        Max Conn: 65536
        Max Subs: 0
     Max Payload: 1.0 MiB
     TLS Timeout: 2s
  Write Deadline: 10s

Statistics:

       CPU Cores: 2 0.00%
          Memory: 11 MiB
     Connections: 1
   Subscriptions: 37
            Msgs: 2 in 1 out
           Bytes: 4 B in 1.2 KiB out
  Slow Consumers: 0

+ kill 13

Recording

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