mirror of
https://github.com/taigrr/nats.docs
synced 2025-01-18 04:03:23 -08:00
GitBook: [master] 82 pages modified
This commit is contained in:
Ginger Collison
committed by
gitbook-bot
gitbook-bot
parent
7e27f03c98
commit
b082996143
@@ -1,11 +0,0 @@
|
||||
## NATS Tools
|
||||
|
||||
The NATS Ecosystem has many tools to support server configuration, enhance monitoring or tune performance:
|
||||
|
||||
- [mkpasswd](mkpasswd.md) - Generates or bcrypts passwords
|
||||
- [nk](nk.md) - Generate NKeys
|
||||
- [nsc](nsc/README.md) - Configure Operators, Accounts and Users
|
||||
- [nats account server](nas/README.md) - Serve Account JWTs
|
||||
- [nats top](nats_top/README.md) - Monitor NATS Server
|
||||
- [nats-bench](natsbench.md) - Benchmark NATS Server
|
||||
- [prometheus-nats-exporter](https://github.com/nats-io/prometheus-nats-exporter) - Export NATS server metrics to [Prometheus](https://prometheus.io/) and a [Grafana](https://grafana.com) dashboard.
|
||||
12
nats-tools/nats-tools.md
Normal file
12
nats-tools/nats-tools.md
Normal file
@@ -0,0 +1,12 @@
|
||||
# Introduction
|
||||
|
||||
The NATS Ecosystem has many tools to support server configuration, enhance monitoring or tune performance:
|
||||
|
||||
* [mkpasswd](mkpasswd.md) - Generates or bcrypts passwords
|
||||
* [nk](nk.md) - Generate NKeys
|
||||
* [nsc](nsc/) - Configure Operators, Accounts and Users
|
||||
* [nats account server](nas/) - Serve Account JWTs
|
||||
* [nats top](nats_top/) - Monitor NATS Server
|
||||
* [nats-bench](natsbench.md) - Benchmark NATS Server
|
||||
* [prometheus-nats-exporter](https://github.com/nats-io/prometheus-nats-exporter) - Export NATS server metrics to [Prometheus](https://prometheus.io/) and a [Grafana](https://grafana.com) dashboard.
|
||||
|
||||
@@ -1,15 +1,15 @@
|
||||
# NATS Account Configuration
|
||||
# nsc
|
||||
|
||||
NATS account configurations are built using the `nsc` tool. The NSC tool allows you to:
|
||||
|
||||
- Create and edit Operators, Accounts, Users
|
||||
- Manage publish and subscribe permissions for Users
|
||||
- Define Service and Stream exports from an account
|
||||
- Reference Service and Streams from another account
|
||||
- Generate Activation tokens that grants access to a private service or stream
|
||||
- Generate User credential files
|
||||
- Describe Operators, Accounts, Users, and Activations
|
||||
- Push and pull account JWTs to an account JWTs server
|
||||
* Create and edit Operators, Accounts, Users
|
||||
* Manage publish and subscribe permissions for Users
|
||||
* Define Service and Stream exports from an account
|
||||
* Reference Service and Streams from another account
|
||||
* Generate Activation tokens that grants access to a private service or stream
|
||||
* Generate User credential files
|
||||
* Describe Operators, Accounts, Users, and Activations
|
||||
* Push and pull account JWTs to an account JWTs server
|
||||
|
||||
## Installation
|
||||
|
||||
@@ -19,26 +19,26 @@ Installing `nsc` is easy:
|
||||
curl -L https://raw.githubusercontent.com/nats-io/nsc/master/install.py | python
|
||||
```
|
||||
|
||||
The script will download the latest version of `nsc` and install it into your system.
|
||||
The script will download the latest version of `nsc` and install it into your system.
|
||||
|
||||
## Tutorials
|
||||
|
||||
You can find various task-oriented tutorials to working with the tool here:
|
||||
|
||||
- [Basic Usage](nsc.md)
|
||||
- [Configuring Streams](streams.md)
|
||||
- [Configuring Services](services.md)
|
||||
- [Signing Keys](signing_keys.md)
|
||||
- [Revoking Users or Activations](revocation.md)
|
||||
- [Working with Managed Operators](managed.md)
|
||||
* [Basic Usage](nsc.md)
|
||||
* [Configuring Streams](streams.md)
|
||||
* [Configuring Services](services.md)
|
||||
* [Signing Keys](signing_keys.md)
|
||||
* [Revoking Users or Activations](revocation.md)
|
||||
* [Working with Managed Operators](managed.md)
|
||||
|
||||
## Tool Documentation
|
||||
|
||||
For more specific browsing of the tool syntax, check out the `nsc` tool documentation.
|
||||
It can be found within the tool itself:
|
||||
For more specific browsing of the tool syntax, check out the `nsc` tool documentation. It can be found within the tool itself:
|
||||
|
||||
```text
|
||||
> nsc help
|
||||
```
|
||||
|
||||
Or an online version [here](https://nats-io.github.io/nsc).
|
||||
Or an online version [here](https://nats-io.github.io/nsc).
|
||||
|
||||
|
||||
@@ -1,30 +1,28 @@
|
||||
# NSC
|
||||
# Basics
|
||||
|
||||
NSC allows you to manage identities. Identities take the form of _nkeys_. Nkeys are a public-key signature system based on Ed25519 for the NATS ecosystem.
|
||||
|
||||
The nkey identities are associated with NATS configuration in the form of a Jason Web Token (JWT). The JWT is digitally signed by the private key of an issuer forming a chain of trust. The `nsc` tool creates and manages these identities and allows you to deploy them to a JWT account server, which in turn makes the configurations available to nats-servers.
|
||||
The nkey identities are associated with NATS configuration in the form of a Jason Web Token \(JWT\). The JWT is digitally signed by the private key of an issuer forming a chain of trust. The `nsc` tool creates and manages these identities and allows you to deploy them to a JWT account server, which in turn makes the configurations available to nats-servers.
|
||||
|
||||
There’s a logical hierarchy to the entities:
|
||||
|
||||
- `Operators` are responsible for running nats-servers, and issuing account JWTs. Operators set the limits on what an account can do, such as the number of connections, data limits, etc.
|
||||
|
||||
- `Accounts` are responsible for issuing user JWTs. An account defines streams and services that can be exported to other accounts. Likewise, they import streams and services from other accounts.
|
||||
|
||||
- `Users` are issued by an account, and encode limits regarding usage and authorization over the account's subject space.
|
||||
* `Operators` are responsible for running nats-servers, and issuing account JWTs. Operators set the limits on what an account can do, such as the number of connections, data limits, etc.
|
||||
* `Accounts` are responsible for issuing user JWTs. An account defines streams and services that can be exported to other accounts. Likewise, they import streams and services from other accounts.
|
||||
* `Users` are issued by an account, and encode limits regarding usage and authorization over the account's subject space.
|
||||
|
||||
NSC allows you to create, edit, and delete these entities, and will be central to all account-based configuration.
|
||||
|
||||
In this guide, you’ll run end-to-end on some of the configuration scenarios:
|
||||
|
||||
- Generate NKey identities and their associated JWTs
|
||||
- Make JWTs accessible to a nats-server
|
||||
- Configure a nats-server to use JWTs
|
||||
* Generate NKey identities and their associated JWTs
|
||||
* Make JWTs accessible to a nats-server
|
||||
* Configure a nats-server to use JWTs
|
||||
|
||||
Let’s run through the process of creating some identities and JWTs and work through the process.
|
||||
|
||||
## Creating an Operator, Account and User
|
||||
|
||||
Let’s create an operator called `O` (oh):
|
||||
Let’s create an operator called `O` \(oh\):
|
||||
|
||||
```bash
|
||||
> nsc add operator O
|
||||
@@ -42,7 +40,6 @@ Lets add a service URL to the operator. Service URLs specify where the nats-serv
|
||||
[ OK ] edited operator "O"
|
||||
```
|
||||
|
||||
|
||||
Creating an account is just as easy:
|
||||
|
||||
```bash
|
||||
@@ -64,14 +61,13 @@ Finally, let's create a user:
|
||||
|
||||
As expected, the tool generated an NKEY representing the user, and stored the private key safely in the keystore. In addition, the tool generated a _credentials_ file. A credentials file contains the JWT for the user and the private key for the user. Credential files are used by NATS clients to identify themselves to the system. The client will extract and present the JWT to the nats-server and use the private key to verify its identity.
|
||||
|
||||
|
||||
### NSC Assets
|
||||
|
||||
NSC manages three different directories:
|
||||
|
||||
- The nsc home directory which stores nsc related data. By default nsc home lives in `~/.nsc` and can be changed via the `$NSC_HOME` environment variable.
|
||||
- An _nkeys_ directory, which stores all the private keys. This directory by default lives in `~/.nkeys` and can be changed via the `$NKEYS_PATH` environment variable. The contents of the nkeys directory should be treated as secrets.
|
||||
- A _stores_ directory, which contains JWTs representing the various entities. This directory lives in `$NSC_HOME/nats`, and can be changed using the command `nsc env -s <dir>`. The stores directory can stored under revision control. The JWTs themselves do not contain any secrets.
|
||||
* The nsc home directory which stores nsc related data. By default nsc home lives in `~/.nsc` and can be changed via the `$NSC_HOME` environment variable.
|
||||
* An _nkeys_ directory, which stores all the private keys. This directory by default lives in `~/.nkeys` and can be changed via the `$NKEYS_PATH` environment variable. The contents of the nkeys directory should be treated as secrets.
|
||||
* A _stores_ directory, which contains JWTs representing the various entities. This directory lives in `$NSC_HOME/nats`, and can be changed using the command `nsc env -s <dir>`. The stores directory can stored under revision control. The JWTs themselves do not contain any secrets.
|
||||
|
||||
#### The NSC Stores Directory
|
||||
|
||||
@@ -97,26 +93,27 @@ The nkeys directory contains all the private keys and credential files. As menti
|
||||
|
||||
The structure keys directory is machine friendly. All keys are sharded by their kind `O` for operators, `A` for accounts, `U` for users. These prefixes are also part of the public key. The second and third letters in the public key are used to create directories where other like-named keys are stored.
|
||||
|
||||
```
|
||||
```text
|
||||
tree ~/.nkeys
|
||||
/Users/aricart/.nkeys
|
||||
├── creds
|
||||
│ └── O
|
||||
│ └── A
|
||||
│ └── U.creds
|
||||
│ └── O
|
||||
│ └── A
|
||||
│ └── U.creds
|
||||
└── keys
|
||||
├── A
|
||||
│ └── DE
|
||||
│ └── ADETPT36WBIBUKM3IBCVM4A5YUSDXFEJPW4M6GGVBYCBW7RRNFTV5NGE.nk
|
||||
│ └── DE
|
||||
│ └── ADETPT36WBIBUKM3IBCVM4A5YUSDXFEJPW4M6GGVBYCBW7RRNFTV5NGE.nk
|
||||
├── O
|
||||
│ └── AF
|
||||
│ └── OAFEEYZSYYVI4FXLRXJTMM32PQEI3RGOWZJT7Y3YFM4HB7ACPE4RTJPG.nk
|
||||
│ └── AF
|
||||
│ └── OAFEEYZSYYVI4FXLRXJTMM32PQEI3RGOWZJT7Y3YFM4HB7ACPE4RTJPG.nk
|
||||
└── U
|
||||
└── DB
|
||||
└── UDBD5FNQPSLIO6CDMIS5D4EBNFKYWVDNULQTFTUZJXWFNYLGFF52VZN7.nk
|
||||
```
|
||||
|
||||
The `nk` files themselves are named after the complete public key, and stored in a single string - the private key in question:
|
||||
|
||||
```bash
|
||||
cat ~/.nkeys/keys/U/DB/UDBD5FNQPSLIO6CDMIS5D4EBNFKYWVDNULQTFTUZJXWFNYLGFF52VZN7.nk
|
||||
SUAG35IAY2EF5DOZRV6MUSOFDGJ6O2BQCZHSRPLIK6J3GVCX366BFAYSNA
|
||||
@@ -126,7 +123,6 @@ The private keys are encoded into a string, and always begin with an `S` for _se
|
||||
|
||||
In addition to containing keys, the nkeys directory contains a `creds` directory. This directory is organized in a way friendly to humans. It stores user credential files or `creds` files for short. A credentials file contains a copy of the user JWT and the private key for the user. These files are used by NATS clients to connect to a NATS server:
|
||||
|
||||
|
||||
```bash
|
||||
> cat ~/.nkeys/creds/O/A/U.creds
|
||||
-----BEGIN NATS USER JWT-----
|
||||
@@ -165,8 +161,7 @@ The different entity names are listed along with their public key, and whether t
|
||||
|
||||
In some cases you may want to view the private keys:
|
||||
|
||||
|
||||
```
|
||||
```text
|
||||
> nsc list keys --show-seeds
|
||||
╭───────────────────────────────────────────────────────────────────────────────────╮
|
||||
│ Seeds Keys │
|
||||
@@ -181,8 +176,7 @@ In some cases you may want to view the private keys:
|
||||
[ERR] error reading seed
|
||||
```
|
||||
|
||||
If you don't have the seed (perhaps you don't control the operator), nsc will decorate the row with a `!`.
|
||||
If you have more than one account, you can show them all by specifying the `--all` flag.
|
||||
If you don't have the seed \(perhaps you don't control the operator\), nsc will decorate the row with a `!`. If you have more than one account, you can show them all by specifying the `--all` flag.
|
||||
|
||||
## The Operator JWT
|
||||
|
||||
@@ -203,7 +197,8 @@ You can view a human readable version of the JWT by using `nsc`:
|
||||
```
|
||||
|
||||
Since the operator JWT is just a JWT you can use other tools, such as jwt.io to decode a JWT an inspect it's contents. All JWTs have a header, payload, and signature:
|
||||
```json
|
||||
|
||||
```javascript
|
||||
{
|
||||
"typ": "jwt",
|
||||
"alg": "ed25519"
|
||||
@@ -223,14 +218,9 @@ Since the operator JWT is just a JWT you can use other tools, such as jwt.io to
|
||||
}
|
||||
```
|
||||
|
||||
All NATS JWTs will use the `algorithm` ed25519 for signature.
|
||||
The payload will list different things. On our basically empty operator, we will only have standard JWT `claim` fields:
|
||||
All NATS JWTs will use the `algorithm` ed25519 for signature. The payload will list different things. On our basically empty operator, we will only have standard JWT `claim` fields:
|
||||
|
||||
`jti` - a jwt id
|
||||
`iat` - the timestamp when the JWT was issued in UNIX time
|
||||
`iss` - the issuer of the JWT, in this case the operator's public key
|
||||
`sub` - the subject or identity represented by the JWT, in this case the same operator
|
||||
`type` - since this is an operator JWT, `operator` is the type
|
||||
`jti` - a jwt id `iat` - the timestamp when the JWT was issued in UNIX time `iss` - the issuer of the JWT, in this case the operator's public key `sub` - the subject or identity represented by the JWT, in this case the same operator `type` - since this is an operator JWT, `operator` is the type
|
||||
|
||||
NATS specific is the `nats` object, which is where we add NATS specific JWT configuration to the JWT claim.
|
||||
|
||||
@@ -293,7 +283,6 @@ The user id is the public key for the user, the issuer is the account. This user
|
||||
|
||||
When a user connects to a nats-server, it presents it's user JWT and signs an nonce using its private key. The server verifies if the user is who they say they are by validating that the nonce was signed using the private key associated with the public key, representing the identify of the user. Next, the server fetches the issuer account and validates that the account was issued by a trusted operator completing the chain of trust verification.
|
||||
|
||||
|
||||
Let’s put all of this together, and create a simple server configuration that accepts sessions from `U`.
|
||||
|
||||
## Account Server Configuration
|
||||
@@ -314,7 +303,7 @@ The account server has options to enable you to use an nsc directory directly. L
|
||||
> nats-account-server -nsc ~/.nsc/nats/O
|
||||
```
|
||||
|
||||
Above, we pointed the account server to our nsc data directory (more specifically to the `O` operator that we created earlier). By default, the server listens on the localhost at port 9090.
|
||||
Above, we pointed the account server to our nsc data directory \(more specifically to the `O` operator that we created earlier\). By default, the server listens on the localhost at port 9090.
|
||||
|
||||
You can also run the account server with a data directory that is not your nsc folder. In this mode, you can upload account JWTs to the server. See the help for `nsc push` for more information about how to push JWTs to the account server.
|
||||
|
||||
@@ -364,14 +353,12 @@ Published [hello] : 'NATS'
|
||||
Subscriber shows:
|
||||
|
||||
```text
|
||||
[#1] Received on [hello]: ’NATS’
|
||||
```
|
||||
|
||||
```
|
||||
|
||||
### NSC Embeds NATS tooling
|
||||
|
||||
To make it easier to work, you can use the NATS clients built right into NSC. These tools know how to find the credential files in the keyring.
|
||||
For convenience, the tools are aliased to `sub`, `pub`, `req`, `reply`:
|
||||
To make it easier to work, you can use the NATS clients built right into NSC. These tools know how to find the credential files in the keyring. For convenience, the tools are aliased to `sub`, `pub`, `req`, `reply`:
|
||||
|
||||
```bash
|
||||
nsc sub --user U ">"
|
||||
@@ -379,12 +366,10 @@ nsc sub --user U ">"
|
||||
|
||||
nsc pub --user U hello NATS
|
||||
...
|
||||
|
||||
```
|
||||
|
||||
See `nsc tool -h` for more detailed information.
|
||||
|
||||
|
||||
## User Authorization
|
||||
|
||||
User authorization, as expected, also works with JWT authentication. With `nsc` you can specify authorization for specific subjects to which the user can or cannot publish or subscribe. By default a user doesn't have any limits on the subjects that it can publish or subscribe to. Any message stream or message published in the account is subscribable by the user. The user can also publish to any subject or imported service. Note that authorization, if configured, must be specified on a per user basis.
|
||||
@@ -455,7 +440,6 @@ Similarly, we can limit a client:
|
||||
|
||||
The client has the opposite permissions of the service. It can publish on the request subject `q`, and receive replies on an inbox.
|
||||
|
||||
|
||||
## The NSC Environment
|
||||
|
||||
As your projects become more involved, you may work with one or more accounts. NSC tracks your current operator and account. If you are not in a directory containing an operator, account or user, it will use the last operator/account context.
|
||||
@@ -480,3 +464,4 @@ To view your current environment:
|
||||
```
|
||||
|
||||
If you have multiple accounts, you can use `nsc env --account <account name>` to set the account as the current default. If you have defined `NKEYS_PATH` or `NSC_HOME` in the environment, you'll also see their current effective values. Finally, if you want to set the stores directory to anything other than the default, you can do `nsc env --store <dir containing an operator>`. If you have multiple accounts, you can try having multiple terminals, each in a directory for a different account.
|
||||
|
||||
|
||||
@@ -49,10 +49,10 @@ To review the service export:
|
||||
|
||||
Importing a service enables you to send requests to the remote _Account_. To import a Service, you have to create an _Import_. To create an import you need to know:
|
||||
|
||||
- The exporting account’s public key
|
||||
- The subject the service is listening on
|
||||
- You can map the service’s subject to a different subject
|
||||
- Self-imports are not valid; you can only import services from other accounts.
|
||||
* The exporting account’s public key
|
||||
* The subject the service is listening on
|
||||
* You can map the service’s subject to a different subject
|
||||
* Self-imports are not valid; you can only import services from other accounts.
|
||||
|
||||
To learn how to inspect a JWT from an account server, [check this article](../nas/inspecting_jwts.md).
|
||||
|
||||
@@ -111,12 +111,12 @@ Let's also add a user to make requests from the service:
|
||||
[ OK ] added user "b" to account "B"
|
||||
```
|
||||
|
||||
|
||||
### Testing the Service
|
||||
|
||||
To test the service, we can install the `nats-req` and `nats-rply` tools:
|
||||
|
||||
Set up a process to handle the request. This process will run from account 'A' using user 'U':
|
||||
|
||||
```text
|
||||
> go get github.com/nats-io/nats.go/examples/nats-rply
|
||||
|
||||
@@ -128,6 +128,7 @@ nsc reply --account A --user U help "I will help"
|
||||
```
|
||||
|
||||
Send the request:
|
||||
|
||||
```text
|
||||
> go get github.com/nats-io/nats.go/examples/nats-req
|
||||
> nats-req -creds ~/.nkeys/creds/O/B/b.creds help me
|
||||
@@ -135,11 +136,13 @@ Published [help] : 'me'
|
||||
```
|
||||
|
||||
The service receives the request:
|
||||
|
||||
```text
|
||||
Received on [help]: 'me'
|
||||
```
|
||||
|
||||
And the response is received by the requestor:
|
||||
|
||||
```text
|
||||
Received [_INBOX.v6KAX0v1bu87k49hbg3dgn.StIGJF0D] : 'I will help'
|
||||
```
|
||||
@@ -200,14 +203,13 @@ As before, we declared an export, but this time we added the `--private` flag. T
|
||||
│ help │ Service │ help │ Yes │ 0 │ - │
|
||||
│ private.help.* │ Service │ private.help.* │ No │ 0 │ - │
|
||||
╰────────────────┴─────────┴────────────────┴────────┴─────────────┴──────────╯
|
||||
|
||||
```
|
||||
|
||||
### Generating an Activation Token
|
||||
|
||||
For the foreign account to _import_ a private service and be able to send requests, you have to generate an activation token. The activation token in addition to granting permission to the account allows you to subset the service’s subject:
|
||||
|
||||
To generate a token, you’ll need to know the public key of the account importing the service. We can easily find the public key for account B by running:
|
||||
To generate a token, you’ll need to know the public key of the account importing the service. We can easily find the public key for account B by running:
|
||||
|
||||
```bash
|
||||
> nsc list keys --account B
|
||||
@@ -222,16 +224,13 @@ To generate a token, you’ll need to know the public key of the account importi
|
||||
╰────────┴──────────────────────────────────────────────────────────┴─────────────┴────────╯
|
||||
```
|
||||
|
||||
|
||||
```text
|
||||
> nsc generate activation --account A --target-account AAM46E3YF5WOZSE5WNYWHN3YYISVZOSI6XHTF2Q64ECPXSFQZROJMP2H --subject private.help.AAM46E3YF5WOZSE5WNYWHN3YYISVZOSI6XHTF2Q64ECPXSFQZROJMP2H -o /tmp/activation.jwt
|
||||
[ OK ] generated "private.help.*" activation for account "AAM46E3YF5WOZSE5WNYWHN3YYISVZOSI6XHTF2Q64ECPXSFQZROJMP2H"
|
||||
[ OK ] wrote account description to "/tmp/activation.jwt"
|
||||
```
|
||||
|
||||
The command took the account that has the export ('A'), the public key of account B, the subject where requests from account B will be handled, and an output file where the token can be stored.
|
||||
The subject for the export allows the service to handle all requests coming in on private.help.*, but account B can only request from a specific subject.
|
||||
|
||||
The command took the account that has the export \('A'\), the public key of account B, the subject where requests from account B will be handled, and an output file where the token can be stored. The subject for the export allows the service to handle all requests coming in on private.help.\*, but account B can only request from a specific subject.
|
||||
|
||||
For completeness, the contents of the JWT file looks like this:
|
||||
|
||||
@@ -267,9 +266,9 @@ When decoded it looks like this:
|
||||
╰─────────────────┴───────────────────────────────────────────────────────────────────────╯
|
||||
```
|
||||
|
||||
The token can be shared directly with the client account.
|
||||
The token can be shared directly with the client account.
|
||||
|
||||
> If you manage many tokens for many accounts, you may want to host activation tokens on a web server and share the URL with the account. The benefit to the hosted approach is that any updates to the token would be available to the importing account whenever their account is updated, provided the URL you host them in is stable. When using a JWT account server, the tokens can be stored right on the server and shared by an URL that is printed when the token is generated.
|
||||
> If you manage many tokens for many accounts, you may want to host activation tokens on a web server and share the URL with the account. The benefit to the hosted approach is that any updates to the token would be available to the importing account whenever their account is updated, provided the URL you host them in is stable. When using a JWT account server, the tokens can be stored right on the server and shared by an URL that is printed when the token is generated.
|
||||
|
||||
## Importing a Private Service
|
||||
|
||||
@@ -320,9 +319,8 @@ Testing a private service is no different than a public one:
|
||||
```bash
|
||||
> nsc reply --account A --user U "private.help.*" "help is here"
|
||||
listening on [private.help.*]
|
||||
[#1] received on [private.help.AAM46E3YF5WOZSE5WNYWHN3YYISVZOSI6XHTF2Q64ECPXSFQZROJMP2H]: 'help_me'
|
||||
|
||||
> nsc req --account B --user b private.help help_me
|
||||
published request: [private.help] : 'help_me'
|
||||
received reply: [_INBOX.3MhS0iCHfqO8wUl1x59bHB.jpE2jvEj] : 'help is here'
|
||||
```
|
||||
|
||||
|
||||
@@ -4,22 +4,22 @@ As previously discussed, NKEYs are identities, and if someone gets a hold of an
|
||||
|
||||
NATS has a strategies to let you deal with scenarios where your private keys escape out in the wild.
|
||||
|
||||
The first and most important line of defense is _Signing Keys_. _Signing Keys_ allow you have multiple NKEY identities of the same kind (Operator or Account) that have the same degree of trust as the standard _Issuer_ nkey.
|
||||
The first and most important line of defense is _Signing Keys_. _Signing Keys_ allow you have multiple NKEY identities of the same kind \(Operator or Account\) that have the same degree of trust as the standard _Issuer_ nkey.
|
||||
|
||||
The concept behind the signing key is that you can issue a JWT for an operator or an account that lists multiple nkeys. Typically the issuer will match the _Subject_ of the entity issuing the JWT. With SigningKeys, a JWT is considered valid if it is signed by the _Subject_ of the _Issuer_ or one of its signing keys. This enables guarding the private key of the Operator or Account more closely while allowing _Accounts_, _Users_ or _Activation Tokens_ be signed using alternate private keys.
|
||||
|
||||
If an issue should arise where somehow a signing key escapes into the wild, you would remove the compromised signing key from the entity, add a new one, and reissue the entity. When a JWT is validated, if the signing key is missing, the operation is rejected. You are also on the hook to re-issue all JWTs (accounts, users, activation tokens) that were signed with the compromised signing key.
|
||||
If an issue should arise where somehow a signing key escapes into the wild, you would remove the compromised signing key from the entity, add a new one, and reissue the entity. When a JWT is validated, if the signing key is missing, the operation is rejected. You are also on the hook to re-issue all JWTs \(accounts, users, activation tokens\) that were signed with the compromised signing key.
|
||||
|
||||
This is effectively a large hammer. You can mitigate the process a bit by having a larger number of signing keys and then rotating the signing keys to get a distribution you can easily handle in case of a compromise. In a future release, we’ll have a revocation process were you can invalidate a single JWT by its unique JWT ID (JTI). For now a sledge hammer you have.
|
||||
This is effectively a large hammer. You can mitigate the process a bit by having a larger number of signing keys and then rotating the signing keys to get a distribution you can easily handle in case of a compromise. In a future release, we’ll have a revocation process were you can invalidate a single JWT by its unique JWT ID \(JTI\). For now a sledge hammer you have.
|
||||
|
||||
With greater security process, there’s greater complexity. With that said, `nsc` doesn’t track public or private signing keys. As these are only identities that when in use presume a manual use. That means that you the user will have to track and manage your private keys more closely.
|
||||
|
||||
Let’s get a feel for the workflow. We are going to:
|
||||
|
||||
- Create an operator with a signing key
|
||||
- Create an account with a signing key
|
||||
- The account will be signed using the operator’s signing key
|
||||
- Create an user with the account’s signing key
|
||||
* Create an operator with a signing key
|
||||
* Create an account with a signing key
|
||||
* The account will be signed using the operator’s signing key
|
||||
* Create an user with the account’s signing key
|
||||
|
||||
All signing key operations revolve around the global `nsc` flag `-K` or `--private-key`. Whenever you want to modify an entity, you have to supply the parent key so that the JWT is signed. Normally this happens automatically but in the case of signing keys, you’ll have to supply the flag by hand.
|
||||
|
||||
@@ -42,7 +42,7 @@ operator key stored ~/.nkeys/keys/O/AZ/OAZBRNE7DQGDYT5CSAGWDMI5ENGKOEJ57BXVU6WUT
|
||||
|
||||
> On a production environment private keys should be saved to a file and always referenced from the secured file.
|
||||
|
||||
Now we are going to edit the operator by adding a signing key with the `--sk` flag providing the generated operator public key (the one starting with `O`):
|
||||
Now we are going to edit the operator by adding a signing key with the `--sk` flag providing the generated operator public key \(the one starting with `O`\):
|
||||
|
||||
```text
|
||||
> nsc edit operator --sk OAZBRNE7DQGDYT5CSAGWDMI5ENGKOEJ57BXVU6WUTHFEAO3CU5GLQYF5
|
||||
@@ -118,7 +118,7 @@ Let’s add the signing key to the account, and remember to sign the account wit
|
||||
╰───────────────────────────┴──────────────────────────────────────────────────────────╯
|
||||
```
|
||||
|
||||
We can see that the signing key `ADUQTJD4TF4O6LTTHCKDKSHKGBN2NECCHHMWFREPKNO6MPA7ZETFEEF7` was added to the account. Also the issuer is the operator signing key (specified by the `-K`).
|
||||
We can see that the signing key `ADUQTJD4TF4O6LTTHCKDKSHKGBN2NECCHHMWFREPKNO6MPA7ZETFEEF7` was added to the account. Also the issuer is the operator signing key \(specified by the `-K`\).
|
||||
|
||||
Now let’s create a user and signing it with account signing key starting with `ABHYL27UAHHQ`.
|
||||
|
||||
@@ -149,3 +149,4 @@ Now let’s create a user and signing it with account signing key starting with
|
||||
```
|
||||
|
||||
As expected, the issuer is now the signing key we generated earlier. To map the user to the actual account, an `Issuer Account` field was added to the JWT that identifies the public key of account _A_.
|
||||
|
||||
|
||||
@@ -53,10 +53,10 @@ Messages this account publishes on `a.b.c.>` will be forwarded to all accounts t
|
||||
|
||||
Importing a stream enables you to receive messages that are published by a different _Account_. To import a Stream, you have to create an _Import_. To create an _Import_ you need to know:
|
||||
|
||||
- The exporting account’s public key
|
||||
- The subject where the stream is published
|
||||
- You can map the stream’s subject to a different subject
|
||||
- Self-imports are not valid; you can only import streams from other accounts.
|
||||
* The exporting account’s public key
|
||||
* The subject where the stream is published
|
||||
* You can map the stream’s subject to a different subject
|
||||
* Self-imports are not valid; you can only import streams from other accounts.
|
||||
|
||||
To learn how to inspect a JWT from an account server, [check this article](../nas/inspecting_jwts.md).
|
||||
|
||||
@@ -72,7 +72,7 @@ With the required information, we can add an import to the public stream.
|
||||
[ OK ] added stream import "a.b.c.>"
|
||||
```
|
||||
|
||||
> Notice that messages published by the remote account will be received on the same subject as they are originally published. Sometimes you would like to prefix messages received from a stream. To add a prefix specify `--local-subject`. Subscribers in our account can listen to `abc.>`. For example if `--local-subject abc`, The message will be received as `abc.a.b.c.>`.
|
||||
> Notice that messages published by the remote account will be received on the same subject as they are originally published. Sometimes you would like to prefix messages received from a stream. To add a prefix specify `--local-subject`. Subscribers in our account can listen to `abc.>`. For example if `--local-subject abc`, The message will be received as `abc.a.b.c.>`.
|
||||
|
||||
And verifying it:
|
||||
|
||||
@@ -119,14 +119,13 @@ Let's also add a user to make requests from the service:
|
||||
|
||||
### Testing the Stream
|
||||
|
||||
```bash
|
||||
```bash
|
||||
> nsc sub --account B --user b "a.b.c.>"
|
||||
Listening on [a.b.c.>]
|
||||
...
|
||||
> nsc pub --account A --user U a.b.c.hello world
|
||||
Published [a.b.c.hello] : "world"
|
||||
...
|
||||
[#1] received on [a.b.c.hello]: 'world'
|
||||
```
|
||||
|
||||
## Securing Streams
|
||||
@@ -177,12 +176,11 @@ Similarly when we defined an export, but this time we added the `--private` flag
|
||||
╰───────────────┴────────┴───────────────┴────────┴─────────────┴──────────╯
|
||||
```
|
||||
|
||||
|
||||
### Generating an Activation Token
|
||||
|
||||
For a foreign account to _import_ a private stream, you have to generate an activation token. In addition to granting permissions to the account, the activation token also allows you to subset the exported stream’s subject.
|
||||
|
||||
To generate a token, you’ll need to know the public key of the account importing the service. We can easily find the public key for account B by running:
|
||||
To generate a token, you’ll need to know the public key of the account importing the service. We can easily find the public key for account B by running:
|
||||
|
||||
```bash
|
||||
> nsc list keys --account B
|
||||
@@ -203,7 +201,7 @@ To generate a token, you’ll need to know the public key of the account importi
|
||||
[ OK ] wrote account description to "/tmp/activation.jwt"
|
||||
```
|
||||
|
||||
The command took the account that has the export ('A'), the public key of account B, the subject where the stream will publish to account B.
|
||||
The command took the account that has the export \('A'\), the public key of account B, the subject where the stream will publish to account B.
|
||||
|
||||
For completeness, the contents of the JWT file look like this:
|
||||
|
||||
@@ -239,7 +237,7 @@ When decoded it looks like this:
|
||||
╰─────────────────┴──────────────────────────────────────────────────────────────────────╯
|
||||
```
|
||||
|
||||
The token can be shared directly with the client account.
|
||||
The token can be shared directly with the client account.
|
||||
|
||||
> If you manage many tokens for many accounts, you may want to host activation tokens on a web server and share the URL with the account. The benefit to the hosted approach is that any updates to the token would be available to the importing account whenever their account is updated, provided the URL you host them in is stable.
|
||||
|
||||
@@ -289,13 +287,12 @@ Importing a private stream is more natural than a public one as the activation t
|
||||
|
||||
Testing a private stream is no different than a public one:
|
||||
|
||||
```bash
|
||||
```bash
|
||||
> nsc sub --account B --user b private.abc.AAM46E3YF5WOZSE5WNYWHN3YYISVZOSI6XHTF2Q64ECPXSFQZROJMP2H
|
||||
Listening on [private.abc.AAM46E3YF5WOZSE5WNYWHN3YYISVZOSI6XHTF2Q64ECPXSFQZROJMP2H]
|
||||
...
|
||||
> nsc pub --account A --user U private.abc.AAM46E3YF5WOZSE5WNYWHN3YYISVZOSI6XHTF2Q64ECPXSFQZROJMP2H hello
|
||||
Published [private.abc.AAM46E3YF5WOZSE5WNYWHN3YYISVZOSI6XHTF2Q64ECPXSFQZROJMP2H] : "hello"
|
||||
...
|
||||
[#1] received on [private.abc.AAM46E3YF5WOZSE5WNYWHN3YYISVZOSI6XHTF2Q64ECPXSFQZROJMP2H]: 'hello'
|
||||
```
|
||||
|
||||
|
||||
Reference in New Issue
Block a user