Intekhab Rizvi

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:

SymbolMeaning
*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:

CapabilityDescription
createWrite a new secret where none exists
updateModify an existing secret
readRead data (like secrets)
deleteDelete the data
listSee what keys exist at a path
sudoFull access, including overriding ACLs
denyExplicitly 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:

  1. Vault checks the identity (token, user, etc.).
  2. It looks at all policies attached to that identity.
  3. It determines whether the action on that path is allowed.

If any policy allows the action, it proceeds — unless… An explicit deny exists — 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 deny for 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.
  • deny trumps everything — even if another policy allows access.
  • All policies assigned to a user are merged, and the most restrictive one wins.