This guide discusses some nuances about working with Vault policies through concrete examples.
Note: The examples shown here are possible because of authentication with a root token. While root tokens are useful in development and other non-production purposes, they should be carefully guarded in production as explained in the Root Tokens documentation. Some of these examples might not be possible for you depending on the capabilities provided by your own token.
Get Current Policies and Their Contents
Which policies are currently available in the Vault instance?
Getting a list of available policies is intuitive enough:
$ vault policy list
default
surfboard_read
root
What are the contents of the surfboard_read
policy? You can learn this by passing the policy name to vault policies
:
$ vault policy read surfboard_read
# Allow reading surfboard secrets
path "secret/surfboards/" {
capabilities = ["list", "read"]
}
Test Policy Capabilities on a Path
Often it can be handy to quickly determine what capabilities a token has for a given Vault path. You can determine this with vault capabilities
.
Here is an example for determining the capabilities of a token created with a tacos_admin policy on the path secret/tacos/
:
$ vault token capabilities s.cDtfMXCly4pStgmQK8q2IbXu secret/tacos/
create, delete, list, read, sudo, update
NOTE: you do not need a leading forward slash when specifying the path.
Policy After the Fact
A policy can be attached to the token after the fact, so long as a token is created with a reference to the policy name, that token will provide capabilities specified by the policy when it exists.
For example consider this sequence of events:
List current policies:
$ vault policy list
default
surfboard_read
root
Create a token with the policy surfboard_read
and the non-existent policy surfboard_write
:
vault token create -policy=surfboard_read -policy=surfboard_write
WARNING! The following warnings were returned from Vault:
* Policy "surfboard_write" does not exist
Key Value
--- -----
token s.nTz7kNiWkv1RpTpBMEQpORyN
token_accessor pGJ3OAU3PWH0M8RAdtRtqWM3
token_duration 50000h
token_renewable true
token_policies ["default" "surfboard_read" "surfboard_write"]
identity_policies []
policies ["default" "surfboard_read" "surfboard_write"]
Note the warning that policy surfboard_write doesn’t exist.
The surfboard_read policy gives read and list capabilities on the path secret/surfboards/
, so we can verify that much:
$ vault token capabilities s.nTz7kNiWkv1RpTpBMEQpORyN secret/surfboards/
list, read
So with that, it would stand to reason that we cannot yet write to secret/surfboards/
, but if we create the surfboard_write
policy that was specified when we created the token, that will change. Here’s the surfboard_write.hcl
policy file contents:
# Allow writing surfboard secrets
path "secret/surfboards/*" {
capabilities = ["list", "read", "create", "update"]
}
Let’s write the policy:
$ vault policy-write surfboard_write surboard_write.hcl
Policy 'surfboard_write' written.
Let’s check what capabilities the token has now against the same path:
$ vault capabilities e7092e39-9d31-ff24-0b7b-f1f50f42ebc6 secret/surfboards/
create, list, read, update
Of course this can be tested further:
$ vault auth s.nTz7kNiWkv1RpTpBMEQpORyN
Successfully authenticated! You are now logged in.
token: s.nTz7kNiWkv1RpTpBMEQpORyN
token_duration: 2764070
token_policies: [default surfboard_read surfboard_write]
$ vault write secret/surfboards/funboard \
key=A0F57D45-21FD-4E99-938C-C209D1B62194
Success! Data written to: secret/surfboards/funboard
Summary
In this article we learned a bit about the basics of working with Vault policies including listing available policies, examining their contents, and testing their capabilities on a given path.
As a bonus, we also learned that a token can be created to use a named policy that does not yet exist, but will assume the policy’s capabilities as soon as one with the specified name is created.