-
Notifications
You must be signed in to change notification settings - Fork 147
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Browse files
Browse the repository at this point in the history
- Loading branch information
Showing
4 changed files
with
46 additions
and
70 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,96 +1,71 @@ | ||
| +++ | ||
| date = "2016-06-23" | ||
| date = "2018-05-22" | ||
| title = "Server Authorization" | ||
| description = "" | ||
| category = "server" | ||
| [menu.documentation] | ||
| [menu.main] | ||
| name = "Server Authorization" | ||
| weight = 3 | ||
| identifier = "server-gnatsd-authorization" | ||
| parent = "server" | ||
| parent = "Server" | ||
| +++ | ||
|
|
||
| The latest release of the NATS Server (0.9.0) supports user/client authorization using subject-level permissioning. | ||
| # NATS Server Authorization | ||
|
|
||
| Subject-level permissioning is available with multi-user authentication configurations and leverages configuation variables. You enable multi-user authentication and permissioning using a NATS Server configuration file that defines the user credentials and permissions. | ||
| The NATS server supports authorization using subject-level permissions on a per-user basis. Permission-based authorization is available with [multi-user authentication](/documentation/server/gnatsd-authentication/). | ||
|
|
||
| ## Usage | ||
| 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 make use of [variables](/documentation/server/gnatsd-config/#variables). | ||
|
|
||
| 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. Authorization filters (subjects) can be a singleton or an array. Subjects can contain wildcards. | ||
|
|
||
| ``` | ||
| PERMSSION_NAME // Variable | ||
| publish // Singleton or array | ||
| subscribe // Singleton or array | ||
| ``` | ||
|
|
||
| ## Example | ||
|
|
||
| For example, since Alice is an ADMIN she can publish/subscribe on any subject. We use the wildcard “>” to match any subject. | ||
| You set permissions by creating an entry inside of the `authorization` configuration block that conforms to the following syntax: | ||
|
|
||
| ``` | ||
| authorization { | ||
| ADMIN = { | ||
| publish = ">" | ||
| subscribe = ">" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Bob is REQUESTOR and can publish requests on subjects req.foo or req.bar, and subscribe to anything that is a response (_INBOX.*). | ||
|
|
||
| ``` | ||
| authorization { | ||
| REQUESTOR = { | ||
| publish = ["req.foo", "req.bar"] | ||
| subscribe = "_INBOX.*" | ||
| PERMISSION_NAME = { | ||
| publish = "singleton" or ["array", ...] | ||
| subscribe = "singleton" or ["array", ...] | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Note that the publish field is an array with two subjects; the subscribe field is a singleton. The parser is generous at understanding what the intent is, so arrays and singletons are processed. | ||
| # Example | ||
|
|
||
| Joe has no permission grant 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. | ||
| Here is an example authorization configuration that defines four users, three of whom are assigned explicit permissions. | ||
|
|
||
| ``` | ||
| authorization { | ||
| default_permissions = { | ||
| publish = "SANDBOX.*" | ||
| subscribe = ["PUBLIC.>", "_INBOX.>"] | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Note that `_INBOX.*` subscribe permissions must be granted in order to use the request APIs in the Synadia supported clients. If an unauthorized client publishes or attempts to subscribe to a subject, the action fails and is logged at the server, and an error message is returned to the client. | ||
|
|
||
| ## Complete example | ||
|
|
||
| ``` | ||
| authorization { | ||
| ADMIN = { | ||
| publish = ">" | ||
| subscribe = ">" | ||
| } | ||
| REQUESTOR = { | ||
| publish = ["req.foo", "req.bar"] | ||
| subscribe = "_INBOX.*" | ||
| subscribe = "_INBOX.>" | ||
| } | ||
| RESPONDER = { | ||
| subscribe = ["req.foo", "req.bar"] | ||
| publish = "_INBOX.>" | ||
| } | ||
| DEFAULT_PERMISSIONS = { | ||
| publish = "SANDBOX.*" | ||
| subscribe = ["PUBLIC.>", "_INBOX.>"] | ||
| } | ||
| PASS: abcdefghijklmnopqrstuvwxwz0123456789 | ||
| users = [ | ||
| {user: alice, password: foo, permissions: $ADMIN} | ||
| {user: bob, password: bar, permissions: $REQUESTOR} | ||
| {user: joe, password: $PASS} | ||
| {user: joe, password: foo, permissions: $ADMIN} | ||
| {user: alice, password: bar, permissions: $REQUESTOR} | ||
| {user: bob, password: $PASS, permissions: $RESPONDER} | ||
| {user: charlie, password: bar} | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| Note that the variable identifier (name) is not case sensitive, but is capitalized by convention for readability. The variable is referenced using the $ character. | ||
| Since Joe is an ADMIN he can publish/subscribe on any subject. We use the wildcard “>” to match any subject. | ||
|
|
||
| Alice is a REQUESTOR and can publish requests on subjects "req.foo" or "req.bar", and subscribe to anything that is a response ("_INBOX.>"). | ||
|
|
||
| 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. | ||
|
|
||
| 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.>. | ||
|
|
||
| Important to 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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters