From 62a7de85bbcf919a60306a7d399afa8b673aa68b Mon Sep 17 00:00:00 2001 From: Matthias Hanel Date: Wed, 5 Feb 2020 18:43:12 -0500 Subject: [PATCH] Move queue permissions, hint at queue name hierarchy, add/fix links Signed-off-by: Matthias Hanel --- developing-with-nats/receiving/queues.md | 38 +------------------ nats-concepts/queue.md | 2 + .../securing_nats/authorization.md | 36 +++++++++++++++++- 3 files changed, 39 insertions(+), 37 deletions(-) diff --git a/developing-with-nats/receiving/queues.md b/developing-with-nats/receiving/queues.md index 2f0aa29..774105e 100644 --- a/developing-with-nats/receiving/queues.md +++ b/developing-with-nats/receiving/queues.md @@ -1,8 +1,8 @@ # Queue Subscriptions -Subscribing to a queue group is only slightly different than subscribing to a subject alone. The application simply includes a queue name with the subscription. The effect of including the group is fairly major, since the server will now load balance messages between the members of the queue group, but the code differences are minimal. +Subscribing to a [queue group](../../nats-concepts/queue.md) is only slightly different than subscribing to a subject alone. The application simply includes a queue name with the subscription. The server will load balance between all members of the queue group. In a cluster setup, every member has the same chance of receiving a particular message. -Keep in mind that the queue groups in NATS are dynamic and do not require any server configuration. You can almost think of a regular subscription as a queue group of 1, but it is probably not worth thinking too much about that. +Keep in mind that queue groups in NATS are dynamic and do not require any server configuration. ![](../../.gitbook/assets/queues.svg) @@ -122,37 +122,3 @@ await nc.subscribe('updates', (err, msg) => { {% endtabs %} If you run this example with the publish examples that send to `updates`, you will see that one of the instances gets a message while the others you run won't. But the instance that receives the message will change. - -## Queue Permissions - -Added in NATS Server v2.1.2, Queue Permissions allow you to express authorization for queue groups. As queue groups are integral to implementing horizontally scalable microservices, control of who is allowed to join a specific queue group is important to the overall security model. - -A Queue Permission can be defined with the syntax ` `, where the name of the queue can also use wildcards, for example the following would allow clients to join queue groups v1 and v2.\*, but won't allow plain subscriptions: - -```text -allow = ["foo v1", "foo v2.*"] -``` - -The full wildcard can also be used, for example the following would prevent plain subscriptions on `bar` but allow the client to join any queue: - -```text -allow = ["bar >"] -``` - -Permissions for Queue Subscriptions can be combined with plain subscriptions as well though, for example you could allow plain subscriptions on `foo` but constrain the queues to which a client can join, as well as preventing any service from using a queue subscription with the name `*.prod`: - -```text -users = [ - { - user: "foo", permissions: { - sub: { - # Allow plain subscription foo, but only v1 groups or *.dev queue groups - allow: ["foo", "foo v1", "foo v1.>", "foo *.dev"] - - # Prevent queue subscriptions on prod groups - deny: ["> *.prod"] - } - } -] -``` - diff --git a/nats-concepts/queue.md b/nats-concepts/queue.md index d08a2c7..6f1222f 100644 --- a/nats-concepts/queue.md +++ b/nats-concepts/queue.md @@ -4,6 +4,8 @@ NATS provides a built-in load balancing feature called distributed queues. Using To create a queue subscription, subscribers register a queue name. All subscribers with the same queue name form the queue group. This requires no configuration. As messages on the registered subject are published, one member of the group is chosen randomly to receive the message. Although queue groups have multiple subscribers, each message is consumed by only one. +Queue group names follow the same naming rules as [subjects](subjects.md). Foremost, they are case sensitive and cannot contain whitespace. Consider structuring queue groups hierarchically using `.`. Some server functionalities can use [wildcard matching](subjects.md#wildcards) on them. + One of the great features of NATS is that queue groups are defined by the application and their queue subscribers, not on the server configuration. Queue subscribers are ideal for scaling services. Scale up is as simple as running another application, scale down is terminating the application with a signal that drains the in flight requests. This flexibility and lack of any configuration changes makes NATS an excellent service communication technology that can work with all platform technologies. diff --git a/nats-server/configuration/securing_nats/authorization.md b/nats-server/configuration/securing_nats/authorization.md index a946bb9..e79f756 100644 --- a/nats-server/configuration/securing_nats/authorization.md +++ b/nats-server/configuration/securing_nats/authorization.md @@ -2,7 +2,7 @@ The NATS server supports authorization using subject-level permissions on a per-user basis. Permission-based authorization is available with multi-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 configuration, you can specify a `permission` object which explicitly allows or denies subjects. The specified subjects can specify wildcards. Permissions can make use of [variables](../#variables). +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 configuration, you can specify a `permission` object which explicitly allows or denies subjects. The specified subjects can specify wildcards. Permissions can make use of [variables](../README.md#variables). You configure authorization by creating a `permissions` entry in the `authorization` object. @@ -95,3 +95,37 @@ authorization: { } ``` +## Queue Permissions + +Added in NATS Server v2.1.2, Queue Permissions allow you to express authorization for queue groups. As queue groups are integral to implementing horizontally scalable microservices, control of who is allowed to join a specific queue group is important to the overall security model. + +A Queue Permission can be defined with the syntax ` `, where the name of the queue can also use wildcards, for example the following would allow clients to join queue groups v1 and v2.\*, but won't allow plain subscriptions: + +```text +allow = ["foo v1", "foo v2.*"] +``` + +The full wildcard can also be used, for example the following would prevent plain subscriptions on `bar` but allow the client to join any queue: + +```text +allow = ["bar >"] +``` + +Permissions for Queue Subscriptions can be combined with plain subscriptions as well though, for example you could allow plain subscriptions on `foo` but constrain the queues to which a client can join, as well as preventing any service from using a queue subscription with the name `*.prod`: + +```text +users = [ + { + user: "foo", permissions: { + sub: { + # Allow plain subscription foo, but only v1 groups or *.dev queue groups + allow: ["foo", "foo v1", "foo v1.>", "foo *.dev"] + + # Prevent queue subscriptions on prod groups + deny: ["> *.prod"] + } + } +] +``` + +