VAULT-39667 Add docs for breaking changes to allowed_ and denied_parameters

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

@@ -0,0 +1,4 @@
+!> **Warning:** In Vault versions 1.20 and earlier, attributes of type list had a different behavior
+with `allowed_parameters` and `denied_parameters`. In order for the list to be considered
+allowed, it didn't matter that all values in the list were individually allowed, as the
+whole list had to be defined as a single allowed value. This has been changed in Vault 1.21.

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

@@ -0,0 +1,5 @@
+!> **Warning:** In Vault versions 1.20 and earlier, attributes of type list had a different behavior
+with `allowed_parameters` and `denied_parameters`. In order for the list to be considered
+denied, it didn't matter that some or all values in the list appeared under
+`denied_parameters`, only that the list as a whole was defined as a single denied value.
+This has been changed in Vault 1.21.

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

@@ -424,6 +424,8 @@ constrain requests, using the following options:
     }
     ```
 
+  @include '../../../global/partials/policies/allowed_parameters_warning.mdx'
+
 - `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`.
 
@@ -476,6 +478,8 @@ 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.
 
+  @include '../../../global/partials/policies/denied_parameters_warning.mdx'
+
 Parameter values also support prefix/suffix globbing. Globbing is enabled by
 prepending or appending or prepending a splat (`*`) to the value:
 

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

@@ -431,6 +431,8 @@ constrain requests, using the following options:
     }
     ```
 
+  @include '../../../global/partials/policies/allowed_parameters_warning.mdx'
+
 - `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`.
 
@@ -483,6 +485,8 @@ 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.
 
+  @include '../../../global/partials/policies/denied_parameters_warning.mdx'
+
 Parameter values also support prefix/suffix globbing. Globbing is enabled by
 prepending or appending or prepending a splat (`*`) to the value:
 

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

@@ -431,6 +431,8 @@ constrain requests, using the following options:
     }
     ```
 
+  @include '../../../global/partials/policies/allowed_parameters_warning.mdx'
+
 - `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`.
 
@@ -483,6 +485,8 @@ 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.
 
+  @include '../../../global/partials/policies/denied_parameters_warning.mdx'
+
 Parameter values also support prefix/suffix globbing. Globbing is enabled by
 prepending or appending or prepending a splat (`*`) to the value:
 

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

@@ -431,6 +431,8 @@ constrain requests, using the following options:
     }
     ```
 
+  @include '../../../global/partials/policies/allowed_parameters_warning.mdx'
+
 - `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`.
 
@@ -483,6 +485,8 @@ 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.
 
+  @include '../../../global/partials/policies/denied_parameters_warning.mdx'
+
 Parameter values also support prefix/suffix globbing. Globbing is enabled by
 prepending or appending or prepending a splat (`*`) to the value:
 

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

@@ -433,6 +433,8 @@ constrain requests, using the following options:
     }
     ```
 
+  @include '../../../global/partials/policies/allowed_parameters_warning.mdx'
+
 - `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 +487,8 @@ 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.
 
+  @include '../../../global/partials/policies/denied_parameters_warning.mdx'
+
 Parameter values also support prefix/suffix globbing. Globbing is enabled by
 prepending or appending or prepending a splat (`*`) to the value:
 

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

@@ -432,6 +432,13 @@ constrain requests, using the following options:
       }
     }
     ```
+
+  - Request parameters that are defined in `allowed_parameters` and set to a list 
+  will be allowed if all the values in the list are allowed, or if the list as a
+  whole is allowed. On Vault 1.20 and below only the latter is true, and during
+  the deprecation process Vault can be configured to use the old behavior by setting
+  the environment flag `VAULT_LEGACY_EXACT_MATCHING_ON_LIST` 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.
 
+  - Request parameters that are defined in `denied_parameters` and set to a list
+  will be denied if any values in the list are denied, or if the list as a whole
+  is denied. On Vault 1.20 and below only the latter is true, and during the
+  deprecation process Vault can be configured to use the old behavior by setting
+  the environment flag `VAULT_LEGACY_EXACT_MATCHING_ON_LIST` on the server.
+
 Parameter values also support prefix/suffix globbing. Globbing is enabled by
 prepending or appending or prepending a splat (`*`) to the value:
 

content/vault/v1.21.x (rc)/content/docs/updates/important-changes.mdx

@@ -49,6 +49,38 @@ vault write auth/kubernetes/role/demo \
 Refer to the [Kubernetes authentication docs](/vault/docs/auth/kubernetes) for
 more information.
 
+### Item-by-item list comparison for allowed_parameters and denied_parameters ((#allowed-parameters-list))
+
+| Change       | Affected version | Vault edition
+| ------------ | ---------------- | -------------
+| Breaking     | 1.21.0           | All
+
+Prior to Vault 1.21, when a parameter in a request was subject to
+`allowed_parameters` or `denied_parameters` checks and the parameter's value was
+a list, Vault evaluated the **entire list** as a single value.
+This meant Vault would only find a match if the **whole list** exactly matched
+an entry in `allowed_parameters` or `denied_parameters`, which was often
+unintuitive.
+
+Starting with Vault 1.21, this behavior has changed.
+When a parameter's value is a list, **each element** in that list is now checked
+individually against the allowed or denied values.
+
+#### Recommendation
+
+If you start seeing workflows fail due to permission checks involving
+`denied_parameters`, it likely means that the workflow was previously relying on
+the old matching behavior, where a list containing a denied value would still
+pass validation as long as the entire list didn't exactly match a denied entry.
+
+In that case, review your policy and workflow:
+* **Check your policies** to ensure they aren’t overly restrictive.
+* **Update workflows** to avoid including explicitly denied values in lists.
+
+If necessary, Vault 1.21 can temporarily revert to the legacy (1.20) behavior by
+setting the `VAULT_LEGACY_EXACT_MATCHING_ON_LIST` environment variable.
+However, note that this option is **deprecated** and will be removed in a future
+release.
 
 ## New behavior
 
@@ -74,4 +106,4 @@ If you have multiple event subscribers with the same namespace and event type
 filters you have two options:
 
 1. Spread them out among the nodes of the Vault cluster.
-1. Only subscribe to events on the active node of the cluster.
+1. Only subscribe to events on the active node of the cluster.