mirror of
https://github.com/taigrr/nats.docs
synced 2025-01-18 04:03:23 -08:00
Merge pull request #19 from nats-io/account-server
- added tutorial on generating a mem resolver config using nsc.
This commit is contained in:
Ginger Collison
GitHub
commit
a1400987ab
@ -119,6 +119,7 @@
|
||||
* [nats-account-server](nats_tools/nas/README.md)
|
||||
* [Basics](nats_tools/nas/nas_conf.md)
|
||||
* [Inspecting JWTs](nats_tools/nas/inspecting_jwts.md)
|
||||
* [Directory Store](nats_tools/nas/dir_store.md)
|
||||
* [Memory Resolver](nats_tools/nas/mem_resolver.md)
|
||||
* [nats-top](nats_tools/nats_top/README.md)
|
||||
* [Tutorial](nats_tools/nats_top/tutorial.md)
|
||||
|
||||
@ -4,21 +4,99 @@
|
||||
### NATS Account Server Configuration
|
||||
|
||||
```
|
||||
OperatorJWTPath: "/users/synadia/.nsc/nats/Test/Test.jwt",
|
||||
OperatorJWTPath: "/users/synadia/.nsc/nats/AAA/AAA.jwt",
|
||||
http {
|
||||
port: 9090
|
||||
port: 9090
|
||||
},
|
||||
store {
|
||||
dir: "/tmp/as_store",
|
||||
readonly: false,
|
||||
shard: true
|
||||
dir: "/tmp/as_store",
|
||||
readonly: false,
|
||||
shard: true
|
||||
}
|
||||
```
|
||||
|
||||
### To Add/Update a JWT
|
||||
The server configuration specifies the `OperatorJWTPath` which is used to validate accounts submitted to the server. If an account is not signed by the specified operator, the update is rejected.
|
||||
|
||||
Starting the server:
|
||||
|
||||
```
|
||||
> nats-account-server -c nas.conf
|
||||
2019/05/31 12:35:23.430128 [INF] loading configuration from "/Users/synadia/Desktop/nats_jwt_doc/as_dir/nas.conf"
|
||||
2019/05/31 12:35:23.430417 [INF] starting NATS Account server, version 0.0-dev
|
||||
2019/05/31 12:35:23.430434 [INF] server time is Fri May 31 12:35:23 CDT 2019
|
||||
2019/05/31 12:35:23.430462 [INF] loading operator from /users/synadia/.nsc/nats/AAA/AAA.jwt
|
||||
2019/05/31 12:35:23.430919 [INF] creating a store at /tmp/as_store
|
||||
2019/05/31 12:35:23.430948 [INF] NATS is not configured, server will not fire notifications on update
|
||||
2019/05/31 12:35:23.437938 [INF] http listening on port 9090
|
||||
2019/05/31 12:35:23.437953 [INF] nats-account-server is running
|
||||
2019/05/31 12:35:23.437956 [INF] configure the nats-server with:
|
||||
2019/05/31 12:35:23.437966 [INF] resolver: URL(http://localhost:9090/jwt/v1/accounts/)
|
||||
```
|
||||
|
||||
On a new store, the server doesn't have any JWTs. This means that any nats-server that attempts to resolve accounts will fail. To add JWTs to the server, you can use a tool like [`curl` to post request](#add/using-curl-to-add-or-update-accounts). But it is much easier if you use `nsc` to update the nats-account-server.
|
||||
|
||||
### Using NSC to And or Update Accounts
|
||||
|
||||
The `nsc` tool has built-in facilities to `push` JWTs related to an operator. The tool also performs validation of your JWTs to ensure that you push JWTs that will validate correctly.
|
||||
|
||||
If your operator doesn't have any entities, now it is a good time to add some:
|
||||
|
||||
```
|
||||
> nsc add account -n A
|
||||
Generated account key - private key stored "~/.nkeys/AAA/accounts/A/A.nk"
|
||||
Success! - added account "A"
|
||||
|
||||
> nsc add user -n u1
|
||||
Generated user key - private key stored "~/.nkeys/AAA/accounts/A/users/u1.nk"
|
||||
Generated user creds file "~/.nkeys/AAA/accounts/A/users/u1.creds"
|
||||
Success! - added user "u1" to "A"
|
||||
|
||||
> nsc add user -n u2
|
||||
Generated user key - private key stored "~/.nkeys/AAA/accounts/A/users/u2.nk"
|
||||
Generated user creds file "~/.nkeys/AAA/accounts/A/users/u2.creds"
|
||||
Success! - added user "u2" to "A"
|
||||
|
||||
> nsc add account -n B
|
||||
Generated account key - private key stored "~/.nkeys/AAA/accounts/B/B.nk"
|
||||
Success! - added account "B"
|
||||
```
|
||||
|
||||
With the account and a couple of users in place, let's push all the accounts to the nats-account-server:
|
||||
|
||||
```
|
||||
> nsc push -A
|
||||
successfully pushed all accounts [A,B]
|
||||
```
|
||||
|
||||
Quick checking of the store directory, shows that the JWTs have been sharded by their public keys:
|
||||
```
|
||||
> tree as_store
|
||||
as_store
|
||||
├── 27
|
||||
│ └── ACVEO3LPVRGE5W262FCYF3OMGQFJIW252AX75FEE6BUY752BFVDADN27.jwt
|
||||
└── TY
|
||||
└── ADDVBX4VPWSNEDLWH5Y6ITASMXS3QY3L6KRNZ6VIQJ6Q3FRGR43NFHTY.jwt
|
||||
```
|
||||
|
||||
Quick check on nsc to verify the ids of the accounts on nsc, match the files:
|
||||
```
|
||||
> nsc list accounts -W
|
||||
╭─────────────────────────────────────────────────────────────────╮
|
||||
│ Accounts │
|
||||
├──────┬──────────────────────────────────────────────────────────┤
|
||||
│ Name │ Public Key │
|
||||
├──────┼──────────────────────────────────────────────────────────┤
|
||||
│ A │ ACVEO3LPVRGE5W262FCYF3OMGQFJIW252AX75FEE6BUY752BFVDADN27 │
|
||||
│ B │ ADDVBX4VPWSNEDLWH5Y6ITASMXS3QY3L6KRNZ6VIQJ6Q3FRGR43NFHTY │
|
||||
╰──────┴──────────────────────────────────────────────────────────╯
|
||||
```
|
||||
|
||||
|
||||
|
||||
### Using Curl to Add or Update Accounts
|
||||
|
||||
```
|
||||
> curl -i -X POST localhost:9090/jwt/v1/accounts/AC7PO3MREV26U3LFZFP5BN3HAI32X3PKLBRVMPAETLEHWPQEUG7EJY4H --data-binary @/Users/synadia/.nsc/nats/Test/accounts/TestAccount/TestAccount.jwt -H "Content-Type: text/text"
|
||||
```
|
||||
|
||||
Note that the `@` before the file name is required for curl to read the specified file, and use it as the payload. Otherwise it will simply post the path specified, which will result in an update error.
|
||||
Note that the `@` before the file name is required for `curl` to read the specified file, and use it as the payload. Otherwise, it will simply post the path specified, which will result in an update error.
|
||||
@ -1,6 +1,6 @@
|
||||
## Memory Resolver
|
||||
|
||||
The `MEMORY` resolver is a built-in resolver for JWTs. It is mostly used by test setups but can be used to test the simplest of environments where there is one or very few accounts, and the account JWTs don’t change often.
|
||||
The `MEMORY` resolver is a built-in resolver for JWTs. It is mostly used by test setups but can be used to test the simplest of environments where there is one or very few accounts, and the account JWTs don't change often.
|
||||
|
||||
The basic configuration for the server requires:
|
||||
|
||||
@ -11,15 +11,15 @@ The basic configuration for the server requires:
|
||||
|
||||
### Create Required Entities
|
||||
|
||||
Let’s create the setup:
|
||||
Let's create the setup:
|
||||
|
||||
```text
|
||||
> nsc add operator -n memory
|
||||
Generated operator key - private key stored "/Users/synadia/.nkeys/memory/memory.nk"
|
||||
Generated operator key - private key stored "~/.nkeys/memory/memory.nk"
|
||||
Success! - added operator "memory"
|
||||
|
||||
> nsc add account --name A
|
||||
Generated account key - private key stored "/Users/synadia/.nkeys/memory/accounts/A/A.nk"
|
||||
Generated account key - private key stored "~/.nkeys/memory/accounts/A/A.nk"
|
||||
Success! - added account "A"
|
||||
|
||||
> nsc describe account -W
|
||||
@ -45,18 +45,52 @@ Success! - added account "A"
|
||||
│ Exports │ None │
|
||||
╰───────────────────────────┴──────────────────────────────────────────────────────────╯
|
||||
|
||||
> cat /Users/synadia/.nsc/nats/memory/accounts/A/A.jwt
|
||||
eyJ0eXAiOiJqd3QiLCJhbGciOiJlZDI1NTE5In0.eyJqdGkiOiJPRFhJSVI2Wlg1Q1AzMlFJTFczWFBENEtTSDYzUFNNSEZHUkpaT05DR1RLVVBISlRLQ0JBIiwiaWF0IjoxNTU2NjU1Njk0LCJpc3MiOiJPRFdaSjJLQVBGNzZXT1dNUENKRjZCWTRRSVBMVFVJWTRKSUJMVTRLM1lERzNHSElXQlZXQkhVWiIsIm5hbWUiOiJBIiwic3ViIjoiQUNTVTNRNkxUTEJWTEdBUVVPTkFHWEpIVk5XR1NLS0FVQTdJWTVUQjRaN1BMRUtTUjVPNkpUR1IiLCJ0eXBlIjoiYWNjb3VudCIsIm5hdHMiOnsibGltaXRzIjp7InN1YnMiOi0xLCJjb25uIjotMSwibGVhZiI6LTEsImltcG9ydHMiOi0xLCJleHBvcnRzIjotMSwiZGF0YSI6LTEsInBheWxvYWQiOi0xLCJ3aWxkY2FyZHMiOnRydWV9fX0._WW5C1triCh8a4jhyBxEZZP8RJ17pINS8qLzz-01o6zbz1uZfTOJGvwSTS6Yv2_849B9iUXSd-8kp1iMXHdoBA
|
||||
|
||||
> nsc add user --name TA
|
||||
Generated user key - private key stored “/Users/synadia/.nkeys/memory/accounts/A/users/TA.nk"
|
||||
Generated user creds file “/Users/synadia/.nkeys/memory/accounts/A/users/TA.creds"
|
||||
Generated user key - private key stored "~/.nkeys/memory/accounts/A/users/TA.nk"
|
||||
Generated user creds file "~/.nkeys/memory/accounts/A/users/TA.creds"
|
||||
Success! - added user "TA" to "A"
|
||||
```
|
||||
|
||||
### Create the Server Config
|
||||
|
||||
With the above entries, we can reference the operator JWT and the account JWT in a server configuration. Remember that your configuration will be in `$NSC_HOME/nats/<operator_name>/<operator_name>.jwt` for the operator. The account JWT will be in `$NSC_HOME/nats/<operator_name>/accounts/<account_name>/<account_name>.jwt`
|
||||
The `nsc` tool can generate a configuration file automatically. You provide a path to the server configuration and operator jwt. The `nsc` tool will copy the operator JWT to the file specified, and generate the server config for you:
|
||||
|
||||
`"
|
||||
> nsc generate config --mem-resolver --config-file /tmp/server.conf --operator-jwt /tmp/memory.jwt
|
||||
Success!! - generated "/tmp/server.conf"
|
||||
generated "/tmp/memory.jwt"
|
||||
```
|
||||
|
||||
If you require additional settings, you may want to consider using [`include`](/nats_server/configuration.md#include-directive) in your main configuration, to reference the generated files. Otherwise, you can start a server and reference the generated configuration:
|
||||
|
||||
`"
|
||||
> nats-server -c /tmp/server.conf
|
||||
`"
|
||||
|
||||
You can then [test it](#testing-the-configuration).
|
||||
|
||||
|
||||
### Manual Server Config
|
||||
|
||||
While generating a configuration file is easy, you may want to craft one by hand to know the details. With the entities created, and a standard location for the `.nsc` directory. You can reference the operator JWT and the account JWT in a server configuration. Remember that your configuration will be in `$NSC_HOME/nats/<operator_name>/<operator_name>.jwt` for the operator. The account JWT will be in `$NSC_HOME/nats/<operator_name>/accounts/<account_name>/<account_name>.jwt`
|
||||
|
||||
For the configuration you'll need:
|
||||
|
||||
- The path to the operator JWT
|
||||
- A copy of the contents of the account JWT file
|
||||
|
||||
The format of the file is:
|
||||
|
||||
`"
|
||||
operator: <path to the operator jwt>
|
||||
resolver: MEMORY
|
||||
resolver_preload: {
|
||||
<public key for an account>: <contents of the account jwt>
|
||||
### add as many accounts as you want
|
||||
...
|
||||
}
|
||||
|
||||
In this example this translates to:
|
||||
|
||||
```text
|
||||
operator: /Users/synadia/.nsc/nats/memory/memory.jwt
|
||||
@ -69,10 +103,15 @@ ACSU3Q6LTLBVLGAQUONAGXJHVNWGSKKAUA7IY5TB4Z7PLEKSR5O6JTGR: eyJ0eXAiOiJqd3QiLCJhbG
|
||||
Save the config at server.conf and start the server:
|
||||
```text
|
||||
> nats-server -c server.conf
|
||||
```
|
||||
`"
|
||||
|
||||
You can then [test it](#testing-the-configuration).
|
||||
|
||||
### Testing the Configuration
|
||||
|
||||
To test the configuration, simply use one of the standard tools:
|
||||
|
||||
Start a subscriber:
|
||||
```text
|
||||
> nats-sub -creds /Users/synadia/.nkeys/memory/accounts/A/users/TA.creds ">"
|
||||
Listening on [>]
|
||||
> nats-pub -creds ~/.nkeys/memory/accounts/A/users/TA.creds hello world
|
||||
Published [hello] : 'world'
|
||||
```
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user