Day 2: Tokens and Policies
Goal: Create, renew and revoke tokens deliberately, and write and test least-privilege policies. · Duration: approx. 75 min · Prerequisite: Day 1
Briefing
- Every access needs a token. Every token has policies, a TTL and usually a parent token.
- If a parent token is revoked, all its children are gone too. The exception is orphan tokens.
- A policy grants capabilities on paths. Everything that is not
allowed is forbidden.
denybeats every grant. - The accessor is a reference to a token. With it you can look up or revoke the token, but not use it.
root
├─ Token A (default, ttl 1h, max 2h)
│ └─ Child A1 <- dies with A
└─ Orphan B <- survives A
Drill 1: Fresh Server and First Token
Terminal 1: bao server -dev -dev-root-token-id=root
Terminal 2:
cd ~/bao-lab/tag02
export BAO_ADDR=http://127.0.0.1:8200 BAO_TOKEN=root
bao token lookupExpected (abridged):
accessor 251a0VhPOrWfPFAGGybachGV
explicit_max_ttl 0s
id root
orphan true
policies [root]
ttl 0s
The root token never expires (ttl 0s). That is exactly
why it is dangerous (Day 13).
bao token create -policy=default -ttl=1h -explicit-max-ttl=2hExpected:
Key Value
--- -----
token s.uY94PuSeZJF7uxLcW35LwQux
token_accessor vD0klFhFClKaV1nxS1IEvPNc
token_duration 1h
token_renewable true
token_policies ["default"]
identity_policies []
policies ["default"]
Tip: OpenBao service tokens start with
s.. Vault useshvs.today.
Save your progress? Sign up for free
Drill 2: Renew and the Hard Ceiling
T=$(bao token create -field=token -policy=default -ttl=1h -explicit-max-ttl=2h)
bao token renew -increment=90m $T | grep duration
bao token renew -increment=3h $TExpected (abridged):
token_duration 1h30m
WARNING! The following warnings were returned from OpenBao:
* TTL of "3h" exceeded the effective max_ttl of "2h"; TTL value is capped
accordingly
token_duration 2h
After 2 hours the token is dead, no matter how often you renew it.
Save your progress? Sign up for free
Drill 3: Periodic, Limited, Orphan
A periodic token has no ceiling as long as it is renewed within
period. That suits long-lived services:
P=$(bao token create -field=token -policy=default -period=24h)
bao token lookup -format=json $P | jq -c '.data | {period, ttl, explicit_max_ttl}'Expected:
{"period":86400,"ttl":86399,"explicit_max_ttl":0}
A token with a use limit:
U=$(bao token create -field=token -policy=default -use-limit=2)
BAO_TOKEN=$U bao token lookup -format=json | jq .data.num_uses
BAO_TOKEN=$U bao token lookup -format=json | jq .data.num_uses
BAO_TOKEN=$U bao token lookupExpected (abridged):
1
-1
Code: 403. Errors:
* permission denied
Every request consumes one use. After the second request the token is revoked.
Parent, child and orphan. The default token may not
create children. That is why the parent gets a small policy:
bao policy write token-creator - <<'EOF'
path "auth/token/create" {
capabilities = ["create", "update"]
}
EOF
PARENT=$(bao token create -field=token -policy=token-creator)
CHILD=$(BAO_TOKEN=$PARENT bao token create -field=token -policy=default)
ORPH=$(bao token create -field=token -policy=default -orphan)
bao token revoke $PARENT
bao token lookup $CHILD
bao token lookup -format=json $ORPH | jq .data.orphanExpected (abridged):
Success! Uploaded policy: token-creator
Success! Revoked token (if it existed)
Code: 403. Errors:
* bad token
true
Tip:
bao token revoke -mode=orphan <token>revokes only the parent token. The children then become orphans.
Save your progress? Sign up for free
Drill 4: Accessor and Capabilities
J=$(bao token create -format=json -policy=default -ttl=1h)
TOK=$(echo "$J" | jq -r .auth.client_token)
ACC=$(echo "$J" | jq -r .auth.accessor)
bao token lookup -accessor $ACC | grep -E '^(id|policies|ttl) '
bao token capabilities $TOK auth/token/lookup-self
bao token capabilities $TOK secret/data/webshop/config
bao token revoke -accessor $ACC
bao list auth/token/accessorsExpected (abridged):
id n/a
policies [default]
ttl 59m59s
read
deny
Success! Revoked token (if it existed)
Keys
----
251a0VhPOrWfPFAGGybachGV
...
Why id n/a? Through the accessor you never see the token
itself. That is why an operator with accessor permissions may manage
tokens without being able to steal them.
Save your progress? Sign up for free
Drill 5: Write the
webshop-read Policy
bao kv put -mount=secret webshop/config db_user=webshop db_pass=lab-pw-1
bao kv put -mount=secret webshop/admin root_pw=lab-admin
bao kv put -mount=secret billing/config iban=DE00-LAB
cat > webshop-read.hcl <<'EOF'
# Read contents (KV v2: data/)
path "secret/data/webshop/*" {
capabilities = ["read"]
}
# List and see versions (KV v2: metadata/)
path "secret/metadata/webshop/*" {
capabilities = ["read", "list"]
}
# Lock the admin secret – deny always wins
path "secret/data/webshop/admin" {
capabilities = ["deny"]
}
EOF
bao policy fmt webshop-read.hcl
bao policy write webshop-read webshop-read.hclExpected (abridged):
Success! Formatted policy: webshop-read.hcl
Success! Uploaded policy: webshop-read
Warning: With KV v2 you write
secret/data/…in the policy, notsecret/…. The CLI addsdata/, the policy does not.
Save your progress? Sign up for free
Drill 6: Test the Policy and Provoke a 403
Log in with a restricted token. bao login stores the
token in ~/.vault-token. A set BAO_TOKEN would
take precedence, though, so unset comes first:
W=$(bao token create -field=token -policy=webshop-read -ttl=30m)
unset BAO_TOKEN
bao login $WExpected (abridged):
Success! You are now authenticated. The token information displayed below is
already stored in the token helper. You do NOT need to run "bao login" again.
token_duration 29m59s
token_policies ["default" "webshop-read"]
bao kv get -mount=secret -field=db_user webshop/config; echo
bao kv list -mount=secret webshop
bao kv get -mount=secret webshop/admin
bao kv get -mount=secret billing/config
bao kv put -mount=secret webshop/config x=1Expected (abridged):
webshop
Keys
----
admin
config
Error reading secret/data/webshop/admin: Error making API request.
Code: 403. Errors:
* permission denied
Error reading secret/data/billing/config: Error making API request.
Code: 403. Errors:
* permission denied
Error writing data to secret/data/webshop/config: Error making API request.
Code: 403. Errors:
* permission denied
Now you check without trying anything:
bao token capabilities secret/data/webshop/config
bao token capabilities secret/data/webshop/admin
bao token capabilities secret/metadata/webshop/Expected:
read
deny
list, read
Back to root:
bao token revoke -self && export BAO_TOKEN=root.
Tip: Every token automatically receives the
defaultpolicy. Read it once withbao policy read default. Among other things, it allowslookup-self,renew-self,revoke-selfandsys/capabilities-self. If you don’t want it, use-no-default-policy.
Save your progress? Sign up for free
Drill 7: Glob * and Segment
+
* only appears at the end and matches everything,
including /. + matches exactly one path
segment:
bao kv put -mount=secret apps/shop/config k=1
bao kv put -mount=secret apps/crm/extra/deep k=3
bao policy write apps-config - <<'EOF'
path "secret/data/apps/+/config" {
capabilities = ["read"]
}
EOF
A=$(bao token create -field=token -policy=apps-config)
for p in apps/shop/config apps/crm/config apps/crm/extra/deep; do
echo "$p: $(bao token capabilities $A secret/data/$p)"
doneExpected (abridged):
apps/shop/config: read
apps/crm/config: read
apps/crm/extra/deep: deny
Save your progress? Sign up for free
Drill 8: Restrict Parameters
cat > shop-writer.hcl <<'EOF'
# Write feature flags – only with the "data" field
path "secret/data/webshop/feature-*" {
capabilities = ["create", "update"]
required_parameters = ["data"]
}
# Child tokens only with webshop-read and TTL 15m/30m (the CLI sends "15m0s")
path "auth/token/create" {
capabilities = ["update"]
allowed_parameters = {
"policies" = [["webshop-read"]]
"ttl" = ["15m0s", "30m0s"]
"*" = []
}
}
EOF
bao policy write shop-writer shop-writer.hcl
export BAO_TOKEN=$(bao token create -field=token -policy=shop-writer -policy=webshop-read)
bao token create -policy=webshop-read -ttl=15m | grep duration
bao token create -policy=webshop-read -ttl=24h
bao token create -policy=default -ttl=15mExpected (abridged):
token_duration 15m
Error creating token: Error making API request.
Code: 403. Errors:
* permission denied
Error creating token: Error making API request.
Code: 403. Errors:
* permission denied
Why "*" = []? The CLI always also sends
period, renewable, num_uses and
other fields. Without * these would be forbidden. And why
does the parent also get webshop-read? The policies of a
child token must be a subset of the parent’s policies. Otherwise OpenBao
answers with child policies must be subset of parent.
Tip:
-output-curl-stringshows which fields a command really sends.
You test required_parameters with curl:
curl -s -X POST -H "X-Vault-Token: $BAO_TOKEN" -d '{"options":{}}' \
$BAO_ADDR/v1/secret/data/webshop/feature-y
export BAO_TOKEN=rootExpected:
{"errors":["1 error occurred:\n\t* permission denied\n\n"]}
Save your progress? Sign up for free
Checkpoint
export BAO_TOKEN=root
W=$(bao token create -field=token -policy=webshop-read -ttl=10m)
c() { [ "$(bao token capabilities $W "$1")" = "$2" ] \
&& echo "✔ $1 = $2" || echo "✘ $1 != $2"; }
c secret/data/webshop/config read
c secret/data/webshop/admin deny
c secret/data/billing/config deny
c secret/metadata/webshop/ "list, read"
bao policy list | grep -qx shop-writer && echo "✔ shop-writer" || echo "✘ shop-writer"Challenge
Write a policy webshop-ops. It may read, write,
soft-delete and restore versions under secret/webshop/. But
it may never run destroy and may not delete any
metadata.
Hint: destroy has its own API path.
Metadata is deleted by delete on
metadata/.
Solution
bao policy write webshop-ops - <<'EOF'
path "secret/data/webshop/*" {
capabilities = ["create", "read", "update", "patch", "delete"]
}
path "secret/delete/webshop/*" {
capabilities = ["update"]
}
path "secret/undelete/webshop/*" {
capabilities = ["update"]
}
path "secret/metadata/webshop/*" {
capabilities = ["read", "list"]
}
path "secret/destroy/webshop/*" {
capabilities = ["deny"]
}
EOF
O=$(bao token create -field=token -policy=webshop-ops)
BAO_TOKEN=$O bao kv delete -mount=secret webshop/config
BAO_TOKEN=$O bao kv undelete -mount=secret -versions=1 webshop/config
BAO_TOKEN=$O bao kv destroy -mount=secret -versions=1 webshop/config
BAO_TOKEN=$O bao kv metadata delete -mount=secret webshop/configExpected (abridged):
Success! Data deleted (if it existed) at: secret/data/webshop/config
Success! Data written to: secret/undelete/webshop/config
Error writing data to secret/destroy/webshop/config: Error making API request.
Code: 403. Errors:
Error deleting secret/metadata/webshop/config: Error making API request.
Code: 403. Errors:
Save your progress? Sign up for free
Enterprise Note
- Never hand out root tokens to people or apps. Use auth methods (Day 3) with short TTLs.
- Set
-explicit-max-ttlortoken_max_ttl. Use periodic tokens only for services that renew themselves. - Manage policies as code with review, for example with
Terraform/OpenTofu (Day 13), and test them with
token capabilitiesin CI. - Work with accessors in runbooks and audit analyses, never with tokens.
- Lay out paths so that policies stay simple, such as
secret/<team>/<app>/….