Merge pull request #61 from nats-io/ngs_nsc

Added documentation for deployment, migration, etc...

SUMMARY.md

@@ -117,6 +117,8 @@
   * [Streams](nats_tools/nsc/streams.md)
   * [Services](nats_tools/nsc/services.md)
   * [Signing Keys](nats_tools/nsc/signing_keys.md)
+  * [Revocation](nats_tools/nsc/revocation.md)
+  * [Managed Operators](nats_tools/nsc/managed.md)
 * [nats-account-server](nats_tools/nas/README.md)
   * [Basics](nats_tools/nas/nas_conf.md)
   * [Inspecting JWTs](nats_tools/nas/inspecting_jwts.md)

nats_tools/nsc/README.md

@@ -1,13 +1,14 @@
-## NATS Account Configuration
+# NATS Account Configuration
 
 NATS account configurations are built using the `nsc` tool. The NSC tool allows you to:
 
-- Create and Edit Operators, Accounts, Users
+- Create and edit Operators, Accounts, Users
 - Manage subscribe and publish permissions for Users
 - Add and delete Exports and Imports
-- Generate Activations
+- Generate Activation tokens
 - Generate User credential files
 - Describe Operators, Accounts, Users, and Activations
+- Push account JWTs to a server or pull account JWTs from a server
 
 ## Installation
 
