1--- 2layout: "guides" 3page_title: "Policies - Guides" 4sidebar_title: "Policies" 5sidebar_current: "guides-identity-policies" 6description: |- 7 Policies in Vault control what a user can access. 8--- 9 10# Policies 11 12In Vault, we use policies to govern the behavior of clients and instrument 13Role-Based Access Control (RBAC) by specifying access privileges 14(_authorization_). 15 16When you first initialize Vault, the 17[**`root`**](/docs/concepts/policies.html#root-policy) policy gets created by 18default. The `root` policy is a special policy that gives superuser access to 19_everything_ in Vault. This allows the superuser to set up initial policies, 20tokens, etc. 21 22In addition, another built-in policy, 23[**`default`**](/docs/concepts/policies.html#default-policy), is created. The 24`default` policy is attached to all tokens and provides common permissions. 25 26Everything in Vault is path based, and admins write policies to grant or forbid 27access to certain paths and operations in Vault. Vault operates on a **secure by 28default** standard, and as such, an empty policy grants **no permissions** in the 29system. 30 31 32### HashiCorp Configuration Language (HCL) 33 34Policies written in [HCL](https://github.com/hashicorp/hcl) format are often 35referred as **_ACL Policies_**. [Sentinel](https://www.hashicorp.com/sentinel) is 36another framework for policy which is available in [Vault 37Enterprise](/docs/enterprise/index.html). Since Sentinel is an enterprise-only 38feature, this guide focuses on writing ACL policies as a foundation. 39 40**NOTE:** HCL is JSON compatible; therefore, JSON can be used as completely 41valid input. 42 43## Reference Material 44 45- [Policies](/docs/concepts/policies.html#default-policy) documentation 46- [Policy API](/api/system/policy.html) documentation 47- [Getting Started guide](/intro/getting-started/policies.html) on policies 48 49~> **NOTE:** An [interactive 50tutorial](https://www.katacoda.com/hashicorp/scenarios/vault-policies) is 51also available if you do not have a Vault environment to perform the steps 52described in this guide. 53 54 55## Estimated Time to Complete 56 5710 minutes 58 59## Personas 60 61The scenario described in this guide introduces the following personas: 62 63- **`root`** sets up initial policies for `admin` 64- **`admin`** is empowered with managing a Vault infrastructure for a team or 65organizations 66- **`provisioner`** configures secret engines and creates policies for 67client apps 68 69 70## Challenge 71 72Since Vault centrally secures, stores, and controls access to secrets across 73distributed infrastructure and applications, it is critical to control 74permissions before any user or machine can gain access. 75 76 77## Solution 78 79Restrict the use of root policy, and write fine-grained policies to practice 80**least privileged**. For example, if an app gets AWS credentials from Vault, 81write policy grants to `read` from AWS secret engine but not to `delete`, etc. 82 83Policies are attached to tokens and roles to enforce client permissions on 84Vault. 85 86 87## Prerequisites 88 89To perform the tasks described in this guide, you need to have a Vault 90environment. Refer to the [Getting 91Started](/intro/getting-started/install.html) guide to install Vault. Make sure 92that your Vault server has been [initialized and 93unsealed](/intro/getting-started/deploy.html). 94 95### Policy requirements 96 97Since this guide demonstrates the creation of an **`admin`** policy, log in with 98**`root`** token if possible. Otherwise, make sure that you have the following 99permissions: 100 101```shell 102# Manage auth methods broadly across Vault 103path "auth/*" 104{ 105 capabilities = ["create", "read", "update", "delete", "list", "sudo"] 106} 107 108# Create, update, and delete auth methods 109path "sys/auth/*" 110{ 111 capabilities = ["create", "update", "delete", "sudo"] 112} 113 114# List auth methods 115path "sys/auth" 116{ 117 capabilities = ["read"] 118} 119 120# Create and manage ACL policies via CLI 121path "sys/policy/*" 122{ 123 capabilities = ["create", "read", "update", "delete", "list", "sudo"] 124} 125 126# Create and manage ACL policies via API 127path "sys/policies/acl/*" 128{ 129 capabilities = ["create", "read", "update", "delete", "list", "sudo"] 130} 131 132# To list policies - Step 3 133path "sys/policy" 134{ 135 capabilities = ["read"] 136} 137 138# To perform Step 4 139path "sys/capabilities" 140{ 141 capabilities = ["create", "update"] 142} 143 144# To perform Step 4 145path "sys/capabilities-self" 146{ 147 capabilities = ["create", "update"] 148} 149 150# List, create, update, and delete key/value secrets 151path "secret/*" 152{ 153 capabilities = ["create", "read", "update", "delete", "list", "sudo"] 154} 155 156# Manage secret engines broadly across Vault 157path "sys/mounts/*" 158{ 159 capabilities = ["create", "read", "update", "delete", "list", "sudo"] 160} 161 162# List existing secret engines 163path "sys/mounts" 164{ 165 capabilities = ["read"] 166} 167 168# Read health checks 169path "sys/health" 170{ 171 capabilities = ["read", "sudo"] 172} 173``` 174 175 176## Steps 177 178The basic workflow of creating policies is: 179 180![Policy Creation Workflow](/img/vault-policy-authoring-workflow.png) 181 182This guide demonstrates basic policy authoring and management tasks. 183 1841. [Write ACL policies in HCL format](#step1) 1851. [Create policies](#step2) 1861. [View existing policies](#step3) 1871. [Check capabilities of a token](#step4) 188 189 190### <a name="step1"></a>Step 1: Write ACL policies in HCL format 191 192Remember, an empty policy grants **no permission** in the system. Therefore, ACL 193policies are defined for each path. 194 195```shell 196path "<PATH>" { 197 capabilities = [ "<LIST_OF_CAPABILITIES>" ] 198} 199``` 200 201-> The path can have a wildcard ("`*`") at the end to allow for 202namespacing. For example, "`secret/training_*`" grants permissions on any 203path starting with "`secret/training_`" (e.g. `secret/training_vault`). 204 205Define one or more [capabilities](/docs/concepts/policies.html#capabilities) on each path to control operations that are 206permitted. 207 208| Capability | Associated HTTP verbs | 209| --------------- |------------------------| 210| create | POST/PUT | 211| read | GET | 212| update | POST/PUT | 213| delete | DELETE | 214| list | LIST 215 216 217#### Policy requirements 218 219The first step in creating policies is to **gather policy requirements**. 220 221**Example:** 222 223**`admin`** is a type of user empowered with managing a Vault infrastructure for 224a team or organizations. Empowered with sudo, the Administrator is focused on 225configuring and maintaining the health of Vault cluster(s) as well as 226providing bespoke support to Vault users. 227 228`admin` must be able to: 229 230- Enable and manage auth methods broadly across Vault 231- Manage the key/value secret engines at `secret/` path 232- Create and manage ACL policies broadly across Vault 233- Read system health check 234 235**`provisioner`** is a type of user or service that will be used by an automated 236tool (e.g. Terraform) to provision and configure a namespace within a Vault 237secret engine for a new Vault user to access and write secrets. 238 239`provisioner` must be able to: 240 241- Enable and manage auth methods 242- Manage the key/value secret engines at `secret/` path 243- Create and manage ACL policies 244 245 246Now, you are ready to author policies to fulfill these requirements. 247 248#### Example policy for admin 249 250`admin-policy.hcl` 251 252```shell 253# Manage auth methods broadly across Vault 254path "auth/*" 255{ 256 capabilities = ["create", "read", "update", "delete", "list", "sudo"] 257} 258 259# Create, update, and delete auth methods 260path "sys/auth/*" 261{ 262 capabilities = ["create", "update", "delete", "sudo"] 263} 264 265# List auth methods 266path "sys/auth" 267{ 268 capabilities = ["read"] 269} 270 271# List existing policies via CLI 272path "sys/policy" 273{ 274 capabilities = ["read"] 275} 276 277# Create and manage ACL policies via CLI 278path "sys/policy/*" 279{ 280 capabilities = ["create", "read", "update", "delete", "list", "sudo"] 281} 282 283# Create and manage ACL policies via API 284path "sys/policies/acl/*" 285{ 286 capabilities = ["create", "read", "update", "delete", "list", "sudo"] 287} 288 289# List, create, update, and delete key/value secrets 290path "secret/*" 291{ 292 capabilities = ["create", "read", "update", "delete", "list", "sudo"] 293} 294 295# Manage secret engines broadly across Vault 296path "sys/mounts/*" 297{ 298 capabilities = ["create", "read", "update", "delete", "list", "sudo"] 299} 300 301# List existing secret engines 302path "sys/mounts" 303{ 304 capabilities = ["read"] 305} 306 307# Read health checks 308path "sys/health" 309{ 310 capabilities = ["read", "sudo"] 311} 312``` 313 314#### Example policy for provisioner 315 316`provisioner-policy.hcl` 317 318```shell 319# Manage auth methods broadly across Vault 320path "auth/*" 321{ 322 capabilities = ["create", "read", "update", "delete", "list", "sudo"] 323} 324 325# Create, update, and delete auth methods 326path "sys/auth/*" 327{ 328 capabilities = ["create", "update", "delete", "sudo"] 329} 330 331# List auth methods 332path "sys/auth" 333{ 334 capabilities = ["read"] 335} 336 337# List existing policies via CLI 338path "sys/policy" 339{ 340 capabilities = ["read"] 341} 342 343# Create and manage ACL policies via CLI 344path "sys/policy/*" 345{ 346 capabilities = ["create", "read", "update", "delete", "list", "sudo"] 347} 348 349# Create and manage ACL policies via API 350path "sys/policies/acl/*" 351{ 352 capabilities = ["create", "read", "update", "delete", "list", "sudo"] 353} 354 355# List, create, update, and delete key/value secrets 356path "secret/*" 357{ 358 capabilities = ["create", "read", "update", "delete", "list"] 359} 360``` 361 362### <a name="step2"></a>Step 2: Create policies 363 364Now, create `admin` and `provisioner` policies in Vault. 365 366#### CLI command 367 368To create policies: 369 370```shell 371$ vault policy write <POLICY_NAME> <POLICY_FILE> 372``` 373 374**Example:** 375 376```shell 377# Create admin policy 378$ vault policy write admin admin-policy.hcl 379 380# Create provisioner policy 381$ vault policy write provisioner provisioner-policy.hcl 382``` 383 384**NOTE:** To update an existing policy, simply re-run the same command by 385passing your modified policy (`*.hcl`). 386 387#### API call using cURL 388 389To create a policy, use the 390[`sys/policies/acl`](/api/system/policies.html#create-update-acl-policy) 391endpoint: 392 393```shell 394$ curl --header "X-Vault-Token: <TOKEN>" \ 395 --request PUT \ 396 --data <PAYLOAD> \ 397 <VAULT_ADDRESS>/v1/sys/policies/acl/<POLICY_NAME> 398``` 399 400Where `<TOKEN>` is your valid token, and `<PAYLOAD>` includes the policy name and 401stringified policy. 402 403-> **NOTE:** To create ACL policies, you can use the 404[`sys/policy`](/api/system/policy.html) endpoint as well. 405 406**Example:** 407 408```shell 409# Create the API request payload. Use stringified policy expression. 410$ tee admin-payload.json <<EOF 411{ 412 "policy": "# Manage auth methods broadly across Vault\npath \"auth/*\"\n{\n capabilities = [\"create\", \"read\", \"update\", \"delete\", \"list\", \"sudo\"]\n}\n\n# List, create, update, and delete auth methods\npath \"sys/auth/*\"\n{\n capabilities = [\"create\", \"read\", \"update\", \"delete\", \"sudo\"]\n}\n\n# List auth methods\npath \"sys/auth\"\n{\n capabilities = [\"read\"]\n}\n\n# List existing policies\npath \"sys/policies\"\n{\n capabilities = [\"read\"]\n}\n\n# Create and manage ACL policies broadly across Vault\npath \"sys/policies/*\"\n{\n capabilities = [\"create\", \"read\", \"update\", \"delete\", \"list\", \"sudo\"]\n}\n\n# List, create, update, and delete key/value secrets\npath \"secret/*\"\n{\n capabilities = [\"create\", \"read\", \"update\", \"delete\", \"list\", \"sudo\"]\n}\n\n# Manage and manage secret engines broadly across Vault.\npath \"sys/mounts/*\"\n{\n capabilities = [\"create\", \"read\", \"update\", \"delete\", \"list\", \"sudo\"]\n}\n\n# List existing secret engines.\npath \"sys/mounts\"\n{\n capabilities = [\"read\"]\n}\n\n# Read health checks\npath \"sys/health\"\n{\n capabilities = [\"read\", \"sudo\"]\n}" 413} 414EOF 415 416# Create admin policy 417$ curl --header "X-Vault-Token: ..." \ 418 --request PUT \ 419 --data @admin-payload.json \ 420 http://127.0.0.1:8200/v1/sys/policies/acl/admin 421 422# Create the API requset payload for creating provisioner policy 423$ tee provisioner-payload.json <<EOF 424{ 425 "policy": "# Manage auth methods broadly across Vault\npath \"auth/*\"\n{\n capabilities = [\"create\", \"read\", \"update\", \"delete\", \"list\", \"sudo\"]\n}\n\n# List, create, update, and delete auth methods\npath \"sys/auth/*\"\n{\n capabilities = [\"create\", \"read\", \"update\", \"delete\", \"sudo\"]\n}\n\n# List existing policies\npath \"sys/policy\"\n{\n capabilities = [\"read\"]\n}\n\n# Create and manage ACL policies\npath \"sys/policy/*\"\n{\n capabilities = [\"create\", \"read\", \"update\", \"delete\", \"list\"]\n}\n\n# List, create, update, and delete key/value secrets\npath \"secret/*\"\n{\n capabilities = [\"create\", \"read\", \"update\", \"delete\", \"list\"]\n}" 426} 427EOF 428 429# Create provisioner policy 430$ curl --header "X-Vault-Token: ..." \ 431 --request PUT \ 432 --data @provisioner-payload.json \ 433 http://127.0.0.1:8200/v1/sys/policies/acl/provisioner 434``` 435 436**NOTE:** To update an existing policy, simply re-run the same command by 437passing your modified policy in the request payload (`*.json`). 438 439 440### <a name="step3"></a>Step 3: View existing policies 441 442Make sure that you see the policies you created in [Step 2](#step2). 443 444#### CLI command 445 446The following command lists existing policies: 447 448```shell 449$ vault policy list 450``` 451 452To view a specific policy: 453 454```shell 455$ vault policy read <POLICY_NAME> 456``` 457 458**Example:** 459 460```shell 461# Read admin policy 462$ vault policy read admin 463 464# Mount and manage auth methods broadly across Vault 465path "auth/*" 466{ 467 capabilities = ["create", "read", "update", "delete", "list", "sudo"] 468} 469 470path "sys/auth/*" 471{ 472 capabilities = ["create", "read", "update", "delete", "sudo"] 473} 474 475# Create and manage ACL policies broadly across Vault 476path "sys/policy/*" 477{ 478 capabilities = ["create", "read", "update", "delete", "list", "sudo"] 479} 480... 481``` 482 483#### API call using cURL 484 485To list existing ACL policies, use the `sys/policies/acl` endpoint. 486 487```shell 488$ curl --request LIST --header "X-Vault-Token: ..." http://127.0.0.1:8200/v1/sys/policies/acl | jq 489``` 490 491To read a specific policy, the endpoint path should be 492`sys/policies/acl/<POLICY_NAME>`. 493 494-> **NOTE:** To read existing ACL policies, you can use the `sys/policy` 495endpoint as well. 496 497**Example:** 498 499```shell 500# Read the admin policy 501$ curl --header "X-Vault-Token: ..." http://127.0.0.1:8200/v1/sys/policies/acl/admin | jq 502{ 503 "request_id": "3f826e5c-70a0-2998-8082-fe34c67c59d1", 504 "lease_id": "", 505 "renewable": false, 506 "lease_duration": 0, 507 "data": { 508 "name": "admin", 509 "policy": "# Manage auth methods broadly across Vault\npath \"auth/*\"\n{\n capabilities = [\"create\", \"read\" ... 510 }, 511 "wrap_info": null, 512 "warnings": null, 513 "auth": null 514} 515``` 516 517### <a name="step4"></a>Step 4: Check capabilities of a token 518 519This step shows how to print out the permitted capabilities of a token on a 520path. This can help verifying what operations are granted based on the policies 521attached to the token. 522 523#### CLI command 524 525The command is: 526 527```shell 528$ vault token capabilities <TOKEN> <PATH> 529``` 530 531**Example:** 532 533First, create a token attached to `admin` policy. 534 535```shell 536$ vault token create -policy="admin" 537Key Value 538--- ----- 539token 2sHGlAHNj36LpqQ2Zevl2Owi 540token_accessor 4G4UIsQOMwifg7vMLqf6QIc3 541token_duration 768h 542token_renewable true 543token_policies ["admin" "default"] 544identity_policies [] 545policies ["admin" "default"] 546``` 547 548Now, fetch the capabilities of this token on the `sys/auth/approle` path. 549 550```plaintext 551$ vault token capabilities 2sHGlAHNj36LpqQ2Zevl2Owi sys/auth/approle 552create, delete, read, sudo, update 553``` 554 555The result should match the policy rule you wrote on the `sys/auth/*` path. You 556can repeat the steps to generate a token for `provisioner` and check its 557capabilities on paths. 558 559In the absence of a token, it returns the capabilities of the current token 560invoking this command. 561 562```shell 563$ vault token capabilities sys/auth/approle 564root 565``` 566 567#### API call using cURL 568 569Use the `sys/capabilities` endpoint. 570 571**Example:** 572 573First, create a token attached to the `admin` policy: 574 575```shell 576$ curl --request POST --header "X-Vault-Token: ..." --data '{ "policies":"admin" }' \ 577 http://127.0.0.1:8200/v1/auth/token/create 578{ 579 "request_id": "bd9b3216-f7e6-610c-4861-38b9112a1821", 580 "lease_id": "", 581 "renewable": false, 582 "lease_duration": 0, 583 "data": null, 584 "wrap_info": null, 585 "warnings": null, 586 "auth": { 587 "client_token": "3xlduc1vGMD7vKeGLyONAxdS", 588 "accessor": "FOoNv0YJSCqtPVCpW03qVeKd", 589 "policies": [ 590 "admin", 591 "default" 592 ], 593 "token_policies": [ 594 "admin", 595 "default" 596 ], 597 "metadata": null, 598 "lease_duration": 2764800, 599 "renewable": true, 600 "entity_id": "" 601 } 602} 603``` 604 605Now, fetch the capabilities of this token on the `sys/auth/approle` path. 606 607```shell 608# Request payload 609$ tee payload.json <<EOF 610{ 611 "token": "3xlduc1vGMD7vKeGLyONAxdS", 612 "path": "sys/auth/approle" 613} 614EOF 615 616$ curl --request POST --header "X-Vault-Token: ..." \ 617 --data @payload.json \ 618 http://127.0.0.1:8200/v1/sys/capabilities | jq 619{ 620 "sys/auth/approle": [ 621 "create", 622 "delete", 623 "read", 624 "sudo", 625 "update" 626 ], 627 "capabilities": [ 628 "create", 629 "delete", 630 "read", 631 "sudo", 632 "update" 633 ], 634 ... 635} 636``` 637 638The result should match the policy rule you wrote on the `sys/auth/*` path. You can 639repeat the steps to generate a token for `provisioner` and check its 640capabilities on paths. 641 642To check the current token's capabilities permitted on a path, use 643the `sys/capabilities-self` endpoint. 644 645```plaintext 646$ curl --request POST --header "X-Vault-Token: ..." \ 647 --data '{"path":"sys/auth/approle"}' \ 648 http://127.0.0.1:8200/v1/sys/capabilities-self 649``` 650 651 652## Next steps 653 654In this guide, you learned how to write policies based on given policy 655requirements. Next, the [AppRole Pull Authentication](/guides/identity/authentication.html) 656guide demonstrates how to associate policies to a role. 657 658To learn about Sentinel policies, refer to the [Sentinel 659Policies](/guides/identity/sentinel.html) guide. 660