Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 36 ยท Policies and Tokens

Vault Policy Path Matching: Globs, Plus Segments and Priority

Understand how Vault picks a policy rule: exact paths, the trailing glob, the + segment wildcard, priority between rules, multiple policies and common matching mistakes.

When a request arrives, Vault must decide which path rule applies. If several rules match, the most specific one wins. Getting this wrong is the top cause of "permission denied" surprises and of accidentally broad access. This lesson explains the matching rules and gives you a stand-in matcher to practice with.

The matcher below is a teaching stand-in written in JavaScript, not Vault. Real Vault has extra rules (parameter constraints, templates). Use vault token capabilities against a real server for a final answer.

Three kinds of patterns

  1. Exact: secret/data/app/db matches only that path.
  2. Trailing glob: secret/data/app/* matches everything that starts with secret/data/app/. The * is a wildcard only at the end of the path.
  3. Segment wildcard +: matches exactly one path segment anywhere, for example secret/data/+/db covers secret/data/payments/db and secret/data/orders/db but not secret/data/payments/eu/db.
HCL
path "secret/data/+/config" {
  capabilities = ["read"]
}
path "secret/data/shared/*" {
  capabilities = ["read", "list"]
}
path "secret/data/shared/private" {
  capabilities = ["list"]
}

A * in the middle is a literal star, not a wildcard. A glob prefix is a plain string prefix: secret/data/app* also matches secret/data/apple.

Which rule wins?

  • An exact match beats a glob.
  • Between several globs, the one with the longest prefix wins.
  • A + segment ranks lower than a literal segment at the same position.
  • Once the winning rule is chosen, only its capabilities apply. Capabilities of less specific rules are not added.

That last point matters: with the rules above, secret/data/shared/private can be listed but not read, even though secret/data/shared/* grants read.

JS Stand-in: pick the winning rule

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

No output.

Multiple policies on one token

A token usually has several policies (default plus yours). Vault combines the capabilities granted by each policy's winning rule, and deny in any policy wins. Avoid contradictory rules and use deny deliberately for guard rails:

HCL
# platform-guard.hcl
path "sys/*" {
  capabilities = ["deny"]
}

Common mistakes

  • Forgetting list. read on secret/data/app/* does not let anyone browse. Listing happens on secret/metadata/app/ (KV v2).
  • Using * in the middle. secret/*/db is not a wildcard match; use +.
  • Overlapping globs. A shorter glob cannot widen a longer rule's capabilities.
  • Prefix surprises. app* matches apple. Prefer app/*.
  • Assuming the CLI path equals the policy path. See policy basics for KV v2.
JS Stand-in: spot an unintended match

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

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the + wildcard match?

    • stands for exactly one segment anywhere in the path.
  2. 2. Rules secret/* (list) and secret/data/shared/* (read) exist. Which applies to secret/data/shared/x?

    The longest matching prefix wins and only its capabilities apply.
  3. 3. Does secret/*/db match secret/data/db?

    • is a wildcard only at the end; use + for one segment.
  4. 4. Why does secret/data/app* match secret/data/apple?

    Without a slash before the star, any path starting with that prefix matches.

Summary

  • Patterns are exact, trailing *, or + for one segment.
  • Exact beats glob; longer prefix beats shorter; only the winner's capabilities apply.
  • deny in any attached policy wins.
  • Prefer app/* over app*, and remember list lives on the metadata path in KV v2.

Next: Tokens: Types and Hierarchy