diff --git a/website/content/docs/concepts/policies.mdx b/website/content/docs/concepts/policies.mdx index 63a43bf24..4df90be91 100644 --- a/website/content/docs/concepts/policies.mdx +++ b/website/content/docs/concepts/policies.mdx @@ -15,7 +15,7 @@ operations in Vault. This section discusses policy workflows and syntaxes. Policies are **deny by default**, so an empty policy grants no permission in the system. -## Policy-Authorization Workflow +## Policy-authorization workflow Before a human or machine can gain access, an administrator must configure Vault with an [auth method](/vault/docs/concepts/auth). Authentication is @@ -255,7 +255,7 @@ credentials _creates_ database credentials, but the HTTP request is a GET which corresponds to a `read` capability. Thus, to grant access to generate database credentials, the policy would grant `read` access on the appropriate path. -## Templated Policies +## Templated policies The policy syntax allows for doing variable replacement in some policy strings with values available to the token. Currently `identity` information can be @@ -333,13 +333,13 @@ path "secret/data/{{identity.entity.aliases.auth_kubernetes_xxxx.metadata.servic } ``` -## Fine-Grained Control +## Fine-grained control In addition to the standard set of capabilities, Vault offers finer-grained control over permissions at a given path. The capabilities associated with a path take precedence over permissions on parameters. -### Parameter Constraints +### Parameter constraints !> **Note:** The use of [globs](/vault/docs/concepts/policies#policy-syntax) (`*`) may result in [surprising or unexpected behavior](#parameter-constraints-limitations). @@ -354,13 +354,13 @@ constrain requests, using the following options: ```ruby # This requires the user to create "secret/profile" with a parameter/key named - # "name" and "id" where kv v1 is enabled at "secret/". + # "name" and "id" where kv v1 is enabled at "secret/". path "secret/profile" { capabilities = ["create"] required_parameters = ["name", "id"] } ``` - + - `allowed_parameters` - A list of keys and values that are permitted on the given path. @@ -371,7 +371,7 @@ constrain requests, using the following options: # 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. + # token_ttl. path "auth/userpass/users/*" { capabilities = ["update"] allowed_parameters = { @@ -384,7 +384,7 @@ constrain requests, using the following options: Templating](/vault/tutorials/policies/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](/vault/docs/auth/userpass) to log in with Vault. + method](/vault/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. @@ -422,7 +422,7 @@ constrain requests, using the following options: } ``` -- `denied_parameters` - A list of keys and values that are not permitted on the given +- `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`. - Setting a parameter with a value of the empty list denies any changes to @@ -447,7 +447,7 @@ constrain requests, using the following options: ```ruby # 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. + # assign any other policies to the parameter. path "auth/token/roles/*" { capabilities = ["create", "update"] denied_parameters = { @@ -567,7 +567,7 @@ path "secret/foo" { } } ``` -### Required Response Wrapping TTLs +### Required response wrapping TTLs These parameters can be used to set minimums/maximums on TTLs set by clients when requesting that a response be @@ -643,7 +643,7 @@ $ curl \ https://vault.hashicorp.rocks/v1/auth/token/create ``` -### Root Policy +### Root policy The `root` policy is a built-in Vault policy that cannot be modified or removed. Any user associated with this policy becomes a root user. A root user can do @@ -676,13 +676,13 @@ For more information, please read: - [Production Hardening](/vault/tutorials/operations/production-hardening) - [Generating a Root Token](/vault/tutorials/operations/generate-root) -## Managing Policies +## Managing policies Policies are authored (written) in your editor of choice. They can be authored in HCL or JSON, and the syntax is described in detail above. Once saved, policies must be uploaded to Vault before they can be used. -### Listing Policies +### Listing policies To list all registered policies in Vault: @@ -702,7 +702,7 @@ $ curl \ wrapper around reading the sys endpoint directly. It provides the same functionality but formats the output in a special manner. -### Creating Policies +### Creating policies Policies may be created (uploaded) via the CLI or via the API. To create a new policy in Vault: @@ -725,7 +725,7 @@ In both examples, the name of the policy is "policy-name". You can think of this name as a pointer or symlink to the policy ACLs. Tokens are attached policies by name, which are then mapped to the set of rules corresponding to that name. -### Updating Policies +### Updating policies Existing policies may be updated to change permissions via the CLI or via the API. To update an existing policy in Vault, follow the same steps as creating a @@ -745,7 +745,7 @@ $ curl \ https://vault.hashicorp.rocks/v1/sys/policy/my-existing-policy ``` -### Deleting Policies +### Deleting policies Existing policies may be deleted via the CLI or API. To delete a policy: @@ -765,7 +765,7 @@ $ curl \ This is an idempotent operation. Vault will not return an error when deleting a policy that does not exist. -## Associating Policies +## Associating policies Vault can automatically associate a set of policies to a token based on an authorization. This configuration varies significantly between authentication @@ -796,6 +796,37 @@ If the provided information is correct, Vault will generate a token, assign the list of configured policies to the token, and return that token to the authenticated user. +## Root protected API endpoints + +The following paths requires a root token or `sudo` capability in the policy: + +| Path | HTTP verb | Description | +| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | +| [auth/token/accessors](/vault/api-docs/auth/token#list-accessors) | LIST | List token accessor | +| [auth/token/create-orphan](/vault/api-docs/auth/token#create-token) | POST | Create an orphan token (the same as `no_parent` option) | +| [auth/token](/vault/api-docs/auth/token#create-token) | POST | Create a periodic or an orphan token (`period` or `no_parent`) option | +| [pki/root](/vault/api-docs/secret/pki#delete-root) | DELETE | Delete the current CA key ([pki secrets engine](/vault/docs/secrets/pki)) | +| [pki/root/sign-self-issued](/vault/api-docs/secret/pki#sign-self-issued) | POST | Use the configured CA certificate to sign a self-issued certificate ([pki secrets engine](/vault/docs/secrets/pki)) | +| [sys/audit](/vault/api-docs/system/audit) | GET | List enabled audit devices | +| [sys/audit/:path](/vault/api-docs/system/audit) | PUT, DELETE | Enable or remove an audit device | +| [sys/auth/:path](/vault/api-docs/system/auth) | GET, POST, DELETE | Manage the auth methods (enable, read, delete, and tune) | +| [sys/config/auditing/request-headers](/vault/api-docs/system/config-auditing) | GET | List the request headers that are configured to be audited | +| [sys/config/auditing/request-headers:name](/vault/api-docs/system/config-auditing) | GET, PUT, DELETE | Manage the auditing headers (create, update, read and delete) | +| [sys/config/cors](/vault/api-docs/system/config-cors) | GET, PUT, DELETE | Configure CORS setting | +| [sys/config-ui](/vault/api-docs/system/config-ui) | GET | Configure the UI settings | +| [sys/internal/specs/openapi](/vault/api-docs/system/internal-specs-openapi) | GET | Generate an OpenAPI document of the mounted backends | +| [sys/leases/lookup/:prefix](/vault/api-docs/system/leases#list-leases) | LIST | List lease IDs | +| [sys/leases/revoke-force/:prefix](/vault/api-docs/system/leases#revoke-force) | PUT | Revoke all secrets or tokens ignoring backend errors | +| [sys/leases/revoke-prefix/:prefix](/vault/api-docs/system/leases#revoke-prefix) | PUT | Revoke all secrets generated under a given prefix | +| [sys/plugins/catalog/:type/:name](/vault/api-docs/system/plugins-catalog#register-plugin) | GET, PUT, DELETE | Register a new plugin, or read/remove an existing plugin | +| [sys/raw](/vault/api-docs/system/raw#list-raw) | LIST, GET | Returns a list of keys for a given path prefix | +| [sys/replication/reindex](/vault/api-docs/system/replication#reindex-replication) | POST | Reindex the local data storage | +| [sys/replication/performance/primary/secondary-token](/vault/api-docs/system/replication/replication-performance#generate-performance-secondary-token) | POST | Generate a performance secondary activation token | +| [sys/replication/dr/primary/secondary-token](/vault/api-docs/system/replication/replication-dr#generate-dr-secondary-token) | POST | Generate a DR secondary activation token | +| [sys/rotate](/vault/api-docs/system/rotate) | PUT | Trigger a rotation of the backend encryption key | +| [sys/seal](/vault/api-docs/system/seal) | PUT | Seals the Vault | +| [sys/step-down](/vault/api-docs/system/step-down) + ### Tokens Tokens have two sets of policies: identity policies, which are computed