Vault ACL Policies

Step 1 of 4

Write an ACL policy

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.

First, login with root token.

Click on the command (⮐) will automatically copy it into the terminal and execute it.

vault login root

Before begins, let's check which secrets 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 secrets 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

Create a policy

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

Create a policy via Vault UI

Let's explore the Vault UI.

Click on the Vault UI tab to launch the Vault UI.
Enter root in the Token text field and then click Sign In.
Click the Policies tab on the top menu, and then select Create ACL policy.
Open the admin.hcl file and copy its content, and then paste it into the Policy text field in the UI.
Enter admin in the Name field.
Click Create policy to create a new admin policy.

Verify your policy

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

Execute the following command to 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

Now, 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_policies       ["base" "default"]
identity_policies    []
policies             ["base" "default"]

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

Remember 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. This should FAIL because the base policy only grants create and read . With absence of update permission, this operation fails.

vault kv put secret/training_test password="password1234"

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

Check Token Capabilities

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.

cd <directory>	Change directory
ls	List directory
echo 'contents' > <file>	Write contents to a file
cat <file>	Output contents of file

i	In Command Mode	Change into Insert Mode, you can now insert and edit text in the file
esc	In Insert Mode	Change into Command Mode, you can now execute commands
:wq	In Command Mode	Save and Exit

Welcome!

Vault ACL Policies

Congratulations!

You've completed the scenario!

Scenario Rating

Resources:

Steps