From 9df839e44688df2a4fade67147a5bd1b6e9d99e8 Mon Sep 17 00:00:00 2001 From: Yoko Hyakuna Date: Tue, 23 Jan 2018 15:43:07 -0800 Subject: [PATCH] More detailed descriptions were added --- .../assets/images/vault-approle-workflow.png | 4 +- .../assets/images/vault-policy-workflow.png | 3 + website/source/guides/authentication.html.md | 134 +++-- website/source/guides/dynamic-secrets.html.md | 50 +- website/source/guides/policies.html.md | 478 ++++++++++++------ 5 files changed, 451 insertions(+), 218 deletions(-) create mode 100644 website/source/assets/images/vault-policy-workflow.png diff --git a/website/source/assets/images/vault-approle-workflow.png b/website/source/assets/images/vault-approle-workflow.png index 238b58cc9..5f377455c 100644 --- a/website/source/assets/images/vault-approle-workflow.png +++ b/website/source/assets/images/vault-approle-workflow.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:338c562a4d323df2b19c575006f1be7a1056fa4877fe526a887594d35f3c182c -size 53140 +oid sha256:278d15ee12965e203b68245ffa9ffb1ab65ac52f7d5629e9882ccf9e7545accb +size 59048 diff --git a/website/source/assets/images/vault-policy-workflow.png b/website/source/assets/images/vault-policy-workflow.png new file mode 100644 index 000000000..6b0189598 --- /dev/null +++ b/website/source/assets/images/vault-policy-workflow.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:cd0bc98ee86f54908deef32c8ebc46f05e75b28da4c407fb716d94b727f24595 +size 10789 diff --git a/website/source/guides/authentication.html.md b/website/source/guides/authentication.html.md index 537a49fb1..cac5d24b7 100644 --- a/website/source/guides/authentication.html.md +++ b/website/source/guides/authentication.html.md @@ -133,8 +133,9 @@ The basic workflow is: ![AppRole auth backend workflow](assets/images/vault-approle-workflow.png) > For the purpose of introducing the basics of AppRole, this guide walks you -> through a very simple scenario involving only two personas. Please refer to -> the [Advanced Features](#advanced-features) section for further discussions. +> through a very simple scenario involving only two personas (admin and app). +> Please refer to the [Advanced Features](#advanced-features) section for +> further discussions after completing the following steps. In this guide, you are going to perform the following steps: @@ -155,13 +156,15 @@ Like many other auth backends, AppRole must be enabled before it can be used. #### CLI command +Enable `approle` auth backend by executing the following command: + ```shell $ vault auth-enable approle ``` #### API call using cURL -Enable `approle` auth backend using `/sys/auth` endpoint: +Enable `approle` auth backend by mounting its endpoint at `/sys/auth/approle`: ```shell $ curl --header "X-Vault-Token: " \ @@ -191,7 +194,7 @@ at the `sys/auth/approle` endpoint. When you enabled AppRole auth backend, it gets mounted at the **`/auth/approle`** path. In this example, you are going to create a role for -**`app`** persona (Jenkins) . +**`app`** persona (`jenkins` in our scenario). The scenario in this guide requires the `app` to have the following policy (`jenkins-pol.hcl`): @@ -219,12 +222,17 @@ $ vault policy-write jenkins jenkins-pol.hcl The command to create a new AppRole: ```shell -$ vault write auth/approle/role/ [args] +$ vault write auth/approle/role/ [parameters] ``` -There are a number of [parameters](/api/auth/approle/index.html) that you can -set. Most importantly, you want to specify the policies when you create a role. - +> There are a number of +> [parameters](/api/auth/approle/index.html#create-new-approle) that you can set +> on a role. If you want to limit the use of the generated secret ID, set +> `secret_id_num_uses` or `secret_id_ttl` parameter values. Similarly, you can +> specify `token_num_uses` and `token_ttl`. You may never want the app token to +> expire. In such a case, specify the `period` so that the token generated by +> this AppRole is a periodic token. To learn more about periodic token, refer to +> the [Tokens and Leases](/guifes/lease.html#step4) guide. **Example:** @@ -272,11 +280,7 @@ $ cat payload.json } ``` -There are a number of [parameters](/api/auth/approle/index.html) that you can -set. Most importantly, you want to specify the policies when you create a role. - -You are going to create a role operates in [**pull** mode](/docs/auth/approle.html) -in this example. +Now, you are ready to create a role. **Example:** @@ -288,9 +292,31 @@ mode](/docs/auth/approle.html).) $ curl --header "X-Vault-Token: ..." --request POST \ --data '{"policies":"jenkins"}' \ https://vault.rocks/v1/auth/approle/role/jenkins +``` + +> There are a number of +> [parameters](/api/auth/approle/index.html#create-new-approle) that you can set +> on a role. If you want to limit the use of the generated secret ID, set +> `secret_id_num_uses` or `secret_id_ttl` parameter values. Similarly, you can +> specify `token_num_uses` and `token_ttl`. You may never want the app token to +> expire. In such a case, specify the `period` so that the token generated by +> this AppRole is a periodic token. To learn more about periodic token, refer to +> the [Tokens and Leases](/guifes/lease.html#step4) guide. -# Read the jenkins role +**NOTE:** To attach multiple policies, pass the policy names as a comma +separated string. + +```shell +$ curl --header "X-Vault-Token:..." + --request POST \ + --data '{"policies":"jenkins,anotherpolicy"}' \ + https://vault.rocks/v1/auth/approle/role/jenkins +```` + +To read the jenkins role you just created: + +```shell $ curl --header "X-Vault-Token: ..." --request GET \ https://vault.rocks/v1/auth/approle/role/jenkins | jq { @@ -317,44 +343,37 @@ $ curl --header "X-Vault-Token: ..." --request GET \ } ``` -**NOTE:** To attach multiple policies, pass the policy names as a comma -separated string. - -```shell -$ curl --header "X-Vault-Token:..." - --request POST \ - --data '{"policies":"jenkins,anotherpolicy"}' \ - https://vault.rocks/v1/auth/approle/role/jenkins -```` ### Step 3: Get Role ID and Secret ID (**Persona:** admin) -Think of **Role ID** and **Secret ID** as the username and password which apps -use to authenticate with Vault. +**Role ID** and **Secret ID** are like username and password which a machine or +app uses to authenticate. Since the example created a `jenkins` role which operates in pull mode, Vault -will generate the Secret ID. Similarly to tokens, you can set properties such as -usage-limit, TTLs, and expirations on the secret IDs. +will generate the Secret ID. You can set properties such as usage-limit, TTLs, +and expirations on the secret IDs to control its lifecycle. #### CLI command Now, you need to fetch the Role ID and Secret ID of a role. -To read role ID: +To read the Role ID: ```shell $ vault read auth/approle/role//role-id ``` -To generate a new secret ID: +To generate a new Secret ID: ```shell $ vault write -f auth/approle/role//secret-id ``` -The `write` operation is equivalent to `POST` or `PUT` HTTP verbs. The `-f` flag -forces the `write` operation to continue without any data values specified. +NOTE: The `-f` flag forces the `write` operation to continue without any data +values specified. Alternatively, you can set +[parameters](/api/auth/approle/index.html#generate-new-secret-id) such as +`cidr_list`. **Example:** @@ -371,10 +390,13 @@ $ vault write -f auth/approle/role/jenkins/secret-id secret_id_accessor a240a31f-270a-4765-64bd-94ba1f65703c ``` +If you specified `secret_id_ttl`, `secret_id_num_uses`, or `bound_cidr_list` on +the role in [Step 2](#step2), the generated secret ID carries out the conditions. + #### API call using cURL -To read role ID: +To read the Role ID: ```shell $ curl --header "X-Vault-Token:..." \ @@ -382,14 +404,19 @@ $ curl --header "X-Vault-Token:..." \ /v1/auth/approle/role//role-id ``` -To generate a new secret ID: +To generate a new Secret ID: ```shell $ curl --header "X-Vault-Token:..." \ --request POST \ + --data /v1/auth/approle/role//secret-id ``` +You can pass +[parameters](/api/auth/approle/index.html#generate-new-secret-id) in the request +payload, or invoke the API with empty payload. + **Example:** ```shell @@ -400,16 +427,16 @@ $ curl --header "X-Vault-Token:..." --request POST \ https://vault.rocks/v1/auth/approle/role/jenkins/secret-id | jq ``` -The above example to generate a new Secret ID does not have any payload. -Optionally, you can pass -[parameters](/api/auth/approle/index.html#generate-new-secret-id) in the request -payload. +If you specified `secret_id_ttl`, `secret_id_num_uses`, or `bound_cidr_list` on +the role in [Step 2](#step2), the generated secret ID carries out the conditions. + + ### Step 4: Login with Role ID & Secret ID (**Persona:** app) -The client (in this case, Jenkins) uses the role ID and secret ID to -authenticate with Vault. If the expecting client did not receive the role ID and +The client (in this case, Jenkins) uses the role ID and secret ID passed by the +admin to authenticate with Vault. If Jenkins did not receive the role ID and/or secret ID, the admin needs to investigate. -> Refer to the [Advanced Features](#advanced-features) section for further @@ -436,7 +463,7 @@ $ vault write auth/approle/login role_id="675a50e7-cfe0-be76-e35f-49ec009731ea" token_meta_role_name "jenkins" ``` -Now you have a client token with `default` and `jenkins` policies attached. +Now you have a **client token** with `default` and `jenkins` policies attached. #### API call using cURL @@ -447,13 +474,13 @@ in the request payload. **Example:** ```plaintext -$ cat jenkins.json +$ cat payload.json { "role_id": "675a50e7-cfe0-be76-e35f-49ec009731ea", "secret_id": "ed0a642f-2acf-c2da-232f-1b21300d5f29" } -$ curl --request POST --data @jenkins.json https://vault.rocks/v1/auth/approle/login | jq +$ curl --request POST --data @payload.json https://vault.rocks/v1/auth/approle/login | jq { "request_id": "fccae32b-1e6a-9a9c-7666-f5cb07805c1e", "lease_id": "", @@ -479,14 +506,14 @@ $ curl --request POST --data @jenkins.json https://vault.rocks/v1/auth/approle/l } ``` -Now you have a client token with `default` and `jenkins` policies attached. +Now you have a **client token** with `default` and `jenkins` policies attached. ### Step 5: Read secrets using the AppRole token (**Persona:** app) -Once the client acquired the token, the future requests can be made using -that token. +Once receiving a token from Vault, the client can make future requests using +this token. #### CLI command @@ -576,23 +603,22 @@ This time, it should return the values you just created. ## Advanced Features The Role ID is equivalent to a username, and Secret ID is the corresponding -password. The app needs both to login with Vault. Naturally, the next question +password. The app needs both to log in with Vault. Naturally, the next question becomes how to deliver those values to the expecting client. -Common solution involves **three personas** instead of two: `admin`, `app`, and -`trusted entity`. Furthermore, the Role ID and Secret ID are delivered to the -client separately by the `trusted entity`. - -![AppRole auth backend workflow](assets/images/vault-approle-workflow2.png) +A common solution involves **three personas** instead of two: `admin`, `app`, and +`trusted entity`. The `trusted entity` delivers the Role ID and Secret ID to the +client by separate means. For example, Terraform injects the Role ID onto the virtual machine. When the app runs on the virtual machine, the Role ID already exists on the virtual machine. +![AppRole auth backend workflow](assets/images/vault-approle-workflow2.png) + Secret ID is like a password. To keep the Secret ID confidential, use [**response wrapping**](/docs/concepts/response-wrapping.html) so that the only -expected client can unwrap the Secret ID. The `admin` user don't even see the -generated token. +expected client can unwrap the Secret ID. In [Step 3](#step3), you executed the following command to retrieve the Secret ID: @@ -627,7 +653,7 @@ secret_id 575f23e4-01ad-25f7-2661-9c9bdbb1cf81 secret_id_accessor 7d8a40b7-a6fd-a634-579b-b7d673ff86fb ``` -To retrieve the Secret ID alone, you can use `jq` as follow: +NOTE: To retrieve the Secret ID alone, you can use `jq` as follow: ```shell $ VAULT_TOKEN=2577044d-cf86-a065-e28f-e2a14ea6eaf7 vault unwrap -format=json | jq -r ".data.secret_id" diff --git a/website/source/guides/dynamic-secrets.html.md b/website/source/guides/dynamic-secrets.html.md index eb6480e24..bd9e302df 100644 --- a/website/source/guides/dynamic-secrets.html.md +++ b/website/source/guides/dynamic-secrets.html.md @@ -32,7 +32,7 @@ you through the generation of dynamic AWS credentials. The end-to-end scenario described in this guide involves two personas: - **`admin`** with privileged permissions to configure secret backends -- **`app`** is the requester of credentials +- **`apps`** reads the secrets from Vault ## Challenge @@ -147,10 +147,21 @@ must be mounted. #### CLI command +To mount a database backend: + ```shell -vault mount database +$ vault mount ``` +**Example:** + +```shell +$ vault mount database +``` + +**NOTE:** In this guide, the database backend is mounted at the `/database path` in +Vault. However, it is possible to mount your secret backends at any location. + #### API call using cURL Mount `database` secret backend using `/sys/mounts` endpoint: @@ -159,7 +170,7 @@ Mount `database` secret backend using `/sys/mounts` endpoint: $ curl --header "X-Vault-Token: " \ --request POST \ --data \ - /v1/sys/mounts/database + /v1/sys/mounts/ ``` Where `` is your valid token, and `` holds [configuration @@ -177,6 +188,8 @@ $ curl --header "X-Vault-Token: ..." \ https://$ vault.rocks/v1/sys/mounts/database ``` +**NOTE:** It is possible to mount your database secret backends at any location. + ### Step 2: Configure PostgreSQL backend (**Persona:** admin) @@ -212,10 +225,10 @@ $ vault write database/config/postgresql plugin_name=postgresql-database-plugin **Example:** ```shell -$ curl --header "X-Vault-Token: ..." --request POST --data @postgres-config.json \ +$ curl --header "X-Vault-Token: ..." --request POST --data @payload.json \ https://vault.rocks/v1/database/config/postgresql -$ cat postgres-config.json +$ cat payload.json { "plugin_name": "postgresql-database-plugin", "allowed_roles": "readonly", @@ -249,7 +262,7 @@ if Vault is offline or unable to communicate with it. **Example:** -```plaintext +```shell $ vault write database/roles/readonly db_name=postgresql creation_statements=@readonly.sql \ default_ttl=1h max_ttl=24h ``` @@ -263,10 +276,10 @@ statement is passed as the role creation statement. **Example:** ```shell -$ curl --header "X-Vault-Token: ..." --request POST --data @role-payload.json \ +$ curl --header "X-Vault-Token: ..." --request POST --data @payload.json \ https://vault.rocks/v1/database/roles/readonly -$ cat role-payload.json +$ cat payload.json { "db_name": "postgres", "creation_statements": "CREATE ROLE '{{name}}' WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}'; @@ -281,9 +294,9 @@ the `role-payload.json`. ### Step 4: Request PostgreSQL credentials -(**Persona:** app) +(**Persona:** apps) -Now, you are switching to [`app` persona](#personas). To get a new set of +Now, you are switching to [`apps` persona](#personas). To get a new set of PostgreSQL credentials, the client app needs to be able to **read** from the `readonly` role endpoint. Therefore, the app's token must have a policy granting the read permission. @@ -300,14 +313,16 @@ path "database/creds/readonly" { #### CLI command First create an `apps` policy, and generate a token so that you can authenticate -as an `app` persona. +as an `apps` persona. **Example:** ```shell +# Create "apps" policy $ vault policy-write apps apps-policy.hcl Policy 'apps' written. +# Create a new token with app policy $ vault token-create -policy="apps" Key Value --- ----- @@ -324,12 +339,14 @@ Use the returned token to perform the remaining. demonstrates more sophisticated way of generating a token for your apps. ```shell +# Authenticate with Vault using the generated token first $ vault auth e4bdf7dc-cbbf-1bb1-c06c-6a4f9a826cf2 Successfully authenticated! You are now logged in. token: e4bdf7dc-cbbf-1bb1-c06c-6a4f9a826cf2 token_duration: 2764277 token_policies: [apps default] +# Invoke the vault command $ vault read database/creds/readonly Key Value @@ -352,15 +369,18 @@ First create an `apps` policy, and generate a token so that you can authenticate as an `app` persona. ```shell -$ curl --header "X-Vault-Token: ..." --request PUT \ - --data @payload.json \ - https://vault.rocks/v1/sys/policy/apps - +# Payload to pass in the API call $ cat payload.json { "policy": "path \"database/creds/readonly\" {capabilities = [ \"read\" ]}" } +# Create "apps" policy +$ curl --header "X-Vault-Token: ..." --request PUT \ + --data @payload.json \ + https://vault.rocks/v1/sys/policy/apps + +# Generate a new token with apps policy $ curl --header "X-Vault-Token: ..." --request POST \ --data '{"policies": ["apps"]}' \ https://vault.rocks/v1/auth/token/create | jq diff --git a/website/source/guides/policies.html.md b/website/source/guides/policies.html.md index 4d28be37f..576155e86 100644 --- a/website/source/guides/policies.html.md +++ b/website/source/guides/policies.html.md @@ -8,8 +8,8 @@ description: |- # Policies -Use policy to govern the behavior of clients by specifying the access privilege -(_authorization_). +In Vault, use policies to govern the behavior of clients by specifying the +access privilege (_authorization_). When you first initialize Vault, the [**`root`**](/docs/concepts/policies.html#root-policy) policy gets created by @@ -47,11 +47,22 @@ valid input. 10 minutes +## Personas + +The scenario described in this guide introduces the following personas: + +- **`root`** sets up initial policies for `admin` +- **`admin`** is empowered with managing a Vault infrastructure for a team or +organizations +- **`provisioner`** configures secret backends as well as creating policies for +client apps + + ## Challenge -Since Vault centrally secure, store, and access control secrets across distributed -infrastructure and applications, it is critical to control permissions before -any user or machine can gain access. +Since Vault centrally secure, store, and access control secrets across +distributed infrastructure and applications, it is critical to control +permissions before any user or machine can gain access. ## Solution @@ -68,26 +79,64 @@ Vault. To perform the tasks described in this guide, you need to have a Vault environment. Refer to the [Getting -Started](/intro/getting-started/install.html) guide to install Vault. - -Make sure that your Vault server has been [initialized and +Started](/intro/getting-started/install.html) guide to install Vault. Make sure +that your Vault server has been [initialized and unsealed](/intro/getting-started/deploy.html). +### Policy requirements + +Since this guide demonstrates the creation of an **`admin`** policy, log in with +**`root`** token if possible. Otherwise, make sure that you have the following +permissions: + +```shell +# To perform Step 2 & 3 +path "sys/policy/*" +{ + capabilities = ["create", "read", "update", "delete", "list"] +} + +# To perform Step 4 +path "auth/token/create" +{ + capabilities = ["create", "update"] +} + +# To perform Step 4 +path "sys/capabilities" +{ + capabilities = ["create", "update"] +} + +# To perform Step 4 +path "sys/capabilities-self" +{ + capabilities = ["create", "update"] +} +``` + + ## Steps +The basic workflow of creating policies is: + +![Policy Creation Workflow](/assets/images/vault-policy-workflow.png) + This guide demonstrates basic policy authoring and management tasks. -1. [Write ACL policies](#step1) -2. [View existing policies](#step2) -3. [Check capabilities of a token](#step3) +1. [Write ACL policies in HCL format](#step1) +2. [Create policies](#step2) +3. [View existing policies](#step3) +4. [Check capabilities of a token](#step4) -### Step 1: Write ACL policies +### Step 1: Write ACL policies in HCL format -ACL policies are defined for each path: +Remember, empty policy grants **no permission** in the system. Therefore, ACL +policies are defined for each path. -```plaintext -path "" { +```shell +path "" { capabilities = [ "" ] } ``` @@ -96,7 +145,7 @@ path "" { namespacing. For example, "`secret/training_*`" grants permissions on any path starts with "`secret/training_`" (e.g. `secret/training_vault`). -Define one or more capabilities on each path to control operations that are +Define one or more [capabilities](/docs/concepts/policies.html#capabilities) on each path to control operations that are permitted. | Capability | Associated HTTP verbs | @@ -110,73 +159,127 @@ permitted. #### Policy requirements -First step in writing policies is to gather policy requirements. As an exercise, -assume that the following are the policy requirements defined for `developers` -and `devops`. +First step in creating policies is to **gather policy requirements**. -Developers must be able to: +**Example:** -- Perform all operations on `secret/apps/*` path -- Obtain AWS credentials for `devops` role -- Obtain database credentials for `devops` role +**`admin`** is a type of user empowered with managing a Vault infrastructure for +a team or organizations. Empowered with sudo, the Administrator is focused on +configuring and maintaining the health of Vault cluster(s) as well as +providing bespoke support to Vault users. -DevOps must be able to: +`admin` must be able to: -- View and manage leases +- Mount and manage auth backends broadly across Vault +- Mount and manage secret backends broadly across Vault +- Create and manage ACL policies broadly across Vault +- Read system health check + +**`provisioner`** is a type of user or service that will be used by an automated +tool (e.g. Terraform) to provision and configure a namespace within a Vault +secret backend for a new Vault user to access and write secrets. + +`provisioner` must be able to: + +- Mount and manage auth backends - Mount and manage secret backends +- Create and manage ACL policies -#### Example policy for Developers -`dev-pol.hcl` +Now, you are ready to author policies to fulfill the requirements. + +#### Example policy for admin + +`admin-policy.hcl` ```shell -# Full permissions on secret/apps/* path -path "secret/apps/*" { - capabilities = ["create", "read", "update", "delete", "list"] +# Manage auth backends broadly across Vault +path "auth/*" +{ + capabilities = ["create", "read", "update", "delete", "list", "sudo"] } -# Read new credentials from aws secret backend -path "aws/creds/devops" { - capabilities = ["read"] +# List, create, update, and delete auth backends +path "sys/auth/*" +{ + capabilities = ["create", "read", "update", "delete", "sudo"] } -# Read new credentials from database secret backend -path "database/creds/devops" { - 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 backends broadly across Vault. +path "sys/mounts/*" +{ + capabilities = ["create", "read", "update", "delete", "list", "sudo"] +} + +# Read health checks +path "sys/health" +{ + capabilities = ["read", "sudo"] } ``` -#### Example policy for DevOps +#### Example policy for provisioner -`devops-pol.hcl` +`provisioner-policy.hcl` ```shell -# Permissions to manage leases -path "sys/leases/*" { +# Manage auth backends broadly across Vault +path "auth/*" +{ capabilities = ["create", "read", "update", "delete", "list"] } -# Permissions to create and manage secret backends -path "sys/mounts/*" { +# List, create, update, and delete auth backends +path "sys/auth/*" +{ + capabilities = ["create", "read", "update", "delete"] +} + +# Create and manage ACL policies +path "sys/policy/*" +{ capabilities = ["create", "read", "update", "delete", "list"] } -# Move already mounted backend to a new endpoint -path "sys/remount/*" { - capabilities = ["create", "update"] +# List, create, update, and delete key/value secrets +path "secret/*" +{ + capabilities = ["create", "read", "update", "delete", "list"] } ``` -Once the ACL policies are written, create policies. +### Step 2: Create policies + +Now, create `admin` and `provisioner` policies in Vault. #### CLI command -Create new ACL policies: +To create policies: ```shell -$ vault write dev-pol dev-pol.hcl +$ vault policy-write +``` -$ vault write devops-pol devops-pol.hcl +**Example:** + +```shell +# Create admin policy +$ vault write admin admin-policy.hcl + +# Create provisioner policy +$ vault write provisioner provisioner-policy.hcl ``` **NOTE:** To update an existing policy, simply re-run the same command by @@ -184,122 +287,125 @@ passing your modified policy (`*.hcl`). #### API call using cURL -Before begin, create the following environment variables for your convenience: +To create a policy, use `/sys/policy` endpoint: -- **VAULT_ADDR** is set to your Vault server address -- **VAULT_TOKEN** is set to your Vault token +```shell +$ curl --header "X-Vault-Token: " \ + --request PUT \ + --data \ + /v1/sys/policy/ +``` + +Where `` is your valid token, and `` includes policy name and +stringfied policy. **Example:** -```plaintext -$ export VAULT_ADDR=http://127.0.0.1:8201 - -$ export VAULT_TOKEN=0c4d13ba-9f5b-475e-faf2-8f39b28263a5 -``` - -Now, create new ACL policies using API: +Now, create `admin` and `provisioner` policies: ```shell -# Create dev-pol policy -$ curl -X PUT -H "X-Vault-Token: $VAULT_TOKEN" -d @dev-payload.json \ - $VAULT_ADDR/v1/sys/policies/acl/dev-pol +# Create admin policy +$ curl --request PUT --header "X-Vault-Token: ..." --data @admin-payload.json \ + https://vault.rocks/v1/sys/policy/admin -$ cat dev-payload.json +$ cat admin-payload.json { - "policy": "path \"secret/apps/*\" { capabilities = [\"create\", \"read\", \"update\" ... }" + "policy": "path \"auth/*\" { capabilities = [\"create\", \"read\", \"update\", ... }" } -# Create devops-pol policy -$ curl -X PUT -H "X-Vault-Token: $VAULT_TOKEN" -d @devops-payload.json \ - $VAULT_ADDR/v1/sys/policies/acl/devops-pol +# Create provisioner policy +$ curl --request PUT --header "X-Vault-Token: ..." --data @provisioner-payload.json \ + https://vault.rocks/v1/sys/policy/provisioner -$ cat devops-payload.json +$ cat provisioner-payload.json { - "policy": "path \"sys/leases/*\" { capabilities = [\"create\", \"read\", \"update\" ... }" + "policy": "path \"auth/*\" { capabilities = [\"create\", \"read\", \"update\", ... }" } ``` -**NOTE:** To update an existing policy, simply re-run the same command by -passing your modified policy in the request payload (`*.json`). - - - -### Step 2: View existing policies - -Make sure that you see the policies you created in [Step 1](#step1). - -#### CLI command - -The following command lists existing policies: - -```shell -vault policies -``` - -To view a specific policy: - -```shell -vault read sys/policy/ -``` - -**Example:** - -```shell -vault read sys/policy/default - -Key Value ---- ----- -name default -rules # Allow tokens to look up their own properties -path "auth/token/lookup-self" { - capabilities = ["read"] -} - -# Allow tokens to renew themselves -path "auth/token/renew-self" { - capabilities = ["update"] -} - -# Allow tokens to revoke themselves -path "auth/token/revoke-self" { - capabilities = ["update"] -} -... -``` - - -#### API call using cURL - -To list existing ACL policies, use the `/sys/policy` endpoint. - -```plaintext -curl -X LIST -H "X-Vault-Token: $VAULT_TOKEN" $VAULT_ADDR/v1/sys/policy | jq -``` - -> NOTE: You can also use `/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 `/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). + +#### CLI command + +The following command lists existing policies: + +```shell +$ vault policies +``` + +To view a specific policy: + +```shell +$ vault read sys/policy/ +``` + +**Example:** + +```shell +# Read admin policy +$ vault read sys/policy/admin +Key Value +--- ----- +name admin +rules # Mount and manage auth backends broadly across Vault +path "auth/*" +{ + capabilities = ["create", "read", "update", "delete", "list", "sudo"] +} + +path "sys/auth/*" +{ + capabilities = ["create", "read", "update", "delete", "sudo"] +} + +# Create and manage ACL policies broadly across Vault +path "sys/policy/*" +{ + capabilities = ["create", "read", "update", "delete", "list", "sudo"] +} +... +``` + +#### API call using cURL + +To list existing ACL policies, use the `/sys/policy` endpoint. + +```shell +$ curl --request LIST --header "X-Vault-Token: ..." https://vault.rocks/v1/sys/policy | jq +``` + To read a specific policy, the endpoint path should be `/sys/policy/`. **Example:** -```plaintext -curl -X GET -H "X-Vault-Token: $VAULT_TOKEN" $VAULT_ADDR/v1/sys/policy/default | jq +Read the admin policy: +```plaintext +$ curl --request GET --header "X-Vault-Token: ..." https://vault.rocks/v1/sys/policy/admin | jq { - "name": "default", - "rules": "\n# Allow tokens to look up their own properties\npath \"auth/token/lookup-self\" ...", - "request_id": "1379d18d-e5e3-dbd2-8f3a-0e446c016a23", + "name": "admin", + "rules": "# Mount and manage auth backends broadly across Vault\npath \"auth/*\"\n{\n ...", + "request_id": "e8151bf3-8136-fef9-428b-1506042350cf", "lease_id": "", "renewable": false, "lease_duration": 0, + "data": { ... ``` - -### Step 3: Check capabilities of a token +### 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 @@ -310,22 +416,42 @@ policies attached to the token. The command is: ```shell -vault capabilities +$ vault capabilities ``` **Example:** -```plaintext -vault capabilities a59c0d41-8df7-ba8e-477e-9bfb394f28a0 secret/apps +First, create a token attached to `admin` policy: -Capabilities: [create delete list read update] +```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] ``` +Now, fetch the capabilities of this token on `sys/auth/approle` path. + +```plaintext +$ vault capabilities 79ecdd41-9bac-1ac7-1ee4-99fbce796221 sys/auth/approle +Capabilities: [create delete read sudo update] +``` + +The result should match the policy rule you wrote on `sys/auth/*` path. You can +repeat the steps to generate a token for `provisioner` and check its +capabilities on paths. + + In the absence of token, it returns capabilities of current token invoking this command. ```shell -vault capabilities secret/apps +$ vault capabilities sys/auth/approle +Capabilities: [root] ``` #### API call using cURL @@ -334,27 +460,85 @@ Use the `sys/capabilities` endpoint. **Example:** -```plaintext -$ curl -X POST -H "X-Vault-Token: $VAULT_TOKEN" -d @payload.json \ - $VAULT_ADDR/v1/sys/capabilities +First, create a token attached to `admin` policy: -$ cat payload.json +```shell +$ curl --request POST --header "X-Vault-Token: ..." --data '{ "policies":"admin" }' \ + https://vault.rocks/v1/auth/token/create { - "token": "a59c0d41-8df7-ba8e-477e-9bfb394f28a0", - "path": "secret/apps" + "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, + "renewable": false, + "entity_id": "" + } } ``` +Now, fetch the capabilities of this token on `sys/auth/approle` path. + +```shell +# Request payload +$ cat payload.json +{ + "token": "9f3a9fbb-4e1a-87c3-9d4d-ee4d96d40af1", + "path": "sys/auth/approle" +} + +$ curl --request POST --header "X-Vault-Token: ..." --data @payload.json \ + https://vault.rocks/v1/sys/capabilities +{ + "capabilities": [ + "create", + "delete", + "read", + "sudo", + "update" + ], + "request_id": "03f9d5e2-7e8a-4cd3-b9e9-034c058d3d06", + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "capabilities": [ + "create", + "delete", + "read", + "sudo", + "update" + ] + }, + "wrap_info": null, + "warnings": null, + "auth": null +} +``` + +The result should match the policy rule you wrote on `sys/auth/*` path. You can +repeat the steps to generate a token for `provisioner` and check its +capabilities on paths. + To check current token's capabilities permitted on a path, use `sys/capabilities-self` endpoint. ```plaintext -curl -X POST -H "X-Vault-Token: $VAULT_TOKEN" -d '{"path":"secret/apps"}' \ - $VAULT_ADDR/v1/sys/capabilities-self +$ curl --request POST --header "X-Vault-Token: ..." --data '{"path":"sys/auth/approle"}' \ + https://vault.rocks/v1/sys/capabilities-self ``` - ## Next steps In this guide, you learned how to write policies based on given policy