Skip to content
Hands-on IT IT Drills

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. deny beats 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 lookup

Expected (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=2h

Expected:

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 uses hvs. 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 $T

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

Expected (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.orphan

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

Expected (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.hcl

Expected (abridged):

Success! Formatted policy: webshop-read.hcl
Success! Uploaded policy: webshop-read

Warning: With KV v2 you write secret/data/… in the policy, not secret/…. The CLI adds data/, 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 $W

Expected (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=1

Expected (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 default policy. Read it once with bao policy read default. Among other things, it allows lookup-self, renew-self, revoke-self and sys/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)"
done

Expected (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=15m

Expected (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-string shows 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=root

Expected:

{"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/config

Expected (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-ttl or token_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 capabilities in 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>/….