mirror of
https://github.com/taigrr/nats.docs
synced 2025-01-18 04:03:23 -08:00
GitBook: [master] 326 pages and 16 assets modified
This commit is contained in:
committed by
gitbook-bot
parent
8b7ba5c3bb
commit
fb0d5c8355
20
nats-tools/nas/README.md
Normal file
20
nats-tools/nas/README.md
Normal file
@@ -0,0 +1,20 @@
|
||||
# nats-account-server
|
||||
|
||||
The [NATS Account Server](https://github.com/nats-io/nats-account-server) is an HTTP server that hosts and vends JWTs for nats-server 2.0 account authentication. The server supports an number of stores which enable it to serve JWTs from:
|
||||
|
||||
* a directory
|
||||
* an [NSC](../nsc/nsc.md) directory
|
||||
* memory \(for testing purposes\)
|
||||
|
||||
The server can operate in a _READ ONLY_ mode where it serves content from a directory, or in notification mode, where it can notify a NATS server that a JWT in the store has been modified, updating the NATS server with the updated JWT.
|
||||
|
||||
The server supports replica mode, which allows load balancing, fault tolerance and geographic distribution of servers. Replicas are read-only and copy JWTs from the primary based on cache invalidation or NATS notifications.
|
||||
|
||||
The account server can host activation tokens as well as account JWTs. These tokens are used when one account needs to give permission to another account to access a private export. Tokens can be configured as full tokens, or URLs. By hosting them in the account server you can avoid the copy/paste process of embedding tokens. They can also be updated more easily on expiration.
|
||||
|
||||
## Memory Resolver
|
||||
|
||||
For very simple installations, where JWTs are mostly static, the NATS server also supports a _Memory Resolver_ that can be configured statically in the server's configuration file.
|
||||
|
||||
You can learn more about how to configure the [memory resolver here](mem_resolver.md).
|
||||
|
||||
102
nats-tools/nas/dir_store.md
Normal file
102
nats-tools/nas/dir_store.md
Normal file
@@ -0,0 +1,102 @@
|
||||
# Directory Store
|
||||
|
||||
## NATS Account Server Configuration
|
||||
|
||||
```text
|
||||
OperatorJWTPath: "/users/synadia/.nsc/nats/AAA/AAA.jwt",
|
||||
http {
|
||||
port: 9090
|
||||
},
|
||||
store {
|
||||
dir: "/tmp/as_store",
|
||||
readonly: false,
|
||||
shard: true
|
||||
}
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```text
|
||||
> 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](dir_store.md#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:
|
||||
|
||||
```text
|
||||
> 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:
|
||||
|
||||
```text
|
||||
> 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:
|
||||
|
||||
```text
|
||||
> 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:
|
||||
|
||||
```text
|
||||
> nsc list accounts -W
|
||||
╭─────────────────────────────────────────────────────────────────╮
|
||||
│ Accounts │
|
||||
├──────┬──────────────────────────────────────────────────────────┤
|
||||
│ Name │ Public Key │
|
||||
├──────┼──────────────────────────────────────────────────────────┤
|
||||
│ A │ ACVEO3LPVRGE5W262FCYF3OMGQFJIW252AX75FEE6BUY752BFVDADN27 │
|
||||
│ B │ ADDVBX4VPWSNEDLWH5Y6ITASMXS3QY3L6KRNZ6VIQJ6Q3FRGR43NFHTY │
|
||||
╰──────┴──────────────────────────────────────────────────────────╯
|
||||
```
|
||||
|
||||
## Using Curl to Add or Update Accounts
|
||||
|
||||
```text
|
||||
> 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.
|
||||
|
||||
39
nats-tools/nas/inspecting_jwts.md
Normal file
39
nats-tools/nas/inspecting_jwts.md
Normal file
@@ -0,0 +1,39 @@
|
||||
# Inspecting JWTs
|
||||
|
||||
Let’s say that you know the account for a stream that you are interested in, but you don't know all the details for creating an import. If you know and have access to a nats-account-server, you can help yourself. The nats-account-server can decode a JWT and give you human readable values that you can use.
|
||||
|
||||
The endpoint for retrieving an account JWT is: `/jwt/v1/accounts/<account_id>`. To decode a JWT add the query string `?decode=true`.
|
||||
|
||||
```javascript
|
||||
> curl http://localhost:9090/jwt/v1/accounts/AC7PO3MREV26U3LFZFP5BN3HAI32X3PKLBRVMPAETLEHWPQEUG7EJY4H\?decode=true
|
||||
{
|
||||
"typ": "jwt",
|
||||
"alg": "ed25519"
|
||||
}
|
||||
{
|
||||
"jti": "5YMRO4KNMYWQDMRAHVTT4KX63CA2L3M6F4VM3S7NNGPMCCATORXQ",
|
||||
"iat": 1556229062 (2019-04-25),
|
||||
"iss": "OAYI3YUZSWDNMERD2IN3HZSIP3JA2E3VDTXSTEVOIII273XL2NABJP64",
|
||||
"name": "TestAccount",
|
||||
"sub": "AC7PO3MREV26U3LFZFP5BN3HAI32X3PKLBRVMPAETLEHWPQEUG7EJY4H",
|
||||
"type": "account",
|
||||
"nats": {
|
||||
"exports": [
|
||||
{
|
||||
"name": "abc",
|
||||
"subject": "a.b.c.>",
|
||||
"type": "stream"
|
||||
}
|
||||
],
|
||||
…
|
||||
```
|
||||
|
||||
As you can see from above, the JWT is decoded. The standard JWT claim field abbreviated names may be a little terse, so here's a list of the more important ones:
|
||||
|
||||
* `jti` is the _JWT ID_. All JWTs have one and they are unique.
|
||||
* `iat` is _Issued At_ - the UNIX date \(number of seconds since 1970\) when the JWT was issued.
|
||||
* `iss` is the _Issuer_. For NATS JWTs it is the public key of the issuer. In the example above the entity is an account, so the issuer will be an operator. Thus the id will always start with the letter `O`.
|
||||
* `sub` is the _Subject_ of the claim. In NATS JWTs it is the public key of the entity of the claim is for. In the example above, it is an Account, so the issuer will always start with the letter `A`.
|
||||
|
||||
On the example above, we see that there is one export in this account, it is public \(`token_req` is `false` or not set\), and it is a `stream`. So this account exports a public stream. With that information you can create an import on the public stream.
|
||||
|
||||
118
nats-tools/nas/mem_resolver.md
Normal file
118
nats-tools/nas/mem_resolver.md
Normal file
@@ -0,0 +1,118 @@
|
||||
# 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 basic configuration for the server requires:
|
||||
|
||||
* The operator JWT
|
||||
* `resolver` set to `MEMORY`
|
||||
* `resolver_preload` set to an object where account public keys are mapped to account JWTs.
|
||||
|
||||
## Create Required Entities
|
||||
|
||||
Let's create the setup:
|
||||
|
||||
```text
|
||||
> nsc add operator -n memory
|
||||
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 "~/.nkeys/memory/accounts/A/A.nk"
|
||||
Success! - added account "A"
|
||||
|
||||
> nsc describe account -W
|
||||
╭──────────────────────────────────────────────────────────────────────────────────────╮
|
||||
│ Account Details │
|
||||
├───────────────────────────┬──────────────────────────────────────────────────────────┤
|
||||
│ Name │ A │
|
||||
│ Account ID │ ACSU3Q6LTLBVLGAQUONAGXJHVNWGSKKAUA7IY5TB4Z7PLEKSR5O6JTGR │
|
||||
│ Issuer ID │ ODWZJ2KAPF76WOWMPCJF6BY4QIPLTUIY4JIBLU4K3YDG3GHIWBVWBHUZ │
|
||||
│ Issued │ 2019-04-30 20:21:34 UTC │
|
||||
│ Expires │ │
|
||||
├───────────────────────────┼──────────────────────────────────────────────────────────┤
|
||||
│ Max Connections │ Unlimited │
|
||||
│ Max Leaf Node Connections │ Unlimited │
|
||||
│ Max Data │ Unlimited │
|
||||
│ Max Exports │ Unlimited │
|
||||
│ Max Imports │ Unlimited │
|
||||
│ Max Msg Payload │ Unlimited │
|
||||
│ Max Subscriptions │ Unlimited │
|
||||
│ Exports Allows Wildcards │ True │
|
||||
├───────────────────────────┼──────────────────────────────────────────────────────────┤
|
||||
│ Imports │ None │
|
||||
│ Exports │ None │
|
||||
╰───────────────────────────┴──────────────────────────────────────────────────────────╯
|
||||
|
||||
> nsc add user --name TA
|
||||
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
|
||||
|
||||
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:
|
||||
|
||||
```text
|
||||
> 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/#include-directive) in your main configuration, to reference the generated files. Otherwise, you can start a server and reference the generated configuration:
|
||||
|
||||
```text
|
||||
> nats-server -c /tmp/server.conf
|
||||
```
|
||||
|
||||
You can then [test it](mem_resolver.md#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:
|
||||
|
||||
```text
|
||||
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
|
||||
resolver: MEMORY
|
||||
resolver_preload: {
|
||||
ACSU3Q6LTLBVLGAQUONAGXJHVNWGSKKAUA7IY5TB4Z7PLEKSR5O6JTGR: eyJ0eXAiOiJqd3QiLCJhbGciOiJlZDI1NTE5In0.eyJqdGkiOiJPRFhJSVI2Wlg1Q1AzMlFJTFczWFBENEtTSDYzUFNNSEZHUkpaT05DR1RLVVBISlRLQ0JBIiwiaWF0IjoxNTU2NjU1Njk0LCJpc3MiOiJPRFdaSjJLQVBGNzZXT1dNUENKRjZCWTRRSVBMVFVJWTRKSUJMVTRLM1lERzNHSElXQlZXQkhVWiIsIm5hbWUiOiJBIiwic3ViIjoiQUNTVTNRNkxUTEJWTEdBUVVPTkFHWEpIVk5XR1NLS0FVQTdJWTVUQjRaN1BMRUtTUjVPNkpUR1IiLCJ0eXBlIjoiYWNjb3VudCIsIm5hdHMiOnsibGltaXRzIjp7InN1YnMiOi0xLCJjb25uIjotMSwibGVhZiI6LTEsImltcG9ydHMiOi0xLCJleHBvcnRzIjotMSwiZGF0YSI6LTEsInBheWxvYWQiOi0xLCJ3aWxkY2FyZHMiOnRydWV9fX0._WW5C1triCh8a4jhyBxEZZP8RJ17pINS8qLzz-01o6zbz1uZfTOJGvwSTS6Yv2_849B9iUXSd-8kp1iMXHdoBA
|
||||
}
|
||||
```
|
||||
|
||||
Save the config at server.conf and start the server:
|
||||
|
||||
```text
|
||||
> nats-server -c server.conf
|
||||
```
|
||||
|
||||
You can then [test it](mem_resolver.md#testing-the-configuration).
|
||||
|
||||
## Testing the Configuration
|
||||
|
||||
To test the configuration, simply use one of the standard tools:
|
||||
|
||||
```text
|
||||
> nats-pub -creds ~/.nkeys/memory/accounts/A/users/TA.creds hello world
|
||||
Published [hello] : 'world'
|
||||
```
|
||||
|
||||
158
nats-tools/nas/nas_conf.md
Normal file
158
nats-tools/nas/nas_conf.md
Normal file
@@ -0,0 +1,158 @@
|
||||
# Basics
|
||||
|
||||
Basic configuration revolves around 4 settings:
|
||||
|
||||
* The store to read JWTs from
|
||||
* The HTTP/S configuration
|
||||
* NATS \(for cases where updates are enabled\)
|
||||
* Logging
|
||||
|
||||
For complete information on please refer to the project's [Github](https://github.com/nats-io/nats-account-server).
|
||||
|
||||
## `nsc` Configuration
|
||||
|
||||
For a basic usage of the server you can specify the `-nsc` flag, and specify the path to an operator in your environment.
|
||||
|
||||
> If you have not yet created an operator or accounts, you'll need to do so before continuing. See [NSC](../nsc/)
|
||||
|
||||
You can easily locate the path by running `nsc env` to print your `nsc` settings:
|
||||
|
||||
```text
|
||||
> nsc env
|
||||
╭──────────────────────────────────────────╮
|
||||
│ NSC Environment │
|
||||
├──────────────────┬─────┬─────────────────┤
|
||||
│ Setting │ Set │ Effective Value │
|
||||
├──────────────────┼─────┼─────────────────┤
|
||||
│ $NKEYS_PATH │ No │ ~/.nkeys │
|
||||
│ $NSC_HOME │ No │ ~/.nsc │
|
||||
│ Config │ │ ~/.nsc/nsc.json │
|
||||
├──────────────────┼─────┼─────────────────┤
|
||||
│ Stores Dir │ │ ~/.nsc/nats │
|
||||
│ Default Operator │ │ Test │
|
||||
│ Default Account │ │ TestAccount │
|
||||
│ Default Cluster │ │ │
|
||||
╰──────────────────┴─────┴─────────────────╯
|
||||
```
|
||||
|
||||
The path you are interested in the `Stores Dir`. This is the root of all operators, you'll also need the name of your operator. If your current operator is not listed, you can list all your available operators by doing:
|
||||
|
||||
```text
|
||||
> nsc list operators
|
||||
```
|
||||
|
||||
To start the `nats-account-server` with the operator `Test`:
|
||||
|
||||
```text
|
||||
> nats-account-server -nsc ~/.nsc/nats/Test
|
||||
2019/05/10 11:22:41.845148 [INF] starting NATS Account server, version 0.0-dev
|
||||
2019/05/10 11:22:41.845241 [INF] server time is Fri May 10 11:22:41 CDT 2019
|
||||
2019/05/10 11:22:41.845245 [INF] loading operator from /Users/synadia/.nsc/nats/Test/Test.jwt
|
||||
2019/05/10 11:22:41.846367 [INF] creating a read-only store for the NSC folder at /Users/synadia/.nsc/nats/Test
|
||||
2019/05/10 11:22:41.846459 [INF] NATS is not configured, server will not fire notifications on update
|
||||
2019/05/10 11:22:41.855291 [INF] http listening on port 9090
|
||||
2019/05/10 11:22:41.855301 [INF] nats-account-server is running
|
||||
2019/05/10 11:22:41.855303 [INF] configure the nats-server with:
|
||||
2019/05/10 11:22:41.855306 [INF] resolver: URL(http://localhost:9090/jwt/v1/accounts/)
|
||||
```
|
||||
|
||||
By default the server will serve JWTs on the localhost at port 9090. The last line in the shown in the printout is important, that is the resolver URL you'll have to provide on your NATS server configuration. You'll also need the matching operator JWT which is on `~/.nsc/nats/Test/Test.jwt` if you are following the example above. On the server configuration you'll need to expand the `~` as necessary. Here's what my NATS server configuration looks like:
|
||||
|
||||
```text
|
||||
operator: /Users/synadia/.nsc/nats/Test/Test.jwt
|
||||
resolver: URL(http://localhost:9090/jwt/v1/accounts/)
|
||||
```
|
||||
|
||||
Note that servers you create with the `-nsc` option \(or store option\) are read-only. This means that the server will not accept POST requests to update the JWT store.
|
||||
|
||||
## Directory Configuration
|
||||
|
||||
You can start a server using a plain directory. In this case you'll be responsible for adding any JWT that you want resolved.
|
||||
|
||||
> The server looks for account JWTs by using the public key of the account as the file name followed by the extension `.jwt`. The server will not introspect the JWTs, so if you don't name the files correctly, it will fail to find them or serve a JWT that doesn't match the requested account.
|
||||
|
||||
```text
|
||||
> mkdir /tmp/jwts
|
||||
nats-account-server -dir /tmp/jwts
|
||||
2019/05/10 11:33:40.501305 [INF] starting NATS Account server, version 0.0-dev
|
||||
2019/05/10 11:33:40.501383 [INF] server time is Fri May 10 11:33:40 CDT 2019
|
||||
2019/05/10 11:33:40.501404 [INF] creating a store at /tmp/jwts
|
||||
2019/05/10 11:33:40.501430 [INF] NATS is not configured, server will not fire notifications on update
|
||||
2019/05/10 11:33:40.510273 [INF] http listening on port 9090
|
||||
2019/05/10 11:33:40.510283 [INF] nats-account-server is running
|
||||
2019/05/10 11:33:40.510285 [INF] configure the nats-server with:
|
||||
2019/05/10 11:33:40.510291 [INF] resolver: URL(http://localhost:9090/jwt/v1/accounts/)
|
||||
```
|
||||
|
||||
Configuration for the NATS server is the same as in the previous example:
|
||||
|
||||
```text
|
||||
operator: /Users/synadia/.nsc/nats/Test/Test.jwt
|
||||
resolver: URL(http://localhost:9090/jwt/v1/accounts/)
|
||||
```
|
||||
|
||||
## Configuration File
|
||||
|
||||
While the `-nsc` and `-dir` store flags are sufficient for some very simple developer setups, any production or non-read-only server will require a configuration file.
|
||||
|
||||
Let's take a look at the configuration options:
|
||||
|
||||
### Configuration Options
|
||||
|
||||
| Option | Description |
|
||||
| :--- | :--- |
|
||||
| `http` | An `http` configuration block specifying HTTP options. |
|
||||
| `logging` | A `logging` configuration block specifying server logging options. |
|
||||
| `nats` | A `nats` configuration block specifying NATS connection information for the account server to push JWT changes to a NATS server. |
|
||||
| `operatorjwtpath` | The path to an operator JWT. Required for non-read-only servers. Only JWTs signed by the operator \(or one of it's signing keys\) are accepted. |
|
||||
| `store` | A `store` configuration block specifying store options. |
|
||||
| `systemaccountjwtpath` | Path to an Account JWT that should be returned as the system account. |
|
||||
| `primary` | URL for the primary, `protocol://host:port`. |
|
||||
| `replicationtimeout` | Timeout, in milliseconds, used by the replica when talking to the primary, defaults to `5000`. |
|
||||
|
||||
### `store` Configuration
|
||||
|
||||
| Option | Description |
|
||||
| :--- | :--- |
|
||||
| `dir` | Configures a directory as a store. |
|
||||
| `nsc` | Configures an nsc read-only store. The value should be the path to an operator _directory_. Option is mutually exlusive with `dir`. |
|
||||
| `readonly` | If `true`, the store will not accept POST requests. Note that to receive requests, the store must also have `operatorjwtpath` specified as a root option. |
|
||||
| `shard` | If `true`, JWTs are sharded in the store directory. |
|
||||
|
||||
## `logging` Options
|
||||
|
||||
| Option | Description |
|
||||
| :--- | :--- |
|
||||
| `time` | If `true`, a timestamp is added to log messages. |
|
||||
| `debug` | If `true`, debug messages are logged. |
|
||||
| `trace` | If `true`, trace messages are logged. |
|
||||
| `colors` | If `true`, messages are logged using ANSI color escape sequences. |
|
||||
| `pid` | If `true`, the process id for the server is added to log messages. |
|
||||
|
||||
## `http` Options
|
||||
|
||||
| Option | Description |
|
||||
| :--- | :--- |
|
||||
| `host` | Interface to listen for requests on. |
|
||||
| `port` | Port to listen for requests on. |
|
||||
| `readtimeout` | Max amount of time in milliseconds to wait for a http read operation to complete. |
|
||||
| `writetimeout` | Max amount of time in milliseconds to wait for a http write operation to complete. |
|
||||
|
||||
## `nats` Options
|
||||
|
||||
| Option | Description |
|
||||
| :--- | :--- |
|
||||
| `servers` | List of NATS servers for the account server to use when connecting to a NATS server to publish updates. |
|
||||
| `connecttimeout` | Max amount of time in milliseconds to wait for a NATS connection. |
|
||||
| `reconnecttimewait` | Amount of time in milliseconds to between NATS server reconnect attempts. |
|
||||
| `tls` | A `tls` configuration block. |
|
||||
| `usercredentials` | A credentials _creds_ file for connecting to the NATS server. Account must be a member of a system account. |
|
||||
|
||||
## `tls` Options
|
||||
|
||||
| Option | Description |
|
||||
| :--- | :--- |
|
||||
| `root` | filepath to the CA certificate. |
|
||||
| `cert` | filepath to the certificate. |
|
||||
| `cert` | filepath to the certificate key. |
|
||||
|
||||
106
nats-tools/nas/notifications.md
Normal file
106
nats-tools/nas/notifications.md
Normal file
@@ -0,0 +1,106 @@
|
||||
# Update Notifications
|
||||
|
||||
The `nats-account-server` can notify a nats-server about JWT updates, enabling the NATS server to update itself to the newly updated JWT.
|
||||
|
||||
To push notifications, the nats-account-server makes use of [system accounts](../../nats-server/nats_admin/sys_accounts/).
|
||||
|
||||
Here's a nats-account-server configuration with updates enabled:
|
||||
|
||||
```text
|
||||
operatorjwtpath: "/users/synadia/.nsc/nats/AAA/AAA.jwt",
|
||||
systemaccountjwtpath: "/users/synadia/.nsc/nats/AAA/accounts/SYS/SYS.jwt"
|
||||
http {
|
||||
port: 9090
|
||||
},
|
||||
store {
|
||||
dir: "/tmp/as_store",
|
||||
readonly: false,
|
||||
shard: true
|
||||
}
|
||||
nats {
|
||||
servers: [nats://localhost:4222]
|
||||
usercredentials: "/Users/synadia/.nkeys/AAA/accounts/SYS/users/sys.creds"
|
||||
}
|
||||
```
|
||||
|
||||
The above configuration:
|
||||
|
||||
* Sets the `operatorjwtpath` to verify pushed JWTs are signed by the operator
|
||||
* Sets the `systemaccountjwtpath` so that the `nats-server` can ask for the system account \(which the nats-account-server will trigger when it connects to the nats-server\)
|
||||
|
||||
The `nats` section:
|
||||
|
||||
* Sets the `servers` with a list of NATS urls
|
||||
* Sets `usercredentials` to the credentials file for the system account user that issues notifications.
|
||||
|
||||
When the account server starts:
|
||||
|
||||
* It makes a connection to the NATS server using the `usercredentials` of the system account.
|
||||
|
||||
The NATS server configuration looks like:
|
||||
|
||||
```text
|
||||
operator: /users/synadia/.nsc/nats/AAA/AAA.jwt
|
||||
resolver: URL(http://localhost:9090/jwt/v1/accounts/)
|
||||
system_account: AAUR7CJU5WTR2RROXOJJFTJFJQPZ6B4VF2NOX6OQ6SQMPIKLQYQ7T37U
|
||||
```
|
||||
|
||||
It specifies:
|
||||
|
||||
* The `operator` JWT
|
||||
* The `resolver` URL where the nats-account-server will create requests. Note the nats-account-server log prints the exact value you should provide for this setting:
|
||||
|
||||
```text
|
||||
...
|
||||
2019/05/31 16:47:50.519361 [INF] configure the nats-server with:
|
||||
2019/05/31 16:47:50.519368 [INF] resolver: URL(http://localhost:9090/jwt/v1/accounts/)
|
||||
...
|
||||
```
|
||||
|
||||
The nats-account-server has to be running before that nats-server starts, as currently, the nats-server will verify that it can connect to the resolver on startup.
|
||||
|
||||
```text
|
||||
> nats-account-server -c nas_not.conf
|
||||
2019/05/31 18:00:26.327583 [INF] loading configuration from "/Users/synadia/Desktop/nats_jwt_doc/as_dir/nas_not.conf"
|
||||
2019/05/31 18:00:26.327833 [INF] starting NATS Account server, version 0.0-dev
|
||||
2019/05/31 18:00:26.327852 [INF] server time is Fri May 31 18:00:26 CDT 2019
|
||||
2019/05/31 18:00:26.327862 [INF] loading operator from /users/synadia/.nsc/nats/AAA/AAA.jwt
|
||||
2019/05/31 18:00:26.328278 [INF] loading system account from /users/synadia/.nsc/nats/AAA/accounts/SYS/SYS.jwt
|
||||
2019/05/31 18:00:26.328590 [INF] creating a store at /tmp/as_store
|
||||
2019/05/31 18:00:26.328619 [INF] connecting to NATS for notifications
|
||||
2019/05/31 18:00:26.329875 [ERR] failed to connect to NATS, nats: no servers available for connection
|
||||
2019/05/31 18:00:26.329884 [ERR] will try to connect again in 1000 milliseconds
|
||||
2019/05/31 18:00:26.330541 [INF] http listening on port 9090
|
||||
2019/05/31 18:00:26.330548 [INF] nats-account-server is running
|
||||
2019/05/31 18:00:26.330551 [INF] configure the nats-server with:
|
||||
2019/05/31 18:00:26.330557 [INF] resolver: URL(http://localhost:9090/jwt/v1/accounts/)
|
||||
2019/05/31 18:00:27.330103 [INF] connecting to NATS for notifications
|
||||
2019/05/31 18:00:27.331215 [ERR] failed to connect to NATS, nats: no servers available for connection
|
||||
2019/05/31 18:00:27.331223 [ERR] will try to connect again in 1000 milliseconds
|
||||
```
|
||||
|
||||
Then start the NATS server:
|
||||
|
||||
```text
|
||||
> nats-server -c /tmp/server.conf
|
||||
[57440] 2019/05/31 18:01:29.940149 [INF] Starting nats-server version 1.4.1
|
||||
[57440] 2019/05/31 18:01:29.940234 [INF] Git commit [not set]
|
||||
[57440] 2019/05/31 18:01:29.940468 [INF] Listening for client connections on 0.0.0.0:4222
|
||||
[57440] 2019/05/31 18:01:29.940476 [INF] Server is ready
|
||||
```
|
||||
|
||||
At this point, you have both servers running. You can submit updates to the nats-account-server using `nsc`:
|
||||
|
||||
```text
|
||||
> nsc push -A
|
||||
successfully pushed all accounts [A, B, SYS]
|
||||
```
|
||||
|
||||
The account server should show the updates in its log:
|
||||
|
||||
```text
|
||||
2019/05/31 18:02:29.702044 [INF] updated JWT for account - ACVEO3LPVRGE - GSO7ZQPXXNTBBEEGXFFLFXZLCGOA5ABUOADZBPASYGCDIEJ6QQPQ
|
||||
2019/05/31 18:02:29.702988 [INF] updated JWT for account - ADDVBX4VPWSN - VPBI4OHVJ7ITKX6S2RWHHJ3BB6JFZ7NPJN33JH6L752T2YI2QJKA
|
||||
2019/05/31 18:02:29.703745 [INF] updated JWT for account - AAUR7CJU5WTR - NHEPTVMURCQEURAWHX6LUUMO4KCQUAP4JCLIQANP3JTNPMG3IFWQ
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user