From 38fd8efcb5442f0e830b60bc8d236598af6b008f Mon Sep 17 00:00:00 2001 From: Yoko Hyakuna Date: Thu, 14 Jul 2022 08:01:22 -0700 Subject: [PATCH] Update the policy examples (#16297) * Update the policy examples * Adjusted the examples --- website/content/docs/concepts/policies.mdx | 86 +++++++++++++--------- 1 file changed, 50 insertions(+), 36 deletions(-) diff --git a/website/content/docs/concepts/policies.mdx b/website/content/docs/concepts/policies.mdx index ce7fe1a569..fa983206d5 100644 --- a/website/content/docs/concepts/policies.mdx +++ b/website/content/docs/concepts/policies.mdx @@ -341,7 +341,7 @@ path take precedence over permissions on parameters. ### Parameter Constraints -~> **Note:**: The `allowed_parameters`, `denied_parameters`, and `required_parameters` fields are not supported for policies used with the version 2 kv store. +~> **Note:** The `allowed_parameters`, `denied_parameters`, and `required_parameters` fields are not supported for policies used with the [version 2 kv secrets engine](/docs/secrets/kv/kv-v2). See the [API Specification](/api-docs/secret/kv/kv-v2) for more information. @@ -351,14 +351,14 @@ constrain requests, using the following options: - `required_parameters` - A list of parameters that must be specified. ```ruby - # This requires the user to create "secret/foo" with a parameter named - # "bar" and "baz". - path "secret/foo" { + # This requires the user to create "secret/profile" with a parameter/key named + # "name" and "id" where kv v1 is enabled at "secret/". + path "secret/profile" { capabilities = ["create"] - required_parameters = ["bar", "baz"] + required_parameters = ["name", "id"] } ``` - + - `allowed_parameters` - A list of keys and values that are permitted on the given path. @@ -366,28 +366,37 @@ constrain requests, using the following options: contain any value. ```ruby - # This allows the user to create "secret/foo" with a parameter named - # "bar". It cannot contain any other parameters, but "bar" can contain - # any value. - path "secret/foo" { - capabilities = ["create"] + # This allows the user to update the password parameter value set on any + # users configured for userpass auth method. The password value can be + # anything. However, the user cannot update other parameter values such as + # token_ttl. + path "auth/userpass/users/*" { + capabilities = ["update"] allowed_parameters = { - "bar" = [] + "password" = [] } } ``` + -> **Usage example:** The [ACL Policy Path + Templating](https://learn.hashicorp.com/tutorials/vault/policy-templating) + tutorial demonstrates the use of `allowed_parameters` to permit a user to + update the user's password when using the [userpass auth + method](/docs/auth/userpass) to log in with Vault. + - Setting a parameter with a value of a populated list allows the parameter to contain only those values. ```ruby - # This allows the user to create "secret/foo" with a parameter named - # "bar". It cannot contain any other parameters, and "bar" can only - # contain the values "zip" or "zap". - path "secret/foo" { - capabilities = ["create"] + # This allows the user to create or update an encryption key for transit + # secrets engine enabled at "transit/". When you do, you can set the + # "auto_rotate_period" parameter value so that the key gets rotated. + # However, the rotation period must be "8h", "24h", or "5d". Any other value + # will result in an error. + path "transit/keys/*" { + capabilities = ["create", "update"] allowed_parameters = { - "bar" = ["zip", "zap"] + "auto_rotate_period" = ["8h", "24h", "5d"] } } ``` @@ -398,9 +407,10 @@ constrain requests, using the following options: will still be restricted to those values. ```ruby - # This allows the user to create "secret/foo" with a parameter named - # "bar". The parameter "bar" can only contain the values "zip" or "zap", - # but any other parameters may be created with any value. + # When kv v1 secrets engine is enabled at "secret/", this allows the user to + # create "secret/foo" with a parameter named "bar". The parameter "bar" can + # only contain the values "zip" or "zap", but any other parameters may be + # created with any value. path "secret/foo" { capabilities = ["create"] allowed_parameters = { @@ -412,6 +422,7 @@ constrain requests, using the following options: - It's important to note that the use of globbing may result in surprising or unexpected behavior. + ```ruby # This allows the user to create, update, or patch "secret/foo" with a parameter # named "bar". The values passed to parameter "bar" must start with "baz/" @@ -438,12 +449,13 @@ constrain requests, using the following options: that parameter. ```ruby - # This allows the user to create "secret/foo" with any parameters not - # named "bar". - path "secret/foo" { - capabilities = ["create"] + # This allows the user to update the userpass auth method's user + # configurations (e.g., "password") but cannot update the "token_policies" + # parameter value. + path "auth/userpass/users/*" { + capabilities = ["update"] denied_parameters = { - "bar" = [] + "token_policies" = [] } } ``` @@ -452,13 +464,13 @@ constrain requests, using the following options: containing those values. ```ruby - # This allows the user to create "secret/foo" with a parameter named - # "bar". It can contain any other parameters, but "bar" cannot contain - # the values "zip" or "zap". - path "secret/foo" { - capabilities = ["create"] + # This allows the user to create or update token roles. However, the + # "allowed_policies" parameter value cannot be "admin", but the user can + # assign any other policies to the parameter. + path "auth/token/roles/*" { + capabilities = ["create", "update"] denied_parameters = { - "bar" = ["zip", "zap"] + "allowed_policies" = ["admin"] } } ``` @@ -466,10 +478,12 @@ constrain requests, using the following options: - Setting to `"*"` will deny any parameter. ```ruby - # This allows the user to create "secret/foo", but it cannot have any - # parameters. - path "secret/foo" { - capabilities = ["create"] + # This allows the user to create or update an encryption key for transit + # secrets engine enabled at "transit/". However, the user cannot set any of + # the configuration parameters. As a result, the created key will have all + # parameters set to default values. + path "transit/keys/*" { + capabilities = ["create", "update"] denied_parameters = { "*" = [] }