diff --git a/SUMMARY.md b/SUMMARY.md index 949c3ab..82df928 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -34,7 +34,7 @@ * [Slow Consumers](nats_admin/slow_consumers.md) * [Signals](nats_admin/signals.md) * [System Accounts](sys_accounts/README.md) - * [Configuration](sys_accounts/sysaccounts.md) + * [Configuration](sys_accounts/sys_accounts.md) ### NATS Tools * [Tools](nats_tools/README.md) diff --git a/nats_server/auth_intro.md b/nats_server/auth_intro.md index 16c86e1..88bade9 100644 --- a/nats_server/auth_intro.md +++ b/nats_server/auth_intro.md @@ -2,14 +2,14 @@ The NATS server provides various ways of authenticating clients: -- Token Authentication -- Username/Password credentials -- TLS Certificate -- NKEY with Challenge -- JWTs with Challenge +- [Token Authentication](tokens.md) +- [Username/Password credentials](username_password.md) +- [TLS Certificate](tls_mutual_auth.md) +- [NKEY with Challenge](nkey_auth.md) +- [JWTs with Challenge](jwt_auth.md) Authentication deals with allowing a NATS client to connect to the server. -With the exception of JWT authentication, authentication and authorization configuration is in the `authorization` block of the configuration. +With the exception of JWT authentication, authentication and authorization is configured in the `authorization` section of the configuration. ## Authorization Map @@ -17,12 +17,13 @@ The `authorization` block provides _authentication_ configuration as well as _au | Property | Description | | :------ | :---- | -| [`token`](tokens.md) | Specifies a token that can be used to authenticate to the server | -| [`user`](username_password.md) | Specifies a single user name for clients to the server | -| [`password`](username_password.md) | Specifies a single password for clients to the server | +| [`token`](tokens.md) | Specifies a global token that can be used to authenticate to the server (exclusive of user and password) | +| [`user`](username_password.md) | Specifies a single _global_ user name for clients to the server (exclusive of token) | +| [`password`](username_password.md) | Specifies a single _global_ password for clients to the server (exclusive of `token`) | | `users` | A list of `user` configuration maps | | `timeout` | Maximum number of seconds to wait for client authentication | +For multiple username and password credentials, specify a `users` list. ### User Configuration Map @@ -34,31 +35,4 @@ A `user` configuration map specifies credentials and permissions options for a s | [`user`](username_password.md) | username for client authentication | | [`password`](username_password.md) | password for the user entry | | [`nkey`](nkey_auth.md) | public nkey identifying an user | -| `permissions` | permissions map configuring subjects accessible to the user | - - -### Permissions Configuration Map - -The `permissions` map specify subjects that can be subscribed to or published by the specified client. - -| Property | Description | -| :------ | :---- | -| `publish` | subject or list of subjects or permission map the client can publish | -| `subscribe` | subject or list of subjects or permission map the client can publish | - -### Permission Map - -The `permission` map provides additional properties for configuring subject permissions: - -| Property | Description | -| :------ | :---- | -| `allow` | List of subject names that are allowed to the client | -| `deny` | List of subjects that are denied to the client | - - - - - - - - +| [`permissions`](authorization.md) | permissions map configuring subjects accessible to the user | diff --git a/nats_server/authorization.md b/nats_server/authorization.md index ee760cb..c53e060 100644 --- a/nats_server/authorization.md +++ b/nats_server/authorization.md @@ -1,25 +1,37 @@ ## Authorization -The NATS server supports authorization using subject-level permissions on a per-user basis. Permission-based authorization is available with [multi-user authentication](/documentation/managing_the_server/authentication/). -Each permission grant is an object with two fields: what subject(s) the authenticated user can publish to, and what subject(s) the authenticated user can subscribe to. The parser is generous at understanding what the intent is, so both arrays and singletons are processed. Subjects themselves can contain wildcards. Permissions can make use of [variables](/documentation/managing_the_server/configuration). +The NATS server supports authorization using subject-level permissions on a per-user basis. Permission-based authorization is available withmulti-user authentication via the `users` list. + +Each permission specifies the subjects the user can publish to and subscribe to. The parser is generous at understanding what the intent is, so both arrays and singletons are processed. For more complex configuation you can specify a `permission` object which explicetly allows or denies subjects. The specified subjects can specify wildcards. Permissions can make use of [variables](configuration.md#variables). + +You configure authorization by creating a `permissions` entry in the `authorization` object. + +### Permissions Configuration Map + +The `permissions` map specify subjects that can be subscribed to or published by the specified client. + +| Property | Description | +| :------ | :---- | +| `publish` | subject, list of subjects, or permission map the client can publish | +| `subscribe` | subject, list of subjects, or permission map the client can publish | + +### Permission Map + +The `permission` map provides additional properties for configuring a `permissions` map. Instead of providing a list of subjects that are allowed, the `permission` map allows you to explicitely list subjects you want to`allow` or `deny`: + +| Property | Description | +| :------ | :---- | +| `allow` | List of subject names that are allowed to the client | +| `deny` | List of subjects that are denied to the client | -You set permissions by creating an entry inside of the `authorization` configuration block that conforms to the following syntax: -```ascii -authorization { - PERMISSION_NAME = { - publish = "singleton" or ["array", ...] - subscribe = "singleton" or ["array", ...] - } -} -``` **Important Note** NATS Authorizations are whitelist only, meaning in order to not break request/reply patterns you need to add rules as above with Alice and Bob for the `_INBOX.>` pattern. If an unauthorized client publishes or attempts to subscribe to a subject that has not been whitelisted, the action fails and is logged at the server, and an error message is returned to the client. ### Example -Here is an example authorization configuration that defines four users, three of whom are assigned explicit permissions. +Here is an example authorization configuration that uses _variables_ which defines four users, three of whom are assigned explicit permissions. ```ascii authorization { @@ -28,31 +40,34 @@ authorization { subscribe = ">" } REQUESTOR = { - publish = ["req.foo", "req.bar"] + publish = ["req.a", "req.b"] subscribe = "_INBOX.>" } RESPONDER = { - subscribe = ["req.foo", "req.bar"] + subscribe = ["req.a", "req.b"] publish = "_INBOX.>" } DEFAULT_PERMISSIONS = { publish = "SANDBOX.*" subscribe = ["PUBLIC.>", "_INBOX.>"] } - PASS: abcdefghijklmnopqrstuvwxwz0123456789 users = [ - {user: joe, password: foo, permissions: $ADMIN} - {user: alice, password: bar, permissions: $REQUESTOR} - {user: bob, password: $PASS, permissions: $RESPONDER} - {user: charlie, password: bar} + {user: admin, password: $ADMIN_PASS, permissions: $ADMIN} + {user: client, password: $CLIENT_PASS, permissions: $REQUESTOR} + {user: service, password: $SERVICE_PASS, permissions: $RESPONDER} + {user: other, password: $OTHER_PASS} ] } ``` -Since Joe is an ADMIN he can publish/subscribe on any subject. We use the wildcard `>` to match any subject. +> *DEFAULT_PERMISSIONS* is a special permissions name. If defined, it applies to all users that don't have specific permissions set. -Alice is a REQUESTOR and can publish requests on subjects `req.foo` or `req.bar`, and subscribe to anything that is a response (`_INBOX.>`). +- _admin_ has `ADMIN` permissions and can publish/subscribe on any subject. We use the wildcard `>` to match any subject. -Charlie has no permissions granted and therefore inherits the default permission set. You set the inherited default permissions by assigning them to the default_permissions entry inside of the authorization configuration block. +- _client_ is a `REQUESTOR` and can publish requests on subjects `req.a` or `req.b`, and subscribe to anything that is a response (`_INBOX.>`). -Bob is a RESPONDER to any of Alice's requests, so Bob needs to be able to subscribe to the request subjects and respond to Alice's reply subject which will be an `_INBOX.>`. \ No newline at end of file +- _service_ is a `RESPONDER` to `req.a` and `req.b` requests, so it needs to be able to subscribe to the request subjects and respond to client's that are able to publish requests to `req.a` and `req.b`. The reply subject subject is an inbox. Typically inboxes start with the prefix `_INBOX.` followed by a generated string. The `_INBOX.>` subject matches all subjects that start with `_INBOX.`. + +- _other_ has no permissions granted and therefore inherits the default permission set. You set the inherited default permissions by assigning them to the `default_permissions` entry inside of the authorization configuration block. + +> Note that in the above example, any client with permissions to subscribe to `_INBOX.>` is able to receive _all_ responses published. More sensitive installations will want to add or subset the prefix to further limit what a client can subscribe to. Alternatively [_Accounts_](jwt_auth.md) allow complete isolation limiting what members of an account can see. diff --git a/nats_server/running.md b/nats_server/running.md index ef38fc0..bdcc261 100644 --- a/nats_server/running.md +++ b/nats_server/running.md @@ -23,7 +23,7 @@ When the server starts it will print some information including where the server If you are running your NATS server in a docker container: ``` -> docker run -p 4222:4222 -ti nats-server:latest +> docker run -p 4222:4222 -ti nats:latest [1] 2019/05/13 14:55:11.981434 [INF] Starting nats-server version 2.0.0 ... [1] 2019/05/13 14:55:11.981545 [INF] Starting http monitor on 0.0.0.0:8222 diff --git a/sys_accounts/README.md b/sys_accounts/README.md index 3a9c2cd..94fd536 100644 --- a/sys_accounts/README.md +++ b/sys_accounts/README.md @@ -1,4 +1,4 @@ -## System Accounts +## System Events NATS servers leverage [Account](nats_server/jwt_auth.md) support and generate events such as: @@ -9,7 +9,7 @@ NATS servers leverage [Account](nats_server/jwt_auth.md) support and generate ev In addition the server supports a limitted number of requests that can be used to query for account connections, server stat summaries, and pinging servers in the cluster. -These events are only accepted and visible to system account users. +These events are only accepted and visible to _system account_ users. ### The System Events Tutorial You can learn more about System Accounts in the [Tutorial](sys_accounts.md). diff --git a/sys_accounts/sys_accounts.md b/sys_accounts/sys_accounts.md index 78a56e7..722271b 100644 --- a/sys_accounts/sys_accounts.md +++ b/sys_accounts/sys_accounts.md @@ -1,4 +1,4 @@ -## System Account Tutorial +## System Events Tutorial The following is a short tutorial on how you can activate a system account to: