Day 1: Reading Secrets
Goal: Read KV v2 secrets via CLI, JSON and curl, master versions, build a token with minimal permissions and hand over a secret safely. · Duration: approx. 60 min · Prerequisite: Day 0
Briefing
- KV v2 versions every secret. The CLI says
secret/shop/api, the API splits it intosecret/data/…(content) andsecret/metadata/…(versions, metadata). - Policies grant permissions on API paths, so always
with
data/ormetadata/. - Anything that is not allowed is forbidden (403).
- Response wrapping packs a response into a single-use token with a short TTL.
bao kv get secret/shop/api ──► GET /v1/secret/data/shop/api
bao kv metadata get … ──► GET /v1/secret/metadata/shop/api
bao kv list secret/shop ──► LIST /v1/secret/metadata/shop
Drill 1: Reading with the CLI
cd ~/secrets-lab/tag01
~/secrets-lab/setup/check.sh | grep ✘ || echo "Gelände ok"
bao kv get secret/shop/apiExpected:
Gelände ok
==== Secret Path ====
secret/data/shop/api
======= Metadata =======
Key Value
--- -----
created_time 2026-10-12T06:18:53.346454787Z
custom_metadata <nil>
deletion_time n/a
destroyed false
version 1
======= Data =======
Key Value
--- -----
api_key lab-api-key-456
db_password lab-db-pw-123
db_user shop
For scripts you usually need exactly one value:
bao kv get -field=db_password secret/shop/api; echo
bao kv get -mount=secret -field=db_user shop/api; echo
bao kv list secret/shopExpected:
lab-db-pw-123
shop
Keys
----
api
stripe
-field prints the value without a trailing newline,
hence the echo. -mount=secret is the
unambiguous notation when a mount name itself contains slashes.
Save your progress? Sign up for free
Drill 2: JSON and jq
bao kv get -format=json secret/shop/api | jq -r '.data.data.api_key'
bao kv get -format=json secret/shop/api | jq '.data.metadata'Expected:
lab-api-key-456
{
"created_time": "2026-10-12T06:18:53.346454787Z",
"custom_metadata": null,
"deletion_time": "",
"destroyed": false,
"version": 1
}
Remember the double .data.data: the outer
data is the API response, the inner one holds your keys.
This exact structure shows up again in ESO, agent templates and
hvac.
Save your progress? Sign up for free
Drill 3: The Same Query with curl
Every CLI query is an HTTP call. The CLI tells you which one:
bao kv get -output-curl-string secret/shop/apiExpected (wrapped):
curl -H "X-Vault-Request: true" -H "X-Vault-Token: $(bao print token)"
"http://127.0.0.1:8200/v1/secret/data/shop/api"
Now do it yourself, once with the token header, once with a bearer header, once without a token:
curl -s -H "X-Vault-Token: $BAO_TOKEN" \
"$BAO_ADDR/v1/secret/data/shop/api" | jq '.data.data'
curl -s -H "Authorization: Bearer $BAO_TOKEN" \
"$BAO_ADDR/v1/secret/data/shop/api" | jq -r '.data.data.db_password'
curl -s -w ' HTTP %{http_code}\n' "$BAO_ADDR/v1/secret/data/shop/api"
curl -s -X LIST -H "X-Vault-Token: $BAO_TOKEN" \
"$BAO_ADDR/v1/secret/metadata/shop" | jq -c '.data'Expected:
{
"api_key": "lab-api-key-456",
"db_password": "lab-db-pw-123",
"db_user": "shop"
}
lab-db-pw-123
{"errors":["permission denied"]}
HTTP 403
{"keys":["api","stripe"]}
No token, no secret, and with 403, not 401.
LIST is an HTTP method of OpenBao’s own. Alternatively,
GET …?list=true works.
Security:
curl -vandset -xwrite the token header to the log. Avoid both in pipelines (Day 14).
Save your progress? Sign up for free
Drill 4: patch Instead of put
The most common KV accident: kv put replaces the
entire secret. Try it on a playground path, not on the
demo data:
bao kv put secret/shop/playground user=demo password=lab-pw-1 | grep version
bao kv patch secret/shop/playground password=lab-pw-2 | grep version
bao kv get -format=json secret/shop/playground | jq -c '.data.data'
bao kv put secret/shop/playground password=lab-pw-3 | grep version
bao kv get -format=json secret/shop/playground | jq -c '.data.data'Expected:
version 1
version 2
{"password":"lab-pw-2","user":"demo"}
version 3
{"password":"lab-pw-3"}
patch changes individual keys, put writes a
new version with only the keys you specify.
user is gone in version 3.
Save your progress? Sign up for free
Drill 5: Versions and Metadata
Luckily nothing is lost:
bao kv get -version=2 -format=json secret/shop/playground | jq -c '.data.data'
bao kv rollback -version=2 secret/shop/playground | grep version
bao kv get -format=json secret/shop/playground \
| jq -c '.data | {v: .metadata.version, d: .data}'Expected:
{"password":"lab-pw-2","user":"demo"}
version 4
{"v":4,"d":{"password":"lab-pw-2","user":"demo"}}
rollback copies the old version as a
new version 4. The history is preserved. Metadata is
attached to the path, not to a version:
bao kv metadata put -max-versions=5 \
-custom-metadata=owner=team-shop -custom-metadata=rotation=90d \
secret/shop/playground
bao kv metadata get -format=json secret/shop/playground \
| jq '.data | {max_versions, custom_metadata}'Expected:
Success! Data written to: secret/metadata/shop/playground
{
"max_versions": 5,
"custom_metadata": {
"owner": "team-shop",
"rotation": "90d"
}
}
Check-and-set protects against concurrent writers: the write succeeds only if the given version is the current one.
bao kv put -cas=3 secret/shop/playground password=x
bao kv put -cas=4 secret/shop/playground user=demo password=lab-pw-5 | grep versionExpected (abridged):
Error writing data to secret/data/shop/playground: Error making API request.
...
Code: 400. Errors:
* check-and-set parameter did not match the current version
version 5
Save your progress? Sign up for free
Drill 6: A Token with Minimal Permissions
Root tokens are for humans in the lab. An application gets exactly its own policy. The CLI tells you which policy a command needs:
bao kv get -output-policy secret/shop/api
bao policy read shop-api-readExpected:
path "secret/data/shop/api" {
capabilities = ["read"]
}
path "secret/data/shop/*" {
capabilities = ["read"]
}
Now a token that has only
shop-api-read:
APP_TOKEN=$(bao token create -policy=shop-api-read -ttl=15m -field=token)
bao token lookup -format=json "$APP_TOKEN" | jq -c '.data | {policies, ttl}'
BAO_TOKEN=$APP_TOKEN bao kv get -field=api_key secret/shop/api; echo
BAO_TOKEN=$APP_TOKEN bao kv put secret/shop/api db_user=hacker
BAO_TOKEN=$APP_TOKEN bao kv list secret/shopExpected (abridged):
{"policies":["default","shop-api-read"],"ttl":900}
lab-api-key-456
Error writing data to secret/data/shop/api: Error making API request.
URL: PUT http://127.0.0.1:8200/v1/secret/data/shop/api
Code: 403. Errors:
* 1 error occurred:
* permission denied
Error listing secret/metadata/shop: Error making API request.
URL: GET http://127.0.0.1:8200/v1/secret/metadata/shop?list=true
Code: 403. Errors:
...
Reading works, writing and listing do not: list needs a
rule on secret/metadata/…. The default policy
is attached to every token and only allows self-management (looking up,
renewing and revoking your own token).
Save your progress? Sign up for free
Drill 7: Checking Permissions Without Guessing
for p in secret/data/shop/api secret/data/shop/playground \
secret/metadata/shop/api secret/data/ci/deploy; do
printf '%-30s %s\n' "$p" "$(bao token capabilities "$APP_TOKEN" "$p")"
doneExpected:
secret/data/shop/api read
secret/data/shop/playground read
secret/metadata/shop/api deny
secret/data/ci/deploy deny
Line 2 is the lesson: shop/* also allows the playground.
A * in a policy covers everything that will ever be created
there later. Without a token argument,
bao token capabilities <path> checks your own
token.
Save your progress? Sign up for free
Drill 8: Response Wrapping for Safe Handover
You need to give a secret to a colleague or a deploy job without it sitting in a chat or a ticket. Solution: a wrapping token, redeemable once, with a short TTL.
WRAP=$(bao kv get -wrap-ttl=5m -format=json secret/shop/stripe \
| jq -r '.wrap_info.token')
bao write sys/wrapping/lookup token="$WRAP"Expected:
Key Value
--- -----
creation_path secret/data/shop/stripe
creation_time 2026-10-12T06:19:41.138587204Z
creation_ttl 5m
The recipient does not need a token of their own, only the wrapping token:
BAO_TOKEN=$WRAP bao unwrap -format=json | jq -c '.data.data'
BAO_TOKEN=$WRAP bao unwrapExpected (abridged):
{"token":"lab-stripe-789"}
Error unwrapping: Error making API request.
URL: PUT http://127.0.0.1:8200/v1/sys/wrapping/unwrap
Code: 400. Errors:
* wrapping token is not valid or does not exist
The second attempt fails. If the real recipient gets this error, someone else redeemed the token first: an alarm instead of a silent leak. Even more valuable is wrapping a token instead of a secret, the “secret zero” for a new service:
WRAP=$(bao token create -policy=shop-api-read -ttl=1h -wrap-ttl=2m -format=json \
| jq -r '.wrap_info.token')
NEW=$(BAO_TOKEN=$WRAP bao unwrap -field=token)
bao token lookup -format=json "$NEW" | jq -c '.data | {policies, ttl}'Expected:
{"policies":["default","shop-api-read"],"ttl":3599}
With curl, both work via the X-Vault-Wrap-TTL
header:
WRAP=$(curl -s -H "X-Vault-Token: $BAO_TOKEN" -H "X-Vault-Wrap-TTL: 120s" \
"$BAO_ADDR/v1/secret/data/shop/stripe" | jq -r '.wrap_info.token')
curl -s -X POST -H "X-Vault-Token: $WRAP" "$BAO_ADDR/v1/sys/wrapping/unwrap" \
| jq -c '.data.data'Expected:
{"token":"lab-stripe-789"}
Save your progress? Sign up for free
Checkpoint
T=$(bao token create -policy=shop-api-read -ttl=5m -field=token)
[ "$(bao token capabilities "$T" secret/data/shop/api)" = read ] \
&& echo "✔ shop-api-read darf lesen" || echo "✘ shop-api-read darf nicht lesen"
BAO_TOKEN=$T bao kv put secret/shop/api x=y >/dev/null 2>&1 \
&& echo "✘ shop-api-read darf schreiben!" || echo "✔ Schreiben verboten (403)"
bao kv metadata get -format=json secret/shop/playground 2>/dev/null \
| jq -e '.data.custom_metadata.owner == "team-shop"' >/dev/null \
&& echo "✔ Metadaten owner=team-shop" || echo "✘ Metadaten fehlen (Drill 5)"
bao kv get -version=2 -field=user secret/shop/playground >/dev/null 2>&1 \
&& echo "✔ Version 2 lesbar" || echo "✘ Version 2 fehlt (Drill 4)"
W=$(bao kv get -wrap-ttl=1m -format=json secret/shop/stripe | jq -r .wrap_info.token)
BAO_TOKEN=$W bao unwrap >/dev/null 2>&1 && ! BAO_TOKEN=$W bao unwrap >/dev/null 2>&1 \
&& echo "✔ Wrapping-Token nur einmal einlösbar" || echo "✘ Wrapping"
bao token revoke "$T" >/dev/nullChallenge
shop-api needs only secret/shop/api, not
secret/shop/stripe and certainly not the playground. Write
a policy shop-api-strict that allows exactly that, and
prove with bao token capabilities that stripe
and metadata are forbidden.
Hint: Without * the policy gets longer,
but every new file under shop/ stays locked by default.
Solution
cat > ~/secrets-lab/tag01/shop-api-strict.hcl <<'EOF'
# Exactly the one secret that shop-api needs – no wildcard
path "secret/data/shop/api" {
capabilities = ["read"]
}
EOF
bao policy write shop-api-strict ~/secrets-lab/tag01/shop-api-strict.hcl
T=$(bao token create -policy=shop-api-strict -ttl=15m -field=token)
for p in secret/data/shop/api secret/data/shop/stripe secret/metadata/shop/api; do
printf '%-26s %s\n' "$p" "$(bao token capabilities "$T" "$p")"
doneExpected:
Success! Uploaded policy: shop-api-strict
secret/data/shop/api read
secret/data/shop/stripe deny
secret/metadata/shop/api deny
Save your progress? Sign up for free
Enterprise Note
- Policies as code (HCL in Git, review via merge request), not by hand in the UI. Wildcards only where a team owns its own path tree.
- Define a path convention up front,
e.g.
<mount>/<team>/<app>/<environment>. It determines how narrow policies can get. - Set
max_versionsanddelete_version_afterdeliberately. Old versions are also old, still valid passwords as long as nobody rotates. - Wrapping tokens with a TTL of minutes for handovers to humans and
legacy systems. The recipient uses
sys/wrapping/lookupto check thatcreation_pathis right. - Root tokens are revoked after setup. Admins work with their own identities so that the audit log shows who read what (Day 14).