Vault paths and wildcards

Hi Vault community,

Forgive me as I am very new to vault and have only to this point built a failover cluster Vault environment with a consul backend (yes I know this is now no longer required) deployed using terraform and ansible on a vsphere environment using CI/CD.

Now I am at the point of learning how to actually use Vault. However, I am a bit confused about vault paths and wondering if someone could clarify how wildcards work in policies and PUT operations?

I set up a test on my vault environment:

# vault secrets enable -path=ops/data/vault-test/* kv

I then created a policy:

# vault policy write vault-test - <<EOF
path "ops/data/vault-test/*" {
    capabilities = ["create", "read", "update", "patch", "delete", "list"]

I then created a role:

# vault write auth/jwt/role/vault-test - <<EOF               > {
>   "role_type": "jwt",
>   "policies": ["vault-test"],
>   "token_explicit_max_ttl": 60,
>   "user_claim": "user_email",
>   "bound_claim_type": "glob",
>   "bound_claims": {
>     "project_id": "42",
>     "ref_protected": "true",
>     "ref_type": "tag",
>     "ref": "auto-deploy-*"
>   }
> }

and then set a token to use that role:

# export VAULT_TOKEN="$(vault token create -field token -policy=vault-test)"

Then I tried to create a secret in kv using that path:

# vault kv put -mount=ops/data/vault-test/secret kv test_secret=password123
Error making API request.

Code: 403. Errors:

* preflight capability check returned 403, please ensure client's policies grant access to path "ops/data/vault-test/secret/"

It was my belief that “ops/data/vault-test/secret/” would be acceptable since there is a wildcard in the policy and the path would be created.

Even odder, this works hence my confusion:

# vault kv put -mount=ops/data/vault-test/* kv test_secret=password123
Success! Data written to: ops/data/vault-test/*/kv

It’s taking the wildcard literally!

Can someone please explain is this a bug or a misunderstanding? How is a wildcard supposed to work? Or should I be using a /+/ there instead?

Also, what are the best practices around setting paths? My intuition tells me that I should set something like:
/<project or department>/<application>/<environment>/<what-it-is (secret etc)>/

Or should you put what it is at the beginning i.e beginning with /kv/?



This command is the start of the problems.

Apparently - and it’s a surprise to me that this is allowed, and probably should be considered a bug - you’ve managed to create a literal path in Vault that contains an asterisk character. This will cause all kinds of confusion as you try to write policies that relate to it. You should not use an asterisk in naming the path to a secrets engine.

1 Like

Oh wow that really was an obvious error I didn’t realise I had even done. Of course, it makes sense, that path is the mount point and the root for that secrets engine. Very embarassing lol.

It did work once I disabled it and enabled it without the wildcard in there.

One more question, once I created a secret it is accessed using:

# vault kv get ops/data/vault-test/secrets/kv
======= Data =======
Key            Value
---            -----
test_secret    password123

Am I correct if I want to filter this to only get test_secret I use -field=test_secret? That did give me the result, but is it the best way.

I believe in this test example I should have put kv in the path and not actually named it kv

I really need to get my head around the best way to name things.

That is the way that’s provided, for if you’re working with Vault via shell scripts. It makes sense to use it in that context. In other programming environments you’d be more likely to talk to the Vault API directly.

For the most part, just whatever works for you.

The only thing to bear in mind is that Vault ACL policies have limited support for wildcards:

  • * can match any number of characters, at the end of a path only
  • + can match any one complete slash-separated path segment

So, if you can reasonably predict that you need to write wildcard policies covering multiple secrets engines, it is useful to bear that in mind when structuring their names.


I wrote up a guide to Vault ACL policies based on my experience with Vault and some common questions in the forums here:

It’s by no means perfect, but might help you get through some of the topics you’ll encounter.