Chapter 9 / 28
Understanding Vault Policies
HashiCorp Vault For Beginners6 min read
Vault doesn’t care who you are.
It cares what you can do — and that’s defined by policies.
You’ve already seen this in action: Alice couldn't access secrets until we give her the right policies. But to truly master Vault, you need to get comfortable writing and understanding these policies.
This chapter is your complete guide.
HCL — HashiCorp Configuration Language
Vault policies are written in HCL, a simple, human-readable language also used in Terraform. You can also use JSON, but HCL is more readable and preferred.
Here’s a simple HCL policy:
path "kv/*" {
capabilities = ["read", "list"]
}
You define what path a user can access, and what they can do there.
Anatomy of a Policy Stanza
A single policy stanza looks like this:
path "kv/data/secret" {
capabilities = ["create", "read", "update"]
}
Let’s break that down:
path– The Vault API path this rule applies to.capabilities– What the user is allowed to do at this path.
You can have multiple stanzas in one policy. Each one targets a specific path.
The Wildcards: * and +
These two symbols help match paths dynamically:
| Symbol | Meaning |
|---|---|
* | Wildcard for one level (no slash) |
+ | Wildcard for multiple levels, including slashes |
Example:
path "kv/*" { } # Matches: kv/foo, kv/bar (but not kv/foo/bar)
path "kv/+/app" { } # Matches: kv/foo/app, kv/bar/app, kv/baz/app but not kv/foo/bank
Use + when you're dealing with unknown or deep hierarchies.
Capabilities — What Can You Actually Do?
Vault understands these permissions:
| Capability | Description |
|---|---|
create | Write a new secret where none exists |
update | Modify an existing secret |
read | Read data (like secrets) |
delete | Delete the data |
list | See what keys exist at a path |
sudo | Full access, including overriding ACLs |
deny | Explicitly block access, even if allowed elsewhere |
You can combine them like this
capabilities = ["read", "list"]
How Policy Enforcement Works
When a request comes into Vault:
- Vault checks the identity (token, user, etc.).
- It looks at all policies attached to that identity.
- It determines whether the action on that path is allowed.
If any policy allows the action, it proceeds — unless… An explicit
denyexists — which overrides all allows.
Deny Always Wins
Vault uses default-deny — if a policy doesn’t say something is allowed, it’s denied.
But if you explicitly write deny, it becomes unskippable.
path "kv/secret/*" {
capabilities = ["read"]
}
path "kv/secret/*" {
capabilities = ["deny"]
}
Even if a user has permission for kv/secret/*, the deny for kv/secret/* wins.
This is useful when you want to broadly allow access but block certain sensitive paths.
Deny in Any Policy Blocks Everything
Here’s the key rule:
If any policy attached to a user includes a
denyfor a path, access is denied — even if another policy allows it.
So if you assign both dev-policy and secure-policy to a user, and secure-policy has a deny rule, it takes precedence.
Use deny carefully. It’s a scalpel, not a hammer.
Example Policy: Reader with a Restriction
# Allow read/list on all kv paths
path "kv/+" {
capabilities = ["read", "list"]
}
# Deny access to production secrets
path "kv/production/*" {
capabilities = ["deny"]
}
This allows broad access, except to sensitive areas. Neat and clean.
Summary
- Policies are written in HCL, with stanzas for each path.
- You define what actions users can perform using
capabilities. - Use
*and+to target path patterns. denytrumps everything — even if another policy allows access.- All policies assigned to a user are merged, and the most restrictive one wins.