From 5d18b8adfa7103cf1074dfd712897894218a9cf7 Mon Sep 17 00:00:00 2001 From: aricart Date: Thu, 30 Jan 2020 16:54:40 -0400 Subject: [PATCH 1/4] Document `allow-responses`. --- .../securing_nats/authorization.md | 33 +++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/nats-server/configuration/securing_nats/authorization.md b/nats-server/configuration/securing_nats/authorization.md index a946bb9..ac21c65 100644 --- a/nats-server/configuration/securing_nats/authorization.md +++ b/nats-server/configuration/securing_nats/authorization.md @@ -14,6 +14,8 @@ The `permissions` map specify subjects that can be subscribed to or published by | :--- | :--- | | `publish` | subject, list of subjects, or permission map the client can publish | | `subscribe` | subject, list of subjects, or permission map the client can subscribe | +| `allow_responses` | boolean or object | + ## Permission Map @@ -26,6 +28,22 @@ The `permission` map provides additional properties for configuring a `permissio **Important Note** NATS Authorizations can be _allow lists_, _deny lists_, or both. It is important to not break request/reply patterns. In some cases \(as shown below\) 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 _allow listed_, the action fails and is logged at the server, and an error message is returned to the client. +## Allow Responses Map + +The `allow_responses` option dynamically allows publishing to reply subjects, this works well for service responders. +When set to `true`, excepting any `publish` permissions, implicitly all publish permissions are denied unless it is the reply subject in a request received by the client. + +The `allow_responses` map also allow you to configure a maximum number of responses and how long to allow the dynamic permission after a message is received. + +| Property | Description | +| :--- | :--- | +| `max` | The maximum number of response messages that can be returned to a request. | +| `expires` | The duration of time to allow a response. Values such as `1s`, `1m`, `1h` (1 second, minute, hour) etc can be specified. | + +If `allow_responses` set to `true` rather than a specific configuration, it defaults to the equivalent of `{ max: 1 }`. + +**Important Note** When using `nsc` to configure your users, you can specify the `--allow-pub-response` and `--response-ttl` to control these settings. + ## Example Here is an example authorization configuration that uses _variables_ which defines four users, three of whom are assigned explicit permissions. @@ -95,3 +113,18 @@ authorization: { } ``` +Here's an example with `allow_responses`: + +```text +authorization: { + users: [ + { user: a, password: a }, + { user: b, password: b, permissions: {subscribe: "q", allow_responses: true } }, + { user: c, password: c, permissions: {subscribe: "q", allow_responses: { max: 5, expires: "1m" } } } + ] +} +``` + +User `a` has no restrictions. User `b` can listen on `q` for requests. If the received request has a reply subject it can reply at most one message. User `c` can also listen on `q` for requests, but is able to return at most 5 reply messages. The reply subject can be publish to for at most `1` minute. + + From 401aa911fbb037ef807a19469e1a193ecf307660 Mon Sep 17 00:00:00 2001 From: Ginger Collison Date: Thu, 30 Jan 2020 16:21:13 -0600 Subject: [PATCH 2/4] Update authorization.md --- nats-server/configuration/securing_nats/authorization.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/nats-server/configuration/securing_nats/authorization.md b/nats-server/configuration/securing_nats/authorization.md index ac21c65..4f620b1 100644 --- a/nats-server/configuration/securing_nats/authorization.md +++ b/nats-server/configuration/securing_nats/authorization.md @@ -30,17 +30,17 @@ The `permission` map provides additional properties for configuring a `permissio ## Allow Responses Map -The `allow_responses` option dynamically allows publishing to reply subjects, this works well for service responders. +The `allow_responses` option dynamically allows publishing to reply subjects and works well for service responders. When set to `true`, excepting any `publish` permissions, implicitly all publish permissions are denied unless it is the reply subject in a request received by the client. -The `allow_responses` map also allow you to configure a maximum number of responses and how long to allow the dynamic permission after a message is received. +The `allow_responses` map also allows you to configure a maximum number of responses and how long to allow the dynamic permission after a message is received. | Property | Description | | :--- | :--- | | `max` | The maximum number of response messages that can be returned to a request. | | `expires` | The duration of time to allow a response. Values such as `1s`, `1m`, `1h` (1 second, minute, hour) etc can be specified. | -If `allow_responses` set to `true` rather than a specific configuration, it defaults to the equivalent of `{ max: 1 }`. +If `allow_responses` is set to `true` rather than a specific configuration, it defaults to the equivalent of `{ max: 1 }`. **Important Note** When using `nsc` to configure your users, you can specify the `--allow-pub-response` and `--response-ttl` to control these settings. @@ -125,6 +125,6 @@ authorization: { } ``` -User `a` has no restrictions. User `b` can listen on `q` for requests. If the received request has a reply subject it can reply at most one message. User `c` can also listen on `q` for requests, but is able to return at most 5 reply messages. The reply subject can be publish to for at most `1` minute. +User `a` has no restrictions. User `b` can listen on `q` for requests. If the received request has a reply subject it can reply at most with one message. User `c` can also listen on `q` for requests, but is able to return at most 5 reply messages, and the reply subject can be published at most for `1` minute. From f7790d0fd2ff153affef22d92c2c5eca608eff3a Mon Sep 17 00:00:00 2001 From: aricart Date: Wed, 5 Feb 2020 08:46:46 -0400 Subject: [PATCH 3/4] review comments. --- nats-server/configuration/securing_nats/authorization.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/nats-server/configuration/securing_nats/authorization.md b/nats-server/configuration/securing_nats/authorization.md index 4f620b1..f02276e 100644 --- a/nats-server/configuration/securing_nats/authorization.md +++ b/nats-server/configuration/securing_nats/authorization.md @@ -31,14 +31,14 @@ The `permission` map provides additional properties for configuring a `permissio ## Allow Responses Map The `allow_responses` option dynamically allows publishing to reply subjects and works well for service responders. -When set to `true`, excepting any `publish` permissions, implicitly all publish permissions are denied unless it is the reply subject in a request received by the client. +When set to `true`, excepting any explicit `allow publish` permissions, implicitly all publish permissions are denied unless it is the reply subject in a request received by the client. The `allow_responses` map also allows you to configure a maximum number of responses and how long to allow the dynamic permission after a message is received. | Property | Description | | :--- | :--- | | `max` | The maximum number of response messages that can be returned to a request. | -| `expires` | The duration of time to allow a response. Values such as `1s`, `1m`, `1h` (1 second, minute, hour) etc can be specified. | +| `expires` | The amount of time the permission is valid. Values such as `1s`, `1m`, `1h` (1 second, minute, hour) etc can be specified. Default doesn't have a time limit. | If `allow_responses` is set to `true` rather than a specific configuration, it defaults to the equivalent of `{ max: 1 }`. From f238360ae2e0d18ce7c908572eaab7be6a5057fb Mon Sep 17 00:00:00 2001 From: aricart Date: Wed, 5 Feb 2020 08:59:17 -0400 Subject: [PATCH 4/4] review changes --- .../configuration/securing_nats/authorization.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/nats-server/configuration/securing_nats/authorization.md b/nats-server/configuration/securing_nats/authorization.md index f02276e..ea5a5e7 100644 --- a/nats-server/configuration/securing_nats/authorization.md +++ b/nats-server/configuration/securing_nats/authorization.md @@ -31,16 +31,14 @@ The `permission` map provides additional properties for configuring a `permissio ## Allow Responses Map The `allow_responses` option dynamically allows publishing to reply subjects and works well for service responders. -When set to `true`, excepting any explicit `allow publish` permissions, implicitly all publish permissions are denied unless it is the reply subject in a request received by the client. - -The `allow_responses` map also allows you to configure a maximum number of responses and how long to allow the dynamic permission after a message is received. +When set to `true`, only one response is allowed, meaning the permission to publish to the reply subject defaults to only once. The `allow_responses` map allows you to configure a maximum number of responses and how long the permission is valid. | Property | Description | | :--- | :--- | -| `max` | The maximum number of response messages that can be returned to a request. | +| `max` | The maximum number of response messages that can be published. | | `expires` | The amount of time the permission is valid. Values such as `1s`, `1m`, `1h` (1 second, minute, hour) etc can be specified. Default doesn't have a time limit. | -If `allow_responses` is set to `true` rather than a specific configuration, it defaults to the equivalent of `{ max: 1 }`. +When `allow_responses` is set to `true`, it defaults to the equivalent of `{ max: 1 }` and no time limit. **Important Note** When using `nsc` to configure your users, you can specify the `--allow-pub-response` and `--response-ttl` to control these settings. @@ -125,6 +123,6 @@ authorization: { } ``` -User `a` has no restrictions. User `b` can listen on `q` for requests. If the received request has a reply subject it can reply at most with one message. User `c` can also listen on `q` for requests, but is able to return at most 5 reply messages, and the reply subject can be published at most for `1` minute. +User `a` has no restrictions. User `b` can listen on `q` for requests and can only publish once to reply subjects. All other subjects will be denied. User `c` can also listen on `q` for requests, but is able to return at most 5 reply messages, and the reply subject can be published at most for `1` minute.