Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 36 ยท Policies and Tokens

Vault Policies: Writing Your First ACL Policy

Learn how Vault policies grant access: path rules, the capabilities list, default and root policies, writing HCL, attaching policies and checking them with a tiny evaluator.

Everything in Vault is a path, and nothing is allowed by default. A policy is a small document that says "on this path, these operations are permitted". Tokens carry policies, and every request is checked against them. If no policy mentions the path, the answer is "permission denied". This deny-by-default model is why Vault can safely sit in front of your most sensitive data.

Vault cannot run inside this website. The commands and policy files below are exactly what you would use against a real server. The js examples are small, clearly labelled stand-ins that re-implement the idea so you can experiment in the browser. They are not Vault.

Anatomy of a policy

Policies are written in HCL (or JSON). Each path block names a path and lists the capabilities allowed on it.

HCL
# app-readonly.hcl
path "secret/data/myapp/*" {
  capabilities = ["read", "list"]
}

path "secret/metadata/myapp/*" {
  capabilities = ["list"]
}

The KV version 2 engine stores data under secret/data/... and metadata under secret/metadata/.... This surprises many beginners: the CLI command vault kv get secret/myapp/db talks to the path secret/data/myapp/db, so your policy must use the data form.

The capabilities

Capability HTTP verb Meaning
create POST/PUT Create data at a path that does not exist yet
read GET Read data
update POST/PUT Change existing data
patch PATCH Partially change data (KV v2)
delete DELETE Delete data
list LIST List keys under a path
sudo - Access root-protected paths
deny - Always refuse; beats everything else

create and update are separate on purpose. Many system endpoints are written with update, while KV v2 distinguishes first writes (create) from later ones (update).

Writing and attaching a policy

Terminal
vault policy write app-readonly app-readonly.hcl
vault policy list
vault policy read app-readonly
vault token create -policy=app-readonly -ttl=1h

Policies are attached when a token is created, or by an auth method role (for example "pods in namespace shop get policy app-readonly"). Changing a policy affects existing tokens immediately because tokens store only the policy names.

Built-in policies

  • default is attached to every token unless you pass -no-default-policy. It lets a token look up itself, renew itself and use its cubbyhole.
  • root can do anything. Treat the root token as an emergency tool: generate it, use it for initial setup, then revoke it.

Never give an application the root policy, and avoid sudo unless a path demands it. Review the default policy too; some organizations tighten it.

A stand-in evaluator

The next example is a minimal model of the decision: find the rules for a path, then test the verb. It supports exact paths and a trailing * only (real Vault has more, see path matching).

JS Stand-in: does this policy allow it?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Policy templates and parameters

Policies can contain templates that use identity information so one policy serves many users:

HCL
path "secret/data/users/{{identity.entity.name}}/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}

Each user sees only their own folder. See identity entities. You can also restrict request parameters with required_parameters, allowed_parameters and denied_parameters, useful for forcing a TTL or blocking a risky field.

JS Stand-in: expanding a templated path

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Good habits

  • Start with the smallest set: read only, one path, then widen.
  • Name policies after the job (payments-api-read), not the person.
  • Keep policy files in Git and apply them from CI or Terraform.
  • Use vault token capabilities <token> <path> to test what a token can do.
  • Grant list on the metadata path if people browse in the UI.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What happens when no policy rule matches the requested path?

    Vault is deny-by-default: access exists only if a policy grants it.
  2. 2. For KV version 2, which path must a policy use to read secret/myapp/db?

    KV v2 stores values under the data/ segment, so the policy must name that path.
  3. 3. Which capability overrides all others?

    deny always wins, even if another rule grants access.
  4. 4. A policy is edited after tokens were issued. What happens?

    Tokens only hold policy names, which are resolved on each request.

Summary

  • A policy maps paths to capabilities; no match means no access.
  • KV v2 needs data/ and metadata/ in paths.
  • deny beats everything; root and sudo need extra care.
  • Templated policies scale one rule to many users.
  • Test with vault token capabilities and keep policies in version control.

Next: Policy Path Matching