1--- 2layout: "docs" 3page_title: "Policies" 4sidebar_title: "Policies" 5sidebar_current: "docs-concepts-policies" 6description: |- 7 Policies are how authorization is done in Vault, allowing you to restrict which parts of Vault a user can access. 8--- 9 10# Policies 11 12Everything in Vault is path based, and policies are no exception. Policies 13provide a declarative way to grant or forbid access to certain paths and 14operations in Vault. This section discusses policy workflows and syntaxes. 15 16Policies are **deny by default**, so an empty policy grants no permission in the 17system. 18 19## Policy-Authorization Workflow 20 21Before a human or machine can gain access, an administrator must configure Vault 22with an [auth method](/docs/concepts/auth.html). Authentication is 23the process by which human or machine-supplied information is verified against 24an internal or external system. 25 26Consider the following diagram, which illustrates the steps a security team 27would take to configure Vault to authenticate using a corporate LDAP or 28ActiveDirectory installation. Even though this example uses LDAP, the concept 29applies to all auth methods. 30 31[![Vault Auth Workflow](/img/vault-policy-workflow.svg)](/img/vault-policy-workflow.svg) 32 331. The security team configures Vault to connect to an auth method. 34This configuration varies by auth method. In the case of LDAP, Vault 35needs to know the address of the LDAP server and whether to connect using TLS. 36It is important to note that Vault does not store a copy of the LDAP database - 37Vault will delegate the authentication to the auth method. 38 391. The security team authors a policy (or uses an existing policy) which grants 40access to paths in Vault. Policies are written in HCL in your editor of 41preference and saved to disk. 42 431. The policy's contents are uploaded and stored in Vault and referenced by name. 44You can think of the policy's name as a pointer or symlink to its set of rules. 45 461. Most importantly, the security team maps data in the auth method to a policy. 47For example, the security team might create mappings like: 48 49 > Members of the OU group "dev" map to the Vault policy named "readonly-dev". 50 51 or 52 53 > Members of the OU group "ops" map to the Vault policies "admin" and "auditor". 54 55Now Vault has an internal mapping between a backend authentication system and 56internal policy. When a user authenticates to Vault, the actual authentication 57is delegated to the auth method. As a user, the flow looks like: 58 59[![Vault Auth Workflow](/img/vault-auth-workflow.svg)](/img/vault-auth-workflow.svg) 60 611. A user attempts to authenticate to Vault using their LDAP credentials, 62providing Vault with their LDAP username and password. 63 641. Vault establishes a connection to LDAP and asks the LDAP server to verify the 65given credentials. Assuming this is successful, the LDAP server returns the 66information about the user, including the OU groups. 67 681. Vault maps the result from the LDAP server to policies inside Vault using the 69mapping configured by the security team in the previous section. Vault then 70generates a token and attaches the matching policies. 71 721. Vault returns the token to the user. This token has the correct policies 73assigned, as dictated by the mapping configuration that was setup by the 74security team in advance. 75 76The user then uses this Vault token for future operations. If the user performs 77the authentication steps again, they will get a _new_ token. The token will have 78the same permissions, but the actual token will be different. Authenticating a 79second time does not invalidate the original token. 80 81## Policy Syntax 82 83Policies are written in [HCL][hcl] or JSON and describe which paths in Vault a 84user or machine is allowed to access. 85 86[hcl]: https://github.com/hashicorp/hcl 87 88Here is a very simple policy which grants read capabilities to the path 89"secret/foo": 90 91```ruby 92path "secret/foo" { 93 capabilities = ["read"] 94} 95``` 96 97When this policy is assigned to a token, the token can read from `"secret/foo"`. 98However, the token cannot update or delete `"secret/foo"`, since the 99capabilities do not allow it. Because policies are **deny by default**, the 100token would have no other access in Vault. 101 102Here is a more detailed policy, and it is documented inline: 103 104```ruby 105# This section grants all access on "secret/*". Further restrictions can be 106# applied to this broad policy, as shown below. 107path "secret/*" { 108 capabilities = ["create", "read", "update", "delete", "list"] 109} 110 111# Even though we allowed secret/*, this line explicitly denies 112# secret/super-secret. This takes precedence. 113path "secret/super-secret" { 114 capabilities = ["deny"] 115} 116 117# Policies can also specify allowed, disallowed, and required parameters. Here 118# the key "secret/restricted" can only contain "foo" (any value) and "bar" (one 119# of "zip" or "zap"). 120path "secret/restricted" { 121 capabilities = ["create"] 122 allowed_parameters = { 123 "foo" = [] 124 "bar" = ["zip", "zap"] 125 } 126} 127``` 128 129Policies use path-based matching to test the set of capabilities against a 130request. A policy `path` may specify an exact path to match, or it could specify 131a glob pattern which instructs Vault to use a prefix match: 132 133```ruby 134# Permit reading only "secret/foo". An attached token cannot read "secret/food" 135# or "secret/foo/bar". 136path "secret/foo" { 137 capabilities = ["read"] 138} 139 140# Permit reading everything under "secret/bar". An attached token could read 141# "secret/bar/zip", "secret/bar/zip/zap", but not "secret/bars/zip". 142path "secret/bar/*" { 143 capabilities = ["read"] 144} 145 146# Permit reading everything prefixed with "zip-". An attached token could read 147# "secret/zip-zap" or "secret/zip-zap/zong", but not "secret/zip/zap 148path "secret/zip-*" { 149 capabilities = ["read"] 150} 151``` 152 153In addition, a `+` can be used to denote any number of characters bounded 154within a single path segment (this appeared in Vault 1.1): 155 156```ruby 157# Permit reading the "teamb" path under any top-level path under secret/ 158path "secret/+/teamb" { 159 capabilities = ["read"] 160} 161 162# Permit reading secret/foo/bar/teamb, secret/bar/foo/teamb, etc. 163path "secret/+/+/teamb" { 164 capabilities = ["read"] 165} 166``` 167 168Vault's architecture is similar to a filesystem. Every action in Vault has a 169corresponding path and capability - even Vault's internal core configuration 170endpoints live under the "sys/" path. Policies define access to these paths and 171capabilities, which controls a token's access to credentials in Vault. 172 173~> Policy paths are matched using the **most specific path match**. This may be 174an exact match or the longest-prefix match of a glob. This means if you define a 175policy for `"secret/foo*"`, the policy would also match `"secret/foobar"`. 176 177!> The glob character referred to in this documentation is the asterisk (`*`). It *is not a regular expression* and is only supported **as the last character of the path**! 178 179When providing `list` capability, it is important to note that since listing 180always operates on a prefix, policies must operate on a prefix because Vault 181will sanitize request paths to be prefixes. In other words, policy paths 182targeting `list` capability should end with a trailing slash: 183 184```ruby 185path "secret/foo" { 186 capabilities = ["read"] 187} 188 189path "secret/foo/" { 190 capabilities = ["list"] 191} 192``` 193 194### Capabilities 195 196Each path must define one or more capabilities which provide fine-grained 197control over permitted (or denied) operations. As shown in the examples above, 198capabilities are always specified as a list of strings, even if there is only 199one capability. The list of capabilities are: 200 201~> In the list below, the associated HTTP verbs are shown in parenthesis next to 202the capability. When authoring policy, it is usually helpful to look at the HTTP 203API documentation for the paths and HTTP verbs and map them back onto 204capabilities. While the mapping is not strictly 1:1, they are often very 205similarly matched. 206 207 * `create` (`POST/PUT`) - Allows creating data at the given path. Very few 208 parts of Vault distinguish between `create` and `update`, so most operations 209 require both `create` and `update` capabilities. Parts of Vault that 210 provide such a distinction are noted in documentation. 211 212 * `read` (`GET`) - Allows reading the data at the given path. 213 214 * `update` (`POST/PUT`) - Allows changing the data at the given path. In most 215 parts of Vault, this implicitly includes the ability to create the initial 216 value at the path. 217 218 * `delete` (`DELETE`) - Allows deleting the data at the given path. 219 220 * `list` (`LIST`) - Allows listing values at the given path. Note that the 221 keys returned by a `list` operation are *not* filtered by policies. Do not 222 encode sensitive information in key names. Not all backends support listing. 223 224In addition to the standard set, there are some capabilities that do not map to 225HTTP verbs. 226 227 * `sudo` - Allows access to paths that are _root-protected_. Tokens are not 228 permitted to interact with these paths unless they are have the `sudo` 229 capability (in addition to the other necessary capabilities for performing 230 an operation against that path, such as `read` or `delete`). 231 232 For example, modifying the audit log backends requires a token with `sudo` 233 privileges. 234 235 * `deny` - Disallows access. This always takes precedence regardless of any 236 other defined capabilities, including `sudo`. 237 238~> Note that capabilities usually map to the HTTP verb, not the underlying 239action taken. This can be a common source of confusion. Generating database 240credentials _creates_ database credentials, but the HTTP request is a GET which 241corresponds to a `read` capability. Thus, to grant access to generate database 242credentials, the policy would grant `read` access on the appropriate path. 243 244## Templated Policies 245 246The policy syntax allows for doing variable replacement in some policy strings 247with values available to the token. Currently `identity` information can be 248injected, and currently the `path` keys in policies allow injection. 249 250### Parameters 251 252| Name | Description | 253| :--------------------------------------------------------------------- | :--------------------------------------------------------------------------- | 254| `identity.entity.id` | The entity's ID | 255| `identity.entity.name` | The entity's name | 256| `identity.entity.metadata.<<metadata key>>` | Metadata associated with the entity for the given key | 257| `identity.entity.aliases.<<mount accessor>>.id` | Entity alias ID for the given mount | 258| `identity.entity.aliases.<<mount accessor>>.name` | Entity alias name for the given mount | 259| `identity.entity.aliases.<<mount accessor>>.metadata.<<metadata key>>` | Metadata associated with the alias for the given mount and metadata key | 260| `identity.groups.ids.<<group id>>.name` | The group name for the given group ID | 261| `identity.groups.names.<<group name>>.id` | The group ID for the given group name | 262| `identity.groups.ids.<<group id>>.metadata.<<metadata key>>` | Metadata associated with the group for the given key | 263| `identity.groups.names.<<group name>>.metadata.<<metadata key>>` | Metadata associated with the group for the given key | 264 265### Examples 266 267The following policy creates a section of the KVv2 Secret Engine to a specific user 268 269```ruby 270path "secret/data/{{identity.entity.id}}/*" { 271 capabilities = ["create", "update", "read", "delete"] 272} 273 274path "secret/metadata/{{identity.entity.id}}/*" { 275 capabilities = ["list"] 276} 277``` 278 279If you wanted to create a shared section of KV that is associated with entities that are in a 280group. 281 282```ruby 283# In the example below, the group ID maps a group and the path 284path "secret/data/groups/{{identity.groups.ids.fb036ebc-2f62-4124-9503-42aa7A869741.name}}/*" { 285 capabilities = ["create", "update", "read", "delete"] 286} 287 288path "secret/metadata/groups/{{identity.groups.ids.fb036ebc-2f62-4124-9503-42aa7A869741.name}}/*" { 289 capabilities = ["list"] 290} 291``` 292 293 ~> When developing templated policies, use IDs wherever possible. Each ID is 294 unique to the user, whereas names can change over time and can be reused. This 295 ensures that if a given user or group name is changed, the policy will be 296 mapped to the intended entity or group. 297 298## Fine-Grained Control 299 300In addition to the standard set of capabilities, Vault offers finer-grained 301control over permissions at a given path. The capabilities associated with a 302path take precedence over permissions on parameters. 303 304### Parameter Constraints 305 306In Vault, data is represented as `key=value` pairs. Vault policies can 307optionally further restrict paths based on the keys and data at those keys when 308evaluating the permissions for a path. The optional finer-grained control 309options are: 310 311 * `required_parameters` - A list of parameters that must be specified. 312 313 ```ruby 314 # This requires the user to create "secret/foo" with a parameter named 315 # "bar" and "baz". 316 path "secret/foo" { 317 capabilities = ["create"] 318 required_parameters = ["bar", "baz"] 319 } 320 ``` 321 322 * `allowed_parameters` - Whitelists a list of keys and values that are 323 permitted on the given path. 324 325 * Setting a parameter with a value of the empty list allows the parameter to 326 contain any value. 327 328 ```ruby 329 # This allows the user to create "secret/foo" with a parameter named 330 # "bar". It cannot contain any other parameters, but "bar" can contain 331 # any value. 332 path "secret/foo" { 333 capabilities = ["create"] 334 allowed_parameters = { 335 "bar" = [] 336 } 337 } 338 ``` 339 340 * Setting a parameter with a value of a populated list allows the parameter 341 to contain only those values. 342 343 ```ruby 344 # This allows the user to create "secret/foo" with a parameter named 345 # "bar". It cannot contain any other parameters, and "bar" can only 346 # contain the values "zip" or "zap". 347 path "secret/foo" { 348 capabilities = ["create"] 349 allowed_parameters = { 350 "bar" = ["zip", "zap"] 351 } 352 } 353 ``` 354 355 * If any keys are specified, all non-specified parameters will be denied 356 unless the parameter `"*"` is set to an empty array, which will 357 allow all other parameters to be modified. Parameters with specific values 358 will still be restricted to those values. 359 360 ```ruby 361 # This allows the user to create "secret/foo" with a parameter named 362 # "bar". The parameter "bar" can only contain the values "zip" or "zap", 363 # but any other parameters may be created with any value. 364 path "secret/foo" { 365 capabilities = ["create"] 366 allowed_parameters = { 367 "bar" = ["zip", "zap"] 368 "*" = [] 369 } 370 } 371 ``` 372 373 * `denied_parameters` - Blacklists a list of parameter and values. Any values 374 specified here take precedence over `allowed_parameters`. 375 376 * Setting a parameter with a value of the empty list denies any changes to 377 that parameter. 378 379 ```ruby 380 # This allows the user to create "secret/foo" with any parameters not 381 # named "bar". 382 path "secret/foo" { 383 capabilities = ["create"] 384 denied_parameters = { 385 "bar" = [] 386 } 387 } 388 ``` 389 390 * Setting a parameter with a value of a populated list denies any parameter 391 containing those values. 392 393 ```ruby 394 # This allows the user to create "secret/foo" with a parameter named 395 # "bar". It can contain any other parameters, but "bar" cannot contain 396 # the values "zip" or "zap". 397 path "secret/foo" { 398 capabilities = ["create"] 399 denied_parameters = { 400 "bar" = ["zip", "zap"] 401 } 402 } 403 ``` 404 405 * Setting to `"*"` will deny any parameter. 406 407 ```ruby 408 # This allows the user to create "secret/foo", but it cannot have any 409 # parameters. 410 path "secret/foo" { 411 capabilities = ["create"] 412 denied_parameters = { 413 "*" = [] 414 } 415 } 416 ``` 417 418 * If any parameters are specified, all non-specified parameters are allowed, 419 unless `allowed_parameters` is also set, in which case normal rules apply. 420 421Parameter values also support prefix/suffix globbing. Globbing is enabled by 422prepending or appending or prepending a splat (`*`) to the value: 423 424```ruby 425# Only allow a parameter named "bar" with a value starting with "foo-*". 426path "secret/foo" { 427 capabilities = ["create"] 428 allowed_parameters = { 429 "bar" = ["foo-*"] 430 } 431} 432``` 433 434Note: the only value that can be used with the `*` parameter is `[]`. 435 436 437### Required Response Wrapping TTLs 438 439These parameters can be used to set minimums/maximums on TTLs set by clients 440when requesting that a response be 441[wrapped](/docs/concepts/response-wrapping.html), with a granularity of a 442second. These can either be specified as a number of seconds or a string with a 443`s`, `m`, or `h` suffix indicating seconds, minutes, and hours respectively. 444 445In practice, setting a minimum TTL of one second effectively makes response 446wrapping mandatory for a particular path. 447 448 * `min_wrapping_ttl` - The minimum allowed TTL that clients can specify for a 449 wrapped response. In practice, setting a minimum TTL of one second 450 effectively makes response wrapping mandatory for a particular path. It can 451 also be used to ensure that the TTL is not too low, leading to end targets 452 being unable to unwrap before the token expires. 453 454 * `max_wrapping_ttl` - The maximum allowed TTL that clients can specify for a 455 wrapped response. 456 457```ruby 458# This effectively makes response wrapping mandatory for this path by setting min_wrapping_ttl to 1 second. 459# This also sets this path's wrapped response maximum allowed TTL to 90 seconds. 460path "auth/approle/role/my-role/secret-id" { 461 capabilities = ["create", "update"] 462 min_wrapping_ttl = "1s" 463 max_wrapping_ttl = "90s" 464} 465``` 466 467If both are specified, the minimum value must be less than the maximum. In 468addition, if paths are merged from different stanzas, the lowest value 469specified for each is the value that will result, in line with the idea of 470keeping token lifetimes as short as possible. 471 472## Builtin Policies 473 474Vault has two built-in policies: `default` and `root`. This section describes 475the two builtin policies. 476 477### Default Policy 478 479The `default` policy is a builtin Vault policy that cannot be removed. By 480default, it is attached to all tokens, but may be explicitly excluded at token 481creation time by supporting authentication methods. 482 483The policy contains basic functionality such as the ability for the token to 484look up data about itself and to use its cubbyhole data. However, Vault is not 485proscriptive about its contents. It can be modified to suit your needs; Vault 486will never overwrite your modifications. If you want to stay up-to-date with 487the latest upstream version of the `default` policy, simply read the contents 488of the policy from an up-to-date `dev` server, and write those contents into 489your Vault's `default` policy. 490 491To view all permissions granted by the default policy on your Vault 492installation, run: 493 494```sh 495$ vault read sys/policy/default 496``` 497 498To disable attachment of the default policy: 499 500```sh 501$ vault token create -no-default-policy 502``` 503 504or via the API: 505 506```sh 507$ curl \ 508 --request POST \ 509 --header "X-Vault-Token: ..." \ 510 --data '{"no_default_policy": "true"}' \ 511 https://vault.hashicorp.rocks/v1/auth/token/create 512``` 513 514### Root Policy 515 516The `root` policy is a builtin Vault policy that can not be modified or removed. 517Any user associated with this policy becomes a root user. A root user can do 518_anything_ within Vault. As such, it is **highly recommended** that you revoke 519any root tokens before running Vault in production. 520 521When a Vault server is first initialized, there always exists one root user. 522This user is used to do the initial configuration and setup of Vault. After 523configured, the initial root token should be revoked and more strictly 524controlled users and authentication should be used. 525 526To revoke a root token, run: 527 528```sh 529$ vault token revoke "<token>" 530``` 531 532or via the API: 533 534```sh 535$ curl \ 536 --request POST \ 537 --header "X-Vault-Token: ..." \ 538 --data '{"token": "<token>"}' \ 539 https://vault.hashicorp.rocks/v1/auth/token/revoke 540``` 541 542For more information, please read: 543 544- [Production Hardening](/guides/operations/production.html) 545- [Generating a Root Token](/guides/operations/generate-root.html) 546 547## Managing Policies 548 549Policies are authored (written) in your editor of choice. They can be authored 550in HCL or JSON, and the syntax is described in detail above. Once saved, 551policies must be uploaded to Vault before they can be used. 552 553### Listing Policies 554 555To list all registered policies in Vault: 556 557```sh 558$ vault read sys/policy 559``` 560 561or via the API: 562 563```sh 564$ curl \ 565 --header "X-Vault-Token: ..." \ 566 https://vault.hashicorp.rocks/v1/sys/policy 567``` 568 569~> You may also see the CLI command `vault policies`. This is a convenience 570wrapper around reading the sys endpoint directly. It provides the same 571functionality but formats the output in a special manner. 572 573### Creating Policies 574 575Policies may be created (uploaded) via the CLI or via the API. To create a new 576policy in Vault: 577 578```sh 579$ vault policy write policy-name policy-file.hcl 580``` 581 582or via the API: 583 584```sh 585$ curl \ 586 --request POST \ 587 --header "X-Vault-Token: ..." \ 588 --data '{"policy":"path \"...\" {...} "}' \ 589 https://vault.hashicorp.rocks/v1/sys/policy/policy-name 590``` 591 592In both examples, the name of the policy is "policy-name". You can think of this 593name as a pointer or symlink to the policy ACLs. Tokens are attached policies by 594name, which are then mapped to the set of rules corresponding to that name. 595 596### Updating Policies 597 598Existing policies may be updated to change permissions via the CLI or via the 599API. To update an existing policy in Vault, follow the same steps as creating a 600policy, but use an existing policy name: 601 602```sh 603$ vault write sys/policy/my-existing-policy policy=@updated-policy.json 604``` 605 606or via the API: 607 608```sh 609$ curl \ 610 --request POST \ 611 --header "X-Vault-Token: ..." \ 612 --data '{"policy":"path \"...\" {...} "}' \ 613 https://vault.hashicorp.rocks/v1/sys/policy/my-existing-policy 614``` 615 616### Deleting Policies 617 618Existing policies may be deleted via the CLI or API. To delete a policy: 619 620```sh 621$ vault delete sys/policy/policy-name 622``` 623 624or via the API: 625 626```sh 627$ curl \ 628 --request DELETE \ 629 --header "X-Vault-Token: ..." \ 630 https://vault.hashicorp.rocks/v1/sys/policy/policy-name 631``` 632 633This is an idempotent operation. Vault will not return an error when deleting a 634policy that does not exist. 635 636## Associating Policies 637 638Vault can automatically associate a set of policies to a token based on an 639authorization. This configuration varies significantly between authentication 640backends. For simplicity, this example will use Vault's built-in userpass 641auth method. 642 643A Vault administrator or someone from the security team would create the user in 644Vault with a list of associated policies: 645 646```sh 647$ vault write auth/userpass/users/sethvargo \ 648 password="s3cr3t!" \ 649 policies="dev-readonly,logs" 650``` 651 652This creates an authentication mapping to the policy such that, when the user 653authenticates successfully to Vault, they will be given a token which has the list 654of policies attached. 655 656The user wishing to authenticate would run 657 658```sh 659$ vault login -method="userpass" username="sethvargo" 660Password (will be hidden): ... 661``` 662 663If the provided information is correct, Vault will generate a token, assign the 664list of configured policies to the token, and return that token to the 665authenticated user. 666 667### Tokens 668 669Tokens are associated with their policies at creation time. For example: 670 671```sh 672$ vault token create -policy=dev-readonly -policy=logs 673``` 674 675Child tokens can be associated with a subset of a parent's policies. Root users 676can assign any policies. 677 678There is no way to modify the policies associated with a token once the token 679has been issued. The token must be revoked and a new one acquired to receive a 680new set of policies. 681 682However, the _contents_ of policies are parsed in real-time whenever the token is used. 683As a result, if a policy is modified, the modified rules will be in force the 684next time a token, with that policy attached, is used to make a call to Vault. 685 686 687## Learn 688 689Refer to the following tutorials for further learning: 690 691- [Vault Policies](https://learn.hashicorp.com/vault/identity-access-management/iam-policies) 692- [ACL Policy Path Templating](https://learn.hashicorp.com/vault/identity-access-management/policy-templating) 693