diff --git a/AUTH.md b/AUTH.md index b150dbfd..c84b05b7 100644 --- a/AUTH.md +++ b/AUTH.md @@ -4,13 +4,13 @@ The `nats auth` command is a new addition that aims to bring the most common fea the `nats` command. The aim is not to have 100% feature parity but rather to provide a easy to use solution for what most people will use. -It remains compatible with the `nsc` store and so users can switch between these commands. +It remains compatible with the `nsc` storage format and default storage location, so users can switch between these commands. It is implemented using a new [Go SDK](https://github.com/synadia-io/jwt-auth-builder.go/) allowing programmatic interaction with the `nsc` store. -This guide is based on the [nsc documentation](https://docs.nats.io/using-nats/nats-tools/nsc) and attempts to -achieve the same outcome. +This guide replicates the steps in the getting started guide of [nsc basics documentation](https://docs.nats.io/using-nats/nats-tools/nsc/basics) and attempts to + ## Limitations @@ -111,7 +111,21 @@ Permissions: ## Configuring NATS Server -Using `nats server generate` create a configuration file which will pre-load the important JWTs. +Using `nats server generate nats-server.conf` create a configuration file which will pre-load the important JWTs. +``` +This tool generates NATS Server configurations based on a question and answer +form-based approach and then renders the result into a directory. + +It supports rendering local bundles compiled into the 'nats' command but can also +fetch and render remote ones using a URL. + +[LOCAL] ? Select a template [Use arrows to move, type to filter] +> 'nats auth' managed NATS Server configuration + Development Super Cluster using Docker Compose + Synadia Cloud Leafnode Configuration +``` + +Starting with the generated config, the server log should show the trusted operators. ``` $ nats-server --config nats-server.conf @@ -123,12 +137,12 @@ $ nats-server --config nats-server.conf [31] 2024/04/23 09:49:20.430708 [INF] Expires : Never ``` -The dynamic account - `MyAccount` in this case - needs to be sent to the NATS Server `SYSTEM` account before you can use it. +## Creating a system user to connect to the new server + +The newly created account - `MyAccount` in this case - needs to be sent to the NATS Server's `SYSTEM` account before you can use it. To do this we need a `SYSTEM` account user and credential. -Unlike `nsc` that makes credentials on demand to push to the servers we use contexts to authenticate to the system account -which feels more in-line with how the `nats` command works. We need a user and credentials for a system user, if we do -not supply the username or account they will be prompted for: +Unlike `nsc`, which makes credentials on demand to push to the servers, we use contexts to authenticate to the system account which feels more in-line with how the `nats` command works. We create a user and credentials for a system user. ``` # nats auth user add admin SYSTEM @@ -136,7 +150,7 @@ not supply the username or account they will be prompted for: Wrote credential for admin to /path/to/system.cred # nats ctx add system --description "System Account" --server localhost:4222 --creds /path/to/system.cred ``` - +## Synchronizing the configuration Next we use the credential we just made to push to the server: ``` @@ -148,7 +162,7 @@ Updating account MyAccount (ADNJMEHSIAQAE3X5EKGABVVOFX3GECHZKG6M4DK72ZDHEPQ5YW4C Success 1 Failed 0 Expected 1 ``` -## User Authorization +## User authentication and login To do a basic test of publish / subscribe we can use the user we created earlier: @@ -173,6 +187,8 @@ And in a another terminal we communicate with it: x ``` +## User with subject based authorization + Now lets lock the requester and responder down, we'll add a user for the service with appropriate permissions. First the user for the service and in the same command we save its credential: @@ -206,7 +222,7 @@ Permissions: x ``` -And we confirm the limits are applied by subscribing to an invalid subject: +And we confirm the restrictions are applied by subscribing to an invalid subject: ``` # nats req other x --creds myuser.cred @@ -214,7 +230,7 @@ And we confirm the limits are applied by subscribing to an invalid subject: 10:36:36 Unexpected NATS error from server nats://127.0.0.1:4222: nats: Permissions Violation for Publish to "other" ``` -## Imports and Exports +## Subject Imports and Exports For the examples below we'll add an account and some users with their credentials: diff --git a/cli/auth_command.go b/cli/auth_command.go index 77b5ea4f..da381239 100644 --- a/cli/auth_command.go +++ b/cli/auth_command.go @@ -15,11 +15,12 @@ package cli func configureAuthCommand(app commandHost) { auth := app.Command("auth", "NATS Decentralized Authentication") + addCheat("auth", auth) // todo: // - Improve maintaining pub/sub permissions for a user, perhaps allow interactive edits of yaml? - auth.HelpLong("WARNING: This is experimental and subject to massive change, do not use yet") + auth.HelpLong("WARNING: This is experimental and subject to change, do not use yet for production deployment. ") configureAuthOperatorCommand(auth) configureAuthAccountCommand(auth) diff --git a/cli/cheats/auth.md b/cli/cheats/auth.md new file mode 100644 index 00000000..5944e52f --- /dev/null +++ b/cli/cheats/auth.md @@ -0,0 +1,33 @@ +# Basic steps for setting up decentralized authentication +All configuration changes are stored locally until `nats auth account push`ed to a nats cluster. + +# Create a new operator and set as working context +nats auth operator add sysopp + +# Generate a template server configuration file from an operator +nats server generate server.conf + +# Create a new account +nats auth account add MyAccount + +# Create a new user in an account +nats auth user add MyUser + +# Create an admin user in system account +nats auth user add admin SYSTEM + +# Export credentials for a user +nats auth user credential sys_admin.cred admin SYSTEM + +# Push an account or its changes from a specific operator to a specific server, using system account credentials. +nats auth account push MyAccount --server nats://localhost:4222 --operator sysopp --creds sys_admin.cred + +# Use `nats context` and `nats auth operator select` to set defaults +nats context add sysadmin --description "System Account" --server nats://localhost:4222 --creds sys_admin.cred + +nats auth operator select sysopp + +# Push account with default settings +nats auth account push MyAccount + +