diff --git a/website/source/guides/identity/policies.html.md b/website/source/guides/identity/policies.html.md index 88d5cb3185..cc1716a9bc 100644 --- a/website/source/guides/identity/policies.html.md +++ b/website/source/guides/identity/policies.html.md @@ -104,10 +104,28 @@ path "auth/*" capabilities = ["create", "read", "update", "delete", "list", "sudo"] } -# List, create, update, and delete auth methods +# Create, update, and delete auth methods path "sys/auth/*" { - capabilities = ["create", "read", "update", "delete", "sudo"] + capabilities = ["create", "update", "delete", "sudo"] +} + +# List auth methods +path "sys/auth" +{ + capabilities = ["read"] +} + +# Create and manage ACL policies via CLI +path "sys/policy/*" +{ + capabilities = ["create", "read", "update", "delete", "list", "sudo"] +} + +# Create and manage ACL policies via API +path "sys/policies/acl/*" +{ + capabilities = ["create", "read", "update", "delete", "list", "sudo"] } # To list policies - Step 3 @@ -116,30 +134,6 @@ path "sys/policy" capabilities = ["read"] } -# Create and manage ACL policies broadly across Vault -path "sys/policy/*" -{ - capabilities = ["create", "read", "update", "delete", "list", "sudo"] -} - -# List, create, update, and delete key/value secrets -path "secret/*" -{ - capabilities = ["create", "read", "update", "delete", "list", "sudo"] -} - -# Manage and manage secret engines broadly across Vault. -path "sys/mounts/*" -{ - capabilities = ["create", "read", "update", "delete", "list", "sudo"] -} - -# Read health checks -path "sys/health" -{ - capabilities = ["read", "sudo"] -} - # To perform Step 4 path "sys/capabilities" { @@ -151,6 +145,30 @@ path "sys/capabilities-self" { capabilities = ["create", "update"] } + +# List, create, update, and delete key/value secrets +path "secret/*" +{ + capabilities = ["create", "read", "update", "delete", "list", "sudo"] +} + +# Manage secret engines broadly across Vault +path "sys/mounts/*" +{ + capabilities = ["create", "read", "update", "delete", "list", "sudo"] +} + +# List existing secret engines +path "sys/mounts" +{ + capabilities = ["read"] +} + +# Read health checks +path "sys/health" +{ + capabilities = ["read", "sudo"] +} ``` @@ -208,8 +226,8 @@ providing bespoke support to Vault users. `admin` must be able to: -- Mount and manage auth methods broadly across Vault -- Mount and manage secret engines broadly across Vault +- Enable and manage auth methods broadly across Vault +- Manage the key/value secret engines at `secret/` path - Create and manage ACL policies broadly across Vault - Read system health check @@ -219,8 +237,8 @@ secret engine for a new Vault user to access and write secrets. `provisioner` must be able to: -- Mount and manage auth methods -- Mount and manage secret engines +- Enable and manage auth methods +- Manage the key/value secret engines at `secret/` path - Create and manage ACL policies @@ -237,37 +255,49 @@ path "auth/*" capabilities = ["create", "read", "update", "delete", "list", "sudo"] } -# List, create, update, and delete auth methods +# Create, update, and delete auth methods path "sys/auth/*" { - capabilities = ["create", "read", "update", "delete", "sudo"] + capabilities = ["create", "update", "delete", "sudo"] } -# List existing policies +# List auth methods +path "sys/auth" +{ + capabilities = ["read"] +} + +# List existing policies via CLI path "sys/policy" { capabilities = ["read"] } -# Create and manage ACL policies broadly across Vault +# Create and manage ACL policies via CLI path "sys/policy/*" { capabilities = ["create", "read", "update", "delete", "list", "sudo"] } +# Create and manage ACL policies via API +path "sys/policies/acl/*" +{ + capabilities = ["create", "read", "update", "delete", "list", "sudo"] +} + # List, create, update, and delete key/value secrets path "secret/*" { capabilities = ["create", "read", "update", "delete", "list", "sudo"] } -# Manage and manage secret engines broadly across Vault. +# Manage secret engines broadly across Vault path "sys/mounts/*" { capabilities = ["create", "read", "update", "delete", "list", "sudo"] } -# List existing secret engines. +# List existing secret engines path "sys/mounts" { capabilities = ["read"] @@ -291,22 +321,34 @@ path "auth/*" capabilities = ["create", "read", "update", "delete", "list", "sudo"] } -# List, create, update, and delete auth methods +# Create, update, and delete auth methods path "sys/auth/*" { - capabilities = ["create", "read", "update", "delete", "sudo"] + capabilities = ["create", "update", "delete", "sudo"] } -# List existing policies +# List auth methods +path "sys/auth" +{ + capabilities = ["read"] +} + +# List existing policies via CLI path "sys/policy" { capabilities = ["read"] } -# Create and manage ACL policies +# Create and manage ACL policies via CLI path "sys/policy/*" { - capabilities = ["create", "read", "update", "delete", "list"] + capabilities = ["create", "read", "update", "delete", "list", "sudo"] +} + +# Create and manage ACL policies via API +path "sys/policies/acl/*" +{ + capabilities = ["create", "read", "update", "delete", "list", "sudo"] } # List, create, update, and delete key/value secrets @@ -343,51 +385,57 @@ passing your modified policy (`*.hcl`). #### API call using cURL -To create a policy, use the `/sys/policy` endpoint: +To create a policy, use the +[`sys/policies/acl`](/api/system/policies.html#create-update-acl-policy) +endpoint: ```shell $ curl --header "X-Vault-Token: " \ --request PUT \ --data \ - /v1/sys/policy/ + /v1/sys/policies/acl/ ``` Where `` is your valid token, and `` includes the policy name and stringified policy. +-> **NOTE:** To create ACL policies, you can use the +[`sys/policy`](/api/system/policy.html) endpoint as well. + **Example:** -Now, create `admin` and `provisioner` policies: - ```shell -# Create admin policy -$ curl --request PUT --header "X-Vault-Token: ..." --data @admin-payload.json \ - http://127.0.0.1:8200/v1/sys/policy/admin - -$ cat admin-payload.json +# Create the API request payload. Use stringified policy expression. +$ tee admin-payload.json < NOTE: You can also use the `/sys/policies` endpoint which is used to manage -ACL, RGP, and EGP policies in Vault (RGP and EGP policies are enterprise-only -features). To list policies, invoke the `/sys/policies/acl` endpoint. - **NOTE:** To update an existing policy, simply re-run the same command by passing your modified policy in the request payload (`*.json`). - ### Step 3: View existing policies Make sure that you see the policies you created in [Step 2](#step2). @@ -433,37 +481,43 @@ path "sys/policy/*" #### API call using cURL -To list existing ACL policies, use the `/sys/policy` endpoint. +To list existing ACL policies, use the `sys/policies/acl` endpoint. ```shell -$ curl --request LIST --header "X-Vault-Token: ..." http://127.0.0.1:8200/v1/sys/policy | jq +$ curl --request LIST --header "X-Vault-Token: ..." http://127.0.0.1:8200/v1/sys/policies/acl | jq ``` To read a specific policy, the endpoint path should be -`/sys/policy/`. +`sys/policies/acl/`. + +-> **NOTE:** To read existing ACL policies, you can use the `sys/policy` +endpoint as well. **Example:** -Read the admin policy: - -```plaintext -$ curl --request GET --header "X-Vault-Token: ..." http://127.0.0.1:8200/v1/sys/policy/admin | jq +```shell +# Read the admin policy +$ curl --header "X-Vault-Token: ..." http://127.0.0.1:8200/v1/sys/policies/acl/admin | jq { - "name": "admin", - "rules": "# Mount and manage auth methods broadly across Vault\npath \"auth/*\"\n{\n ...", - "request_id": "e8151bf3-8136-fef9-428b-1506042350cf", + "request_id": "3f826e5c-70a0-2998-8082-fe34c67c59d1", "lease_id": "", "renewable": false, "lease_duration": 0, "data": { - ... + "name": "admin", + "policy": "# Manage auth methods broadly across Vault\npath \"auth/*\"\n{\n capabilities = [\"create\", \"read\" ... + }, + "wrap_info": null, + "warnings": null, + "auth": null +} ``` ### Step 4: Check capabilities of a token -Use the `/sys/capabilities` endpoint to fetch the capabilities of a token on a -given path. This helps to verify what operations are granted based on the -policies attached to the token. +This step shows how to print out the permitted capabilities of a token on a +path. This can help verifying what operations are granted based on the policies +attached to the token. #### CLI command @@ -475,37 +529,38 @@ $ vault token capabilities **Example:** -First, create a token attached to `admin` policy: +First, create a token attached to `admin` policy. ```shell $ vault token create -policy="admin" -Key Value ---- ----- -token 79ecdd41-9bac-1ac7-1ee4-99fbce796221 -token_accessor 39b5e8b5-7bbf-6c6d-c536-ba79d3a80dd5 -token_duration 768h0m0s -token_renewable true -token_policies [admin default] +Key Value +--- ----- +token 2sHGlAHNj36LpqQ2Zevl2Owi +token_accessor 4G4UIsQOMwifg7vMLqf6QIc3 +token_duration 768h +token_renewable true +token_policies ["admin" "default"] +identity_policies [] +policies ["admin" "default"] ``` Now, fetch the capabilities of this token on the `sys/auth/approle` path. ```plaintext -$ vault token capabilities 79ecdd41-9bac-1ac7-1ee4-99fbce796221 sys/auth/approle -Capabilities: [create delete read sudo update] +$ vault token capabilities 2sHGlAHNj36LpqQ2Zevl2Owi sys/auth/approle +create, delete, read, sudo, update ``` -The result should match the policy rule you wrote on the `sys/auth/*` path. You can -repeat the steps to generate a token for `provisioner` and check its +The result should match the policy rule you wrote on the `sys/auth/*` path. You +can repeat the steps to generate a token for `provisioner` and check its capabilities on paths. - -In the absence of a token, it returns the capabilities of the current token invoking this -command. +In the absence of a token, it returns the capabilities of the current token +invoking this command. ```shell $ vault token capabilities sys/auth/approle -Capabilities: [root] +root ``` #### API call using cURL @@ -520,24 +575,29 @@ First, create a token attached to the `admin` policy: $ curl --request POST --header "X-Vault-Token: ..." --data '{ "policies":"admin" }' \ http://127.0.0.1:8200/v1/auth/token/create { - "request_id": "870ef38c-1401-7beb-633c-ff09cca3db68", - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": null, - "wrap_info": null, - "warnings": null, - "auth": { - "client_token": "9f3a9fbb-4e1a-87c3-9d4d-ee4d96d40af1", - "accessor": "f8a269c0-153a-c1ea-ae97-e7e964814392", - "policies": [ - "root" - ], - "metadata": null, - "lease_duration": 0, + "request_id": "bd9b3216-f7e6-610c-4861-38b9112a1821", + "lease_id": "", "renewable": false, - "entity_id": "" - } + "lease_duration": 0, + "data": null, + "wrap_info": null, + "warnings": null, + "auth": { + "client_token": "3xlduc1vGMD7vKeGLyONAxdS", + "accessor": "FOoNv0YJSCqtPVCpW03qVeKd", + "policies": [ + "admin", + "default" + ], + "token_policies": [ + "admin", + "default" + ], + "metadata": null, + "lease_duration": 2764800, + "renewable": true, + "entity_id": "" + } } ``` @@ -545,15 +605,24 @@ Now, fetch the capabilities of this token on the `sys/auth/approle` path. ```shell # Request payload -$ cat payload.json +$ tee payload.json <