Everything in Vault is path based, and admins write policies to grant or forbid access to certain paths and operations in Vault. Vault operates on a secure by default standard, and as such, an empty policy grants no permissions in the system.

Before begins, let's check which secret engines have been enabled: vault secrets list

The output should look like:

Path          Type         Description
----          ----         -----------
cubbyhole/    cubbyhole    per-token private secret storage
identity/     identity     identity store
secret/       kv           key/value secret storage
sys/          system       system endpoints used for control, policy and debugging

For each of these path, you must write policies to allow any operation against it.

Write a Policy File

You are going to write an ACL policy in HCL format. HCL is JSON compatible; therefore, JSON can be used as completely valid input.

Remember, an empty policy grants no permission in the system. Therefore, ACL policies are defined for each path.

path "<PATH>" {
   capabilities = [ "<LIST_OF_CAPABILITIES>" ]
}

The path can have a wildcard ("*") at the end to allow for any string in its place. For example, "secret/training_*" grants permissions on any path starting with "secret/training_" (e.g. secret/training_vault). To allow wildcard matching for a single directory, use "+". For example, "secret/app/+/stage" would match a path such as "secret/app/release_1.0/stage".

The base.hcl file should be opened in the editor pane. Enter the following policy rules in the editor (the following snippet can be copied into the editor):

path "secret/data/training_*" {
   capabilities = ["create", "read"]
}

path "secret/data/+/apikey" {
   capabilities = ["create", "read", "update", "delete"]
}

Notice that the path has the "splat" operator (training_*) as well as single directory wildcard (+). This is helpful in working with namespace patterns.

This policy grants create and read operations on any path starting with secret/data/training_. Also, permits create, read, update, and delete operations on any path matching the pattern of secret/data/<string>/apikey.

NOTE: When you are working with key/value secret engine v2, the path to write policies would be secret/data/<path> even though the K/V command to the path is secret/<path>. When you are working with v1, the policies should be written against secret/<path>. This is because the API endpoint to invoke K/V v2 is different from v1.

Get help for the vault policy command:

vault policy -h

To view the full list of optional parameters for vault policy write operation, run the following command: vault policy write -h

To clear the screen: clear

Execute the following command to create a policy:

vault policy write base base.hcl

Run the following command to list existing policies:

vault policy list

The list should include the base policy you just created.

The following command displays the policy you just created:

vault policy read base

Optional: Execute the following command to examine the default policy.

vault policy read default

Now, create a token attached to the base policy so that you can test it.

You are going to run the vault token create command. To view the full list of optional parameters for the operation, run the following command:

vault token create -h

To clear the screen: clear

Create a new token, and save the generated token in a file named, token.txt:

vault token create -policy="base" \
    -format=json | jq -r ".auth.client_token" > token.txt

Authenticate with Base Token

Let's login with newly generated token (token.txt). The command is:

vault login $(cat token.txt)

Notice that the base policy is listed.

Key                  Value
---                  -----
token                s.hea9aAZJ8LMPL8Q0BJUEIk94
token_accessor       GypP6CuHkTyVHjlWkduiev2G
token_duration       767h59m50s
token_renewable      true
token_policies       ["base" "default"]
identity_policies    []
policies             ["base" "default"]

NOTE: A built-in policy, default, is attached to all tokens and provides common permissions.

Recall that the base policy only permits CRUD operations on secret/training_* path.

The following command should fail with "permission denied" error since the base policy doesn't define any permission on the secret/apikey path:

vault kv put secret/apikey key="my-api-key"

Now, the following command should execute successfully:

vault kv put secret/training_test password="[email protected]"

The policy was written for the secret/training_* path so that you can write on secret/training_test, secret/training_dev, secret/training_prod, etc.

You should be able to read back the data:

vault kv get secret/training_test

Now, pass a different password value to update it.

vault kv put secret/training_test password="password1234"

This should fail because the base policy only grants create and read . With absence of update permission, this operation fails.

Question

What happens when you try to write data in secret/training_ path?

Will this work? 

Answer

This is going to work.

vault kv put secret/training_ year="2018"

However, this is NOT because the path is a regular expression. Vault's paths use a radix tree, and that "*" can only come at the end. It matches zero or more characters but not because of a regex.

Now, try the following command:

vault kv put secret/team-eng/apikey api_key="123456789"

The path secret/team-eng/apikey matches the secret/<string>/apikey pattern, so the command should execute successfully.

Since the policy allows delete operation, the following command should execute successfully as well:

vault kv delete secret/team-eng/apikey

Log back in with root token:

vault login root

Execute the capabilities command to check permissions on secret/data/training_dev path.

vault token capabilities $(cat token.txt) secret/data/training_dev

Where token.txt contains the generated token with base policy attached.

This lists the capabilities of a token on a path granted by its attached policies (base). When unexpected behavior was encountered, this is an easy method to check the policy for the token.

How about secret/data/splunk/apikey path?

vault token capabilities $(cat token.txt) secret/data/splunk/apikey

Execute the command without a token:

vault token capabilities secret/data/training_dev

With absence of a token, the command checks the capabilities of current token that you are logged in with.