diff --git a/content/vault/global/partials/important-changes/breaking-changes/allowed-parameters-list.mdx b/content/vault/global/partials/important-changes/breaking-changes/allowed-parameters-list.mdx new file mode 100644 index 0000000000..00f55b7d02 --- /dev/null +++ b/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. diff --git a/content/vault/global/partials/important-changes/summary-tables/1_21.mdx b/content/vault/global/partials/important-changes/summary-tables/1_21.mdx index e0579747dc..47df058d04 100644 --- a/content/vault/global/partials/important-changes/summary-tables/1_21.mdx +++ b/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 diff --git a/content/vault/global/partials/policies/allowed_parameters_warning.mdx b/content/vault/global/partials/policies/allowed_parameters_warning.mdx new file mode 100644 index 0000000000..8d9d3a0044 --- /dev/null +++ b/content/vault/global/partials/policies/allowed_parameters_warning.mdx @@ -0,0 +1,9 @@ + + +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. + + diff --git a/content/vault/global/partials/policies/list-allowed-parameters.mdx b/content/vault/global/partials/policies/list-allowed-parameters.mdx new file mode 100644 index 0000000000..3abf79ddff --- /dev/null +++ b/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"` + + + +Vault addressed the unexpected behavior of +`allowed_parameters` and `denied_parameters` in 1.21.x with +more intuitive list processing. + + diff --git a/content/vault/v1.16.x/content/docs/concepts/policies.mdx b/content/vault/v1.16.x/content/docs/concepts/policies.mdx index 1162e2447d..bf5fe2c42b 100644 --- a/content/vault/v1.16.x/content/docs/concepts/policies.mdx +++ b/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 diff --git a/content/vault/v1.17.x/content/docs/concepts/policies.mdx b/content/vault/v1.17.x/content/docs/concepts/policies.mdx index 4226fa9160..4bc39149ab 100644 --- a/content/vault/v1.17.x/content/docs/concepts/policies.mdx +++ b/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 diff --git a/content/vault/v1.18.x/content/docs/concepts/policies.mdx b/content/vault/v1.18.x/content/docs/concepts/policies.mdx index 4226fa9160..4bc39149ab 100644 --- a/content/vault/v1.18.x/content/docs/concepts/policies.mdx +++ b/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 diff --git a/content/vault/v1.19.x/content/docs/concepts/policies.mdx b/content/vault/v1.19.x/content/docs/concepts/policies.mdx index 4226fa9160..4bc39149ab 100644 --- a/content/vault/v1.19.x/content/docs/concepts/policies.mdx +++ b/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 diff --git a/content/vault/v1.20.x/content/docs/concepts/policies.mdx b/content/vault/v1.20.x/content/docs/concepts/policies.mdx index a3772b4569..79aac1e1db 100644 --- a/content/vault/v1.20.x/content/docs/concepts/policies.mdx +++ b/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 diff --git a/content/vault/v1.21.x (rc)/content/docs/concepts/policies.mdx b/content/vault/v1.21.x (rc)/content/docs/concepts/policies.mdx index a3772b4569..16dda12c0d 100644 --- a/content/vault/v1.21.x (rc)/content/docs/concepts/policies.mdx +++ b/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 diff --git a/content/vault/v1.21.x (rc)/content/docs/updates/deprecation.mdx b/content/vault/v1.21.x (rc)/content/docs/updates/deprecation.mdx index 78be0771d9..09ceebd8ad 100644 --- a/content/vault/v1.21.x (rc)/content/docs/updates/deprecation.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/updates/deprecation.mdx @@ -49,6 +49,8 @@ or raise a ticket with your support team. @include 'deprecation/duplicate-hcl-attributes.mdx' +@include 'deprecation/list-allowed-parameters.mdx' + diff --git a/content/vault/v1.21.x (rc)/content/docs/updates/important-changes.mdx b/content/vault/v1.21.x (rc)/content/docs/updates/important-changes.mdx index 39df6a8dcd..6a4446c403 100644 --- a/content/vault/v1.21.x (rc)/content/docs/updates/important-changes.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/updates/important-changes.mdx @@ -49,6 +49,7 @@ vault write auth/kubernetes/role/demo \ Refer to the [Kubernetes authentication docs](/vault/docs/auth/kubernetes) for more information. +@include '../../../global/partials/important-changes/breaking-changes/allowed-parameters-list.mdx' ## New behavior @@ -81,4 +82,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. \ No newline at end of file +1. Only subscribe to events on the active node of the cluster. diff --git a/content/vault/v1.21.x (rc)/content/partials/deprecation/list-allowed-parameters.mdx b/content/vault/v1.21.x (rc)/content/partials/deprecation/list-allowed-parameters.mdx new file mode 100644 index 0000000000..32a51fb1f7 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/partials/deprecation/list-allowed-parameters.mdx @@ -0,0 +1,13 @@ +## Exact-match list comparison on allowed_parameters and denied_parameters ((#list-allowed-parameters-deprecation)) + +| Announced | Expected end of support | Expected removal | +| :-------: | :---------------------: | :--------------: | +| OCT 2025 | OCT 2025 | APR 2026 | + +The behavior of `allowed_parameters` and `denied_parameters` policy rules when +evaluating list-type request parameters is changing in Vault v1.21.0. During the +deprecation period the environment variable `VAULT_LEGACY_EXACT_MATCHING_ON_LIST` +can be set to revert to the legacy behavior. + +Refer to [list parameter evaluation](/vault/docs/concepts/policies#list-parameter-evaluation) +for more information on the behavior change.