mirror of
https://github.com/taigrr/nats.docs
synced 2025-01-18 04:03:23 -08:00
Better explanation of jwt. Reorganizing files, adding links.
Signed-off-by: Matthias Hanel <mh@synadia.com>
This commit is contained in:
Matthias Hanel
@@ -1,20 +1,18 @@
|
||||
# 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:
|
||||
The [NATS Account Server](https://github.com/nats-io/nats-account-server) is an HTTP server that hosts and vends [JWTs](../../nats-server/configuration/securing_nats/jwt/README.md) for nats-server 2.0 account authentication.
|
||||
The server supports an number of stores which enable it to serve account [JWTs](../../nats-server/configuration/securing_nats/jwt/README.md) from:
|
||||
|
||||
* a directory
|
||||
* an [NSC](../nsc/nsc.md) directory
|
||||
* memory \(for testing purposes\)
|
||||
* a [directory](nas_conf.md#directory-configuration)
|
||||
* an [NSC](../nsc/nsc.md) [directory](nas_conf.md#nsc-configuration)
|
||||
|
||||
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.
|
||||
> For testing purposes the nats server can be configured with a [memory resolver](../../nats-server/configuration/securing_nats/jwt/resolver.md#memory) that avoids usage of the account server.
|
||||
|
||||
The server can operate in a _READ ONLY_ mode where it serves content from a directory, or in [notification mode](notifications.md), 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).
|
||||
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. The account serer furthermore allows for jwt inspection.
|
||||
|
||||
All account server configuration options can be found [here](nas_conf.md#Configuration-File).
|
||||
It futhermore allows [inspection](inspecting_jwts.md) of JWT.
|
||||
@@ -100,3 +100,4 @@ Quick check on nsc to verify the ids of the accounts on nsc, match the files:
|
||||
|
||||
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.
|
||||
|
||||
Curl can also be used to [inspect](inspecting_jwts.md) JWTs.
|
||||
@@ -1,118 +0,0 @@
|
||||
# Memory Resolver
|
||||
|
||||
The `MEMORY` resolver is a server built-in resolver for account JWTs. If there are a small number of accounts, or they do not change too often this can be a simpler configuration that does not require an external account resolver. Server configuration reload is supported, meaning the preloads can be updated in the server configuration and reloaded without a server restart.
|
||||
|
||||
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'
|
||||
```
|
||||
|
||||
@@ -91,6 +91,8 @@ operator: /Users/synadia/.nsc/nats/Test/Test.jwt
|
||||
resolver: URL(http://localhost:9090/jwt/v1/accounts/)
|
||||
```
|
||||
|
||||
A step by step tutorial using directory configuration can be found [here](dir_store.md).
|
||||
|
||||
## 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.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# 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.
|
||||
The `nats-account-server` can notify a nats-server about [JWT](../../nats-server/configuration/securing_nats/jwt/README.md) 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/configuration/sys_accounts/sys_accounts.md).
|
||||
|
||||
|
||||
Reference in New Issue
Block a user