NATS20NSCMode.md

NATS20NSCInst.md

Setting up NATS 2.0 Security

Install the tools

nats-server

go get github.com/nats-io/nats-server

nsc

curl -L https://raw.githubusercontent.com/nats-io/nsc/master/install.py | python

Setup the Operator JWT

$ nsc add operator -n AcmeCorporation
Generated operator key - private key stored "~/.nkeys/AcmeCorporation/AcmeCorporation.nk"
Success! - added operator "AcmeCorporation"

Save the generated NKEY (*.nk file) someplace very safe.

You'll need to reference the operator's JWT, so save that someplace accessible by the nats-account-server.

Setup the NATS server

This is all you need! Reference the operator JWT, and the resolver. In this case, we'll use the directory store, which is mutable, so operators can add and remove users and accounts.

operator: <this directory>/.nsc/nats/AcmeCorporation/AcmeCorporation.jwt
resolver: URL(http://localhost:9090/jwt/v1/accounts/)

Setup the NATS account server

http: {
  host: "localhost",
  port: 9090,
  readtimeout: 5000,
  writetimeout: 5000,
}

# Reference the operator JWT.
OperatorJWTPath: /Users/colinsullivan/.nsc/nats/AcmeCorporation/AcmeCorporation.jwt

# This is the location of the store, where public account JWTs will be
# uploaded.
store: {
    nsc: /Users/colinsullivan/.nsc/AcmeCorporation
}

Create an account JWT

This would be done by the operator, or administrator.

$ nsc add account -n Acme
Generated account key - private key stored "~/.nkeys/AcmeCorporation/accounts/Acme/Acme.nk"
Success! - added account "Acme"

Find the public NKEY of the account

$ nsc describe jwt -W -f ~/.nsc/nats/AcmeCorporation/accounts/Acme/Acme.jwt | grep "Account ID"
│ Account ID                │ AAHC5D6GVMRI753MOVEIEV2LVR3C7GUCYLAOHQH5DL5V7M6CXSYGWZRK │

Create a user for your connecting applications

$ nsc add user -n Colin
Generated user key - private key stored "~/.nkeys/AcmeCorporation/accounts/Acme/users/Colin.nk"
Generated user creds file "~/.nkeys/AcmeCorporation/AcmeCorporation/Acme/users/Colin.creds"
Success! - added user "Colin" to "Acme"

Test the user:

$ nats-pub -creds ~/.nkeys/AcmeCorporation/accounts/Acme/users/Colin.creds foo bar
Published [foo] : 'bar'

Advanced

NATS Alerts

To enable NATS alerts, create a user to connect to NATS and publish alerts. In this case, we've created a user account-user.

Setup NATS connectivity in the NATS account server by adding the following stanza:

nats: {
  Servers: ["localhost:4222"],
  ConnectTimeout: 5000,
  MaxReconnects: 5,
  ReconnectWait: 5000,
  UserCredentials: /Users/colinsullivan/.nkeys/AcmeCorporation/accounts/Acme/users/account-server.creds
}

The account server will connect to the NATS server to publish account related events. You'll see statements like this:

2019/05/13 17:39:31.905301 [ERR] failed to connect to NATS, nats: no servers available for connection
2019/05/13 17:39:31.905319 [ERR] will try to connect again in 5000 milliseconds
2019/05/13 17:39:36.908554 [INF] connecting to NATS for notifications

System Account

You can create a system account for generating alearts, usage, etc. It's simply a user you define.

$ nsc add account -n SYS
Generated account key - private key stored "~/.nkeys/AcmeCorporation/accounts/SYS/SYS.nk"
Success! - added account "SYS"

$ nsc add user -n SYSU
Generated user key - private key stored "~/.nkeys/AcmeCorporation/accounts/SYS/users/SYSU.nk"
Generated user creds file "~/.nkeys/AcmeCorporation/accounts/SYS/users/SYSU.creds"
Success! - added user "SYSU" to "SYS"

Add the system account to the NATS server and account server. In your account server configuration add:

SystemAccountJWTPath: /Users/colinsullivan/.nsc/nats/AcmeCorporation/accounts/SYS/SYS.jwt

In the NATS server configuration, add:

system: <system account public key>

Reload or bounce the NATS server.

At this point, you can import the sys account into other accounts, or use the system account credentials to listen:

 $ nats-sub --creds ~/.nkeys/AcmeCorporation/accounts/SYS/users/SYSU.creds ">"
Listening on [>]
[#1] Received on [$SYS.SERVER.NAU6IMZULWID6FGHNUEJFZS5SIFD5H3N73DWZ7SVYZF4QZ4W24LKLJKX.STATSZ]: '{
  "server": {
    "host": "0.0.0.0",
    "id": "NAU6IMZULWID6FGHNUEJFZS5SIFD5H3N73DWZ7SVYZF4QZ4W24LKLJKX",
    "ver": "2.0.0-RC12",
    "seq": 9,
    "time": "2019-05-21T16:03:16.040694-06:00"
  },
  "statsz": {
    "start": "2019-05-21T16:01:46.021341-06:00",
    "mem": 11448320,
    "cores": 8,
    "cpu": 0,
    "connections": 3,
    "total_connections": 4,
    "active_accounts": 2,
    "subscriptions": 10,
    "sent": {
      "msgs": 0,
      "bytes": 0
    },
    "received": {
      "msgs": 0,
      "bytes": 0
    },
    "slow_consumers": 0
  }
}'

Importing and exporting data

Let's import some of the data from the SYS account into our Acme account.

First create and upload another account:

nsc add account -n PublicServices nsc create user -n PublicServiceUser

Export a service from the PublicServices account

Note that we are already working on the PublicServices account.

 $ nsc add export --name "TicketService" --subject "generate.ticket" --service
Success! - added public service export "TicketService"

You've locally updated your account to have a public TicketService exposed on subject generate.ticket. The changes are local, so now upload it with curl.

Import the service from the Acme account

Let's change the account we're working on:

 $ nsc env -a Acme
 $

Now we'll add an import to the account:

Get the account ID from the list the accounts:

$ nsc describe jwt -W -f /Users/colinsullivan/.nsc/nats/AcmeCorporation/accounts/PublicServices/PublicServices.jwt | grep "Account ID"
│ Account ID                │ ADGDN5CFZMDLGU64MOFQOVCVZZ2RB7PMXXDGEQZKNRJPGW5JAV3GKIFE │

Now add the import.

$ nsc add import --src-account ADGDN5CFZMDLGU64MOFQOVCVZZ2RB7PMXXDGEQZKNRJPGW5JAV3GKIFE --name TicketService --remote-subject generate.ticket --service
Success! - added service import "generate.ticket"

Restart the NATS server.

Test your service

$ ./nats-rply --creds ~/.nkeys/AcmeCorporation/accounts/PublicServices/users/PublicServiceUser.creds "generate.ticket" "A ticket for you"
Listening on [generate.ticket]
[#1] Received on [generate.ticket]: '1234'

Make the request:

$ nats-req --creds ~/.nkeys/AcmeCorporation/accounts/Acme/users/Colin.creds generate.ticket 1234
Published [generate.ticket] : '1234'
Received  [_INBOX.lcNdEvPWJgViyD89f8tdPj.kewEfJ97] : 'A ticket for you'