VAULT-39667 Add docs for breaking changes to allowed_ and denied_parameters (#1120)

This PR adds documentation about Vault's breaking change to the
`allowed_parameters` and `denied_parameters` behavior when comparing
list parameters.

Jira: [VAULT-39667](https://hashicorp.atlassian.net/browse/VAULT-39667)
Internal draft: [Documentation for denied_parameters breaking
change](https://docs.google.com/document/d/1FJldPo9Nc2wNjk3j5Zp-sTIJu1yxMCX1ergHrijLd70/edit?tab=t.0)

[VAULT-39667]:
https://hashicorp.atlassian.net/browse/VAULT-39667?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

Author: bosouza

content/vault/global/partials/important-changes/breaking-changes/allowed-parameters-list.mdx

@@ -0,0 +1,34 @@
+### Item-by-item list comparison for allowed_parameters and denied_parameters ((#allowed-parameters-list))
+
+| Change       | Affected version | Vault edition
+| ------------ | ---------------- | -------------
+| Breaking     | 1.21.0+          | All
+
+Previous versions of Vault only matched list parameters when the associated
+policy defined the list as a whole. As a result, Vault allowed lists containing
+denied values as long as the policy did not deny that exact list and denied
+lists containing allowed values because the policy did not allow the exact list.
+
+Vault now checks each value in a list parameter against allowed/denied values
+in the applicable Vault policy and allows or denies requests if the policy
+defines the list as a whole or every/any individual element of the list. For
+example, if the request includes a list like `['a', 'b', 'c']`, it still matches
+to a policy that includes `['a', 'b', 'c']` but also matches to an approve
+policy that includes all the individual values `a`, `b`, and `c` or a deny
+policy that includes any of the individual values.
+
+#### Recommendation
+
+Workflows that previously succeeded may now fail due to permission checks
+involving `denied_parameters` because the new matching behavior correctly
+identifies the fact that the list contains individually denied values even when
+the exact list does not appear in the policy.
+
+To address the broken workflow:
+- Check whether or not your policies are overly restrictive.
+- Update your workflows to avoid including explicitly denied values in lists.
+
+Refer to [list parameter evaluation](/vault/docs/concepts/policies#list-parameter-evaluation) for more information.
+
+You can temporarily revert to the deprecated matching behavior by setting the
+`VAULT_LEGACY_EXACT_MATCHING_ON_LIST` environment variable on your Vault server.

content/vault/global/partials/important-changes/summary-tables/1_21.mdx

@@ -3,6 +3,7 @@
 Introduced | Recommendations | Edition    | Change
 ---------- | --------------- | ---------- | ------
 1.21.0     | **Yes**         | All        | [Audiences required for Kubernetes authentication roles](/vault/docs/v1.21.x/updates/important-changes#k8-audience-required)
+1.21.0     | **Yes**         | All        | [Item-by-item list comparison for allowed_parameters and denied_parameters](/vault/docs/v1.21.x/updates/important-changes#allowed-parameters-list)
 
 
 ### New behavior

content/vault/global/partials/policies/allowed_parameters_warning.mdx

@@ -0,0 +1,9 @@
+<Warning title="Parameter list behavior">
+
+Vault evaluates list parameters matching `allowed_parameters` and `denied_parameters` by
+ looking for the whole list instead of each element in the list.
+
+When restricting list parameters we strongly recommend using allow rules instead of deny
+rules. Refer to [list parameter evaluation](#list-parameter-evaluation) for more details.
+
+</Warning>

content/vault/global/partials/policies/list-allowed-parameters.mdx

@@ -0,0 +1,39 @@
+#### List parameter evaluation
+
+When a request parameter carrying a list value matches an
+`allowed_parameters` or `denied_parameters` policy rule, Vault checks for
+an exact match between each allowed or denied value in the policy and
+the **entire** list value in the request parameter. The fact that Vault
+looks for matches to the entire list can produce unexpected results.
+
+For example, if you set `allowed_parameters` to `"X": ["A", "B"]`:
+
+- Vault only allows requests with parameter `"X": "A"` or `"X": "B"`.
+- Vault denies all other requests. . For example, Vault denies
+   requests with parameter `"X": ["A", "B"]`, `"X": ["B", "A"]` or
+   even `"X": ["A"]`, because the parameter value does not
+   **exactly** match one of the allowed values ("A" or "B").
+
+The same logic applies to `denied_parameters`. If you create a policy with
+`denied_parameters` set to `"Y": ["C", "D"]`:
+
+- Vault only denies requests with parameter `"X": "C"` or `"X": "D"`.
+- Vault allows all other requests. For example, Vault allows requests with
+   parameter `"Y": ["C", "D"]`, which can lead to unauthorized access if you
+   intended to deny any request that included "C", "D", or both.
+
+As a result, we **strongly recommend** using `allowed_parameters`
+instead of `denied_parameters` for list parameters.
+
+Additionally, Vault does not treat comma-separated strings in request
+parameters as lists when evaluating `allowed_parameters` and `denied_parameters`.
+For instance, configuring `denied_parameters` as `"Z": ["C", "D", ["C"], ["D"], ["C", "D"], ["D", "C"]]`
+does not block requests that set `"Z": "C,D"` or `"Z": "D,C"`
+
+<Tip title="Consider upgrading to 1.21.x or later">
+
+Vault addressed the unexpected behavior of
+`allowed_parameters` and `denied_parameters` in 1.21.x with
+more intuitive list processing.
+
+</Tip>

content/vault/v1.16.x/content/docs/concepts/policies.mdx

@@ -347,6 +347,8 @@ path take precedence over permissions on parameters.
 
 ~> **Note:** The `allowed_parameters`, `denied_parameters`, and `required_parameters` fields are not supported for policies used with the [version 2 kv secrets engine](/vault/docs/secrets/kv/kv-v2).
 
+@include '../../../global/partials/policies/allowed_parameters_warning.mdx'
+
 See the [API Specification](/vault/api-docs/secret/kv/kv-v2) for more information.
 
 Policies can take into account HTTP request parameters to further
@@ -571,6 +573,8 @@ path "secret/foo" {
 }
 ```
 
+@include '../../../global/partials/policies/list-allowed-parameters.mdx'
+
 ### Required response wrapping TTLs
 
 These parameters can be used to set minimums/maximums on TTLs set by clients

content/vault/v1.17.x/content/docs/concepts/policies.mdx

@@ -354,6 +354,8 @@ path take precedence over permissions on parameters.
 
 ~> **Note:** The `allowed_parameters`, `denied_parameters`, and `required_parameters` fields are not supported for policies used with the [version 2 kv secrets engine](/vault/docs/secrets/kv/kv-v2).
 
+@include '../../../global/partials/policies/allowed_parameters_warning.mdx'
+
 See the [API Specification](/vault/api-docs/secret/kv/kv-v2) for more information.
 
 Policies can take into account HTTP request parameters to further
@@ -578,6 +580,8 @@ path "secret/foo" {
 }
 ```
 
+@include '../../../global/partials/policies/list-allowed-parameters.mdx'
+
 ### Required response wrapping TTLs
 
 These parameters can be used to set minimums/maximums on TTLs set by clients

content/vault/v1.18.x/content/docs/concepts/policies.mdx

@@ -354,6 +354,8 @@ path take precedence over permissions on parameters.
 
 ~> **Note:** The `allowed_parameters`, `denied_parameters`, and `required_parameters` fields are not supported for policies used with the [version 2 kv secrets engine](/vault/docs/secrets/kv/kv-v2).
 
+@include '../../../global/partials/policies/allowed_parameters_warning.mdx'
+
 See the [API Specification](/vault/api-docs/secret/kv/kv-v2) for more information.
 
 Policies can take into account HTTP request parameters to further
@@ -578,6 +580,8 @@ path "secret/foo" {
 }
 ```
 
+@include '../../../global/partials/policies/list-allowed-parameters.mdx'
+
 ### Required response wrapping TTLs
 
 These parameters can be used to set minimums/maximums on TTLs set by clients

content/vault/v1.19.x/content/docs/concepts/policies.mdx

@@ -354,6 +354,8 @@ path take precedence over permissions on parameters.
 
 ~> **Note:** The `allowed_parameters`, `denied_parameters`, and `required_parameters` fields are not supported for policies used with the [version 2 kv secrets engine](/vault/docs/secrets/kv/kv-v2).
 
+@include '../../../global/partials/policies/allowed_parameters_warning.mdx'
+
 See the [API Specification](/vault/api-docs/secret/kv/kv-v2) for more information.
 
 Policies can take into account HTTP request parameters to further
@@ -578,6 +580,8 @@ path "secret/foo" {
 }
 ```
 
+@include '../../../global/partials/policies/list-allowed-parameters.mdx'
+
 ### Required response wrapping TTLs
 
 These parameters can be used to set minimums/maximums on TTLs set by clients

content/vault/v1.20.x/content/docs/concepts/policies.mdx

@@ -356,6 +356,8 @@ path take precedence over permissions on parameters.
 
 ~> **Note:** The `allowed_parameters`, `denied_parameters`, and `required_parameters` fields are not supported for policies used with the [version 2 kv secrets engine](/vault/docs/secrets/kv/kv-v2).
 
+@include '../../../global/partials/policies/allowed_parameters_warning.mdx'
+
 See the [API Specification](/vault/api-docs/secret/kv/kv-v2) for more information.
 
 Policies can take into account HTTP request parameters to further
@@ -580,6 +582,8 @@ path "secret/foo" {
 }
 ```
 
+@include '../../../global/partials/policies/list-allowed-parameters.mdx'
+
 ### Required response wrapping TTLs
 
 These parameters can be used to set minimums/maximums on TTLs set by clients

content/vault/v1.21.x (rc)/content/docs/concepts/policies.mdx

@@ -433,6 +433,13 @@ constrain requests, using the following options:
     }
     ```
 
+  - When a request includes a parameter that contains a list value, Vault allows the request
+  if `allowed_parameters` contains all values in the list or the list as a whole. Previously, Vault
+  only allowed the request when the entire list matched an allowed value. During the
+  deprecation period, you can restore the old behavior by setting the
+  `VAULT_LEGACY_EXACT_MATCHING_ON_LIST` environment variable on the server.
+
+
 - `denied_parameters` - A list of keys and values that are not permitted on the given
   path. Any values specified here take precedence over `allowed_parameters`.
 
@@ -485,6 +492,12 @@ constrain requests, using the following options:
   - If any parameters are specified, all non-specified parameters are allowed,
     unless `allowed_parameters` is also set, in which case normal rules apply.
 
+  - When a request includes a parameter that contains a list value, Vault denies the request
+  if `denied_parameters` contains any value in the list or the list as a whole. Previously, Vault
+  only denied the request when the entire list matched a denied value. During the
+  deprecation period, you can restore the old behavior by setting the
+  `VAULT_LEGACY_EXACT_MATCHING_ON_LIST` environment variable on the server.
+
 Parameter values also support prefix/suffix globbing. Globbing is enabled by
 prepending or appending or prepending a splat (`*`) to the value:
 
@@ -580,6 +593,22 @@ path "secret/foo" {
 }
 ```
 
+#### List parameter evaluation
+
+In Vault v1.21.0 and later, when a request parameter carrying a list value matches
+an `allowed_parameters` or `denied_parameters` policy rule, Vault checks each
+element in the list against the list of allowed or denied values in the policy,
+as well as the list as a whole. This means that if `allowed_parameters` is set to
+`"X": ["A", "B"]`, Vault would allow all of the following values for "X": `"A"`, 
+`"B"`, `["A", "B"]`, `["B", "A"]`, `["A"]`, `["B"]`, `"A,B"`, and `"B,A"`.
+
+Previous versions of Vault did not treat list values in this way, which led to
+unexpected behavior. For more information refer to this same section in the
+documentation for Vault v1.20.x and earlier. During the deprecation period, you
+can restore the old behavior by setting the `VAULT_LEGACY_EXACT_MATCHING_ON_LIST`
+environment variable on the Vault server.
+
+
 ### Required response wrapping TTLs
 
 These parameters can be used to set minimums/maximums on TTLs set by clients