@@ -27,6 +28,8 @@ You can find various task-oriented tutorials to working with the tool here:
 - [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
 
@@ -37,5 +40,4 @@ It can be found within the tool itself:
 > nsc help
 ```
 
-Or an online version [here](https://nats-io.github.io/nsc)
+Or an online version [here](https://nats-io.github.io/nsc).
-

nats_tools/nsc/managed.md

@@ -0,0 +1,59 @@
+# Working with Managed Operators
+
+You can use `nsc` to administer multiple operators. Operators can be thought of as the owners of nats-servers, and fall into two categories: local and managed. The key difference, pardon the pun, is that managed operators are ones which you don't have the nkey for. An example of a managed operator is the Synadia service called NGS. Synadia has the keys.
+
+Accounts, as represented by their JWTs, are signed by the operator. Some operators may use local copies of JWTs, others may use the [nats-account-server](../nas/README.md) to manage their JWTs. Synadia uses a custom server for their JWTs that works similarly to the open-sourced account server.
+
+There are a few special commands when dealing with server based operators:
+
+* Account JWTs can be pushed to the server using `nsc push`
+* Account JWTs can be pulled from a server using `nsc pull`
+
+For managed operators this push/pull behavior is built into `nsc`. Each time you edit your account JWT `nsc` will push the change to a managed operator's server and pull the signed response. If this fails the JWT on disk may not match the value on the server. You can always push or pull the account again without editing it. Note - push only works if the operator JWT was configured with an account server URL.
+
+The managed operator will not only sign your account JWT with its key, but may also edit the JWT to include limits to constrain your access to their NATS servers. Some operators may also add demonstration or standard imports. Generally you can remove these, although the operator gets the final call on all Account edits. As with any deployment, the managed operator doesn't track user JWTs.
+
+To start using a managed operator you need to tell `nsc` about it. There are a couple ways to do this. First you can manually tell `nsc` to download the operator JWT using the `add operator` command:
+
+```bash
+% nsc add operator -u http://localhost:6060/jwt/v1/operator
+```
+
+The URL you pass in should be provided to you by the operator. The second way to add a managed operator is with the `init` command:
+
+```bash
+% nsc init -u http://localhost:6060/jwt/v1/operator -n alpha
+```
+
+or
+
+```bash
+% nsc init -o synadia -n alpha
+```
+
+In the second case you can use the name of an existing operator, or a well known one (currently only "synadia").
+
+Once you add a managed operator you can add accounts to it normally, with the caveat that new accounts are pushed and pulled as described above.
+
+## Defining "Well Known Operators"
+
+To define a well known operator, you would tell `nsc` about an operator that you want people in your environment to use by name with a simple environment variable of the form `nsc_<operator name>_operator` the value of this environment variable should be the URL for getting the operator JWT. For example:
+
+```bash
+export nsc_zoom_operator=https://account-server-host/jwt/v1/operator
+```
+
+will tell `nsc` that there is a well known operator named zoom with its JWT at `https://account-server-host/jwt/v1/operator`. With this definition you can now use the `-u` flag with the name "zoom" to add the operator to an `nsc` store directory.
+
+The operator JWT should have its account JWT server property set to point to the appropriate URL. For our example this would be:
+
+```bash
+nsc edit operator -u https://account-server-host/jwt/v1
+```
+
+You can also set one or more service urls. These allow the `nsc tool` actions like pub and sub to work. For example:
+
+```bash
+nsc edit operator -n nats://localhost:4222
+nsc tool pub hello world
+```

nats_tools/nsc/nsc.md

@@ -1,4 +1,4 @@
-## NSC
+# NSC
 
 NATS uses JWTs to armor the various identity and authorization artifacts. These JWTs are created with the `nsc` tool. NSC simplifies the tasks of creating and managing identities and other JWT artifacts.
 
@@ -20,11 +20,11 @@ In this guide, you’ll run end-to-end on some of the configuration scenarios:
 
 Let’s run through the process of creating some identities and JWTs and work through the process.
 
-By default JWTs are written to `~/.nsc` and secrets to `~/.nkeys`. You can easily change those locations by setting `NSC_HOME` and `NKEYS_PATH` respectively in your environment to your desired locations.
+## The NSC Environment
 
-> The $NKEYS_PATH stores secrets. Since nkeys relies on cryptographic signatures to prove identity, anyone with access to your private keys will be able to assume your identity. With that said, treat them as secrets and guard them carefully.
+By default JWTs are written to ~/.nsc and secrets to ~/.nkeys. nsc also tracks a value called the "stores directory". This directory contains the operators you are currently working with. By default the stores directory is ~/.nsc/nats but you can switch it to another folder if you want to separate JWTs for use in a revision control system, or co-locate them with a project, etc..
 
-Let’s see what settings `nsc` has in its environment:
+To see the current NSC environment use the command `nsc env`:
 
 ```text
 > nsc env
@@ -44,10 +44,13 @@ Let’s see what settings `nsc` has in its environment:
 ╰──────────────────┴─────┴─────────────────╯
 ```
 
-By default you’ll see that generated secrets are stored in `~/.nkeys`, and configurations in `~/.nsc/nats`. All operations are assumed to be in a context of the current operator and current account. When working with multiple operators and accounts you may need to set the current one. You can easily do so by issuing the `nsc env` and provide flags to set the current operator or account. See `nsc env —help` for more details.
+As you can see there is a setting for the nkeys folder and the nsc home. By default you’ll see that generated secrets are stored in `~/.nkeys`, and configurations in `~/.nsc/nats`. All operations are assumed to be in a context of the current operator and current account. When working with multiple operators and accounts you may need to set the current one. You can easily do so by issuing the `nsc env` and provide flags to set the current operator or account. See `nsc env —help` for more details.
 
+You can easily change the home and keys locations by setting `NSC_HOME` and `NKEYS_PATH` respectively in your environment to your desired locations. The environment itself is stored in the `NSC_HOME`. Operator folders are in the stores directory which can be inside `NSC_HOME` or external to it.
 
-#### Creating an Operator
+> The $NKEYS_PATH stores secrets. Since nkeys relies on cryptographic signatures to prove identity, anyone with access to your private keys will be able to assume your identity. With that said, treat them as secrets and guard them carefully.
+
+## Creating an Operator
 
 Let’s create an operator called `Test`:
 
@@ -93,9 +96,11 @@ Note that the Operator ID is truncated to simplify the output, to get the full I
 ╰─────────────┴──────────────────────────────────────────────────────────╯
 ```
 
+The operator JWT contains two important URLs. The `account-jwt-server-url` is used by `nsc` when you want to push JWTs to an account server. The `service-url`s are used by `nsc` when you run the tool commands, like `nsc tool pub`.
+
 With an operator, we are ready to create our first account.
 
-#### Creating an Account
+## Creating an Account
 
 Let’s create an account called `TestAccount`:
 
@@ -138,7 +143,7 @@ Note that the issuer for the account is the ID for the operator (the public key
 
 Now we are ready to add a user.
 
-#### Creating a User
+## Creating a User
 
 Let’s add a user named ‘TestUser’:
 
@@ -173,7 +178,7 @@ And let’s describe it:
 
 Let’s put all of this together, and create a simple server configuration that accepts sessions from TestUser.
 
-### Account Server Configuration
+## Account Server Configuration
 
 To configure a server to use accounts you need an _account resolver_. An account resolver exposes a URL where a nats-server can query for JWTs belonging to an account.
 
@@ -193,9 +198,11 @@ The account server has options to enable you to use an nsc directory directly. L
 
 Above we pointed the account server to our nsc data directory (more specifically to the `Test` operator that we created earlier). By default, the server listens on the localhost at port 9090.
 
-We are now ready to configure the nats-server
+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.
 
-### NATS Server Configuration
+We are now ready to configure the nats-server.
+
+## NATS Server Configuration
 
 If you don’t have a nats-server installed, let’s do that now:
 
@@ -212,7 +219,7 @@ resolver: URL(http://localhost:9090/jwt/v1/accounts/)
 
 At minimum the server requires the `operator` JWT, which we have pointed at directly, and a resolver. The resolver has two types `MEM` and `URL`. We are interested in the `URL` since we want the nats-server to talk to the account server. Note we put the URL of the server with the path `/jwt/v1/accounts`. Currently this is where the account server expects requests for account information.
 
-### Client Testing
+## Client Testing
 
 Let’s install some tooling:
 
@@ -223,23 +230,26 @@ Let’s install some tooling:
 ```
 
 Create a subscriber:
+
 ```text
 nats-sub -creds ~/.nkeys/Test/accounts/TestAccount/users/TestUser.creds ">"
 Listening on [>]
 ```
 
 Publish a message:
+
 ```text
 nats-pub -creds ~/.nkeys/Test/accounts/TestAccount/users/TestUser.creds hello NATS 
 Published [hello] : 'NATS'
 ```
 
 Subscriber shows:
+
 ```text
 [#1] Received on [hello]: ’NATS’
 ```
 
-### User Authorization
+## 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.
 
@@ -304,4 +314,3 @@ Success! - added user "TestClient" to "TestAccount"
 ```
 
 The client has the opposite permissions of the service. It can publish on the request subject `req.a`, and receive replies on an inbox.
-

nats_tools/nsc/revocation.md

@@ -0,0 +1,28 @@
+# Revocation
+
+NATS supports two types of revocations. Both of these are stored in the Account JWT, so that the nats-server can see the revocations and apply them.
+
+Users are revoked by public key and time. Access to an export, called an activation, can be revoked for a specific account at a specific time. The use of time here can be confusing, but is designed to support the primary uses of revocation.
+
+When a user or activation is revoked at time T, it means that any user JWT or activation token created before that time is invalid. If a new user JWT or new activation token is created after T it can be used. This allows an account owner to revoke a user and renew their access at the same time.
+
+Let's look at an example. Suppose you created a user JWT with access to the subject "billing". Later you decide you don't want that user to have access to "billing". Revoke the user, say at noon on May 1st 2019, and create a new user JWT without access to "billing". The user can no longer log in with the old JWT because it is revoked, but they can log in with the new JWT because it was created after noon May 1st 2019.
+
+`nsc` provides a number of commands to create, remove or list revocations:
+
+```bash
+Usage:
+  nsc revocations [command]
+
+Available Commands:
+  add_activation    Revoke an accounts access to an export
+  add_user          Revoke a user
+  delete_activation Remove an account revocation from an export
+  delete_user       Remove a user revocation
+  list_activations  List account revocations for an export
+  list_users        List users revoked in an account
+```
+
+Both add commands take the flag `--at` which defaults to 0, for now, which can be used to set the unix timestamp as described above. By default revocations are at the current time, but you can set them in the past for situations where you know when a problem occurred and was fixed.
+
+Deleting a revocation is permanent and can allow an old activation or user JWT to be valid again. Therefore delete should only be used if you are sure the tokens in question have expired.

nats_tools/nsc/services.md

@@ -1,8 +1,8 @@
-## Services
+# Services
 
 To share services that other accounts can reach via request reply, you have to _Export_ a _Service_. _Services_ are associated with the account performing the replies and are advertised in the exporting accounts' JWT.
 
-### Adding a Public Service Export
+## Adding a Public Service Export
 
 To add a service to your account:
 
@@ -44,7 +44,7 @@ To review the service export:
 ╰──────┴─────────┴─────────┴────────╯
 ```
 
-### Importing a Service
+## Importing a Service
 
 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:
 
@@ -61,7 +61,7 @@ To learn how to inspect a JWT from an account server, [check this article](../na
 Success! - added service import "help"
 ```
 
-Verifying our handywork:
+Verifying our work:
 
 ```text
 > nsc describe account
@@ -123,7 +123,6 @@ And the response is received by the requestor:
 Received  [_INBOX.v6KAX0v1bu87k49hbg3dgn.StIGJF0D] : 'I will help'
 ```
 
-
 ## Securing Services
 
 If you want to create a service that is only accessible to accounts you designate you can create a _private_ service. The export will be visible in your account, but subscribing accounts will require an authorization token that must be created by you and generated specifically for the requesting account.

nats_tools/nsc/signing_keys.md

@@ -1,4 +1,4 @@
-## Signing Keys
+# Signing Keys
 
 As previously discussed, NKEYs are identities, and if someone gets a hold of an account or operator nkey they can do everything you can do as you.
 
@@ -21,7 +21,6 @@ Let’s get a feel for the workflow. We are going to:
 - 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.
 
 Creating the operator:
@@ -71,7 +70,6 @@ Check our handy work:
 ╰──────────────┴─────────────────────────╯
 ```
 
-
 Now let’s create an account called `A` and sign it the generated operator private signing key. To sign it with the key specify the `-K` flag and the private key or a path to the private key:
 
 ```text
@@ -89,6 +87,7 @@ ABHYL27UAHHQXA5HLH2YWHFQBIP4YMPC7RNZ4PSFRAMJHSSZUUIXF2RV
 ```
 
 Let’s add the signing key to the account, and remember to sign the account with the operator signing key:
+
 ```text
 > nsc edit account --sk ABHYL27UAHHQXA5HLH2YWHFQBIP4YMPC7RNZ4PSFRAMJHSSZUUIXF2RV -K SOAIHSQSAM3ZJI5W6U5M4INH7FUCQQ5ETJ5RMPVJZCJLTDREY6ZNEE6LZQ 
 Success! - edited account "A"
@@ -149,4 +148,3 @@ Success! - added user "U" to "A"
 ```
 
 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_.
-

nats_tools/nsc/streams.md

@@ -1,4 +1,4 @@
-## Streams
+# Streams
 
 To share messages you publish with other accounts, you have to _Export_ a _Stream_. _Exports_ are associated with the account performing the export and advertised in exporting account’s JWT.