Skip to content
Hands-on IT IT Drills

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 into secret/data/… (content) and secret/metadata/… (versions, metadata).
  • Policies grant permissions on API paths, so always with data/ or metadata/.
  • 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/api

Expected:

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/shop

Expected:

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/api

Expected (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 -v and set -x write 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 version

Expected (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-read

Expected:

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/shop

Expected (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")"
done

Expected:

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 unwrap

Expected (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/null

Challenge

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")"
done

Expected:

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_versions and delete_version_after deliberately. 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/lookup to check that creation_path is right.
  • Root tokens are revoked after setup. Admins work with their own identities so that the audit log shows who read what (Day 14).