Skip to content
Hands-on IT IT Drills

Day 3: Auth Methods – userpass, AppRole and Response Wrapping

Goal: Log in people with userpass and machines with AppRole, and deliver the SecretID securely via response wrapping. · Duration: approx. 75 min · Prerequisite: Day 2

Briefing

  • An auth method exchanges a proof for a token. Policies and TTLs come from the configuration of the user or role.
  • userpass is meant for people in the lab. AppRole is for machines: the RoleID is like a username, the SecretID like a short-lived password.
  • Response wrapping packs a response into a single-use token. Only whoever unwraps it sees the contents. If it is intercepted, the recipient notices.
CI/orchestrator --(wrap-ttl)--> wrapping token --> app
App: unwrap -> SecretID; RoleID lives in the image/config
App: login(RoleID, SecretID) -> token (webshop-read, 20m)

Drill 1: Preparation

Terminal 1: bao server -dev -dev-root-token-id=root

Terminal 2:

cd ~/bao-lab/tag03
export BAO_ADDR=http://127.0.0.1:8200 BAO_TOKEN=root
cp ../tag02/webshop-read.hcl .
bao policy write webshop-read webshop-read.hcl
bao kv put -mount=secret webshop/config db_user=webshop db_pass=lab-pw-1

Expected (abridged):

Success! Uploaded policy: webshop-read
version            1

Save your progress? Sign up for free

Drill 2: userpass

bao auth enable userpass
bao write auth/userpass/users/thomas password=lab-pw-thomas \
  token_policies=webshop-read token_ttl=1h
bao read auth/userpass/users/thomas

Expected (abridged):

Success! Enabled userpass auth method at: userpass/
Success! Data written to: auth/userpass/users/thomas
Key                        Value
---                        -----
token_bound_cidrs          []
token_max_ttl              0s
token_policies             [webshop-read]
token_ttl                  1h
token_type                 default

Log in via the CLI. If you leave out password=, the CLI asks for it, and the password does not end up in the history:

unset BAO_TOKEN
bao login -method=userpass username=thomas
bao token lookup | grep -E '^(display_name|path|policies|meta)'
bao kv get -mount=secret -field=db_user webshop/config; echo

Expected (abridged):

Password (will be hidden):
Success! You are now authenticated. ...
token_duration         1h
token_policies         ["default" "webshop-read"]
token_meta_username    thomas
display_name        userpass-thomas
meta                map[username:thomas]
path                auth/userpass/login/thomas
policies            [default webshop-read]
webshop

The same via the API:

curl -s -X POST -d '{"password":"lab-pw-thomas"}' \
  $BAO_ADDR/v1/auth/userpass/login/thomas \
  | jq -c '.auth | {policies, lease_duration, metadata}'
rm ~/.vault-token && export BAO_TOKEN=root

Expected:

{"policies":["default","webshop-read"],"lease_duration":3600,
 "metadata":{"username":"thomas"}}

Save your progress? Sign up for free

Drill 3: Create the webshop AppRole

bao auth enable approle
bao write auth/approle/role/webshop \
  token_policies=webshop-read token_ttl=20m token_max_ttl=1h \
  bind_secret_id=true secret_id_ttl=10m secret_id_num_uses=1 \
  secret_id_bound_cidrs=127.0.0.1/32
bao read auth/approle/role/webshop

Expected (abridged):

Success! Enabled approle auth method at: approle/
Success! Data written to: auth/approle/role/webshop
Key                        Value
---                        -----
bind_secret_id             true
secret_id_bound_cidrs      [127.0.0.1/32]
secret_id_num_uses         1
secret_id_ttl              10m
token_max_ttl              1h
token_policies             [webshop-read]
token_ttl                  20m
Parameter Effect
bind_secret_id A SecretID is required for login. Leave it at true.
secret_id_ttl How long a SecretID is valid.
secret_id_num_uses How often a SecretID may be used. 1 means a one-time password.
secret_id_bound_cidrs From which source IPs a login is allowed.

Save your progress? Sign up for free

Drill 4: RoleID, SecretID, Login

bao read auth/approle/role/webshop/role-id
bao write -f auth/approle/role/webshop/secret-id

Expected:

Key        Value
---        -----
role_id    e6d4b29c-ea95-33ab-e221-e222acd87c6c
Key                   Value
---                   -----
secret_id             c0fbd747-8419-035d-be8d-6c2f3e7e5b47
secret_id_accessor    1737860f-c4c6-26a2-d5e3-a65bca0c008f
secret_id_num_uses    1
secret_id_ttl         10m

Log in via the CLI. There is no bao login -method=approle for AppRole. You write directly to the login path:

ROLE_ID=$(bao read -field=role_id auth/approle/role/webshop/role-id)
SECRET_ID=$(bao write -f -field=secret_id auth/approle/role/webshop/secret-id)
bao write auth/approle/login role_id=$ROLE_ID secret_id=$SECRET_ID
bao write auth/approle/login role_id=$ROLE_ID secret_id=$SECRET_ID

Expected (abridged):

Key                     Value
---                     -----
token                   s.nFjFikeldgveVuN6umToj95T
token_duration          20m
token_policies          ["default" "webshop-read"]
token_meta_role_name    webshop
Error writing data to auth/approle/login: Error making API request.
Code: 400. Errors:

* invalid role or secret ID

The second login fails because secret_id_num_uses=1 applies.

Warning: bao login -method=approle reports Unknown auth method: approle. The CLI has no login helper for AppRole.

Via curl, the way an app would do it:

SECRET_ID=$(bao write -f -field=secret_id auth/approle/role/webshop/secret-id)
curl -s -X POST -d "{\"role_id\":\"$ROLE_ID\",\"secret_id\":\"$SECRET_ID\"}" \
  $BAO_ADDR/v1/auth/approle/login | jq -c '.auth | {policies, lease_duration, metadata}'

Expected:

{"policies":["default","webshop-read"],"lease_duration":1200,
 "metadata":{"role_name":"webshop"}}

Save your progress? Sign up for free

Drill 5: Check the CIDR Binding

bao write auth/approle/role/webshop secret_id_bound_cidrs=10.0.0.0/8
SECRET_ID=$(bao write -f -field=secret_id auth/approle/role/webshop/secret-id)
bao write auth/approle/login role_id=$ROLE_ID secret_id=$SECRET_ID
bao write auth/approle/role/webshop secret_id_bound_cidrs=127.0.0.1/32

Expected (abridged):

Code: 400. Errors:

* source address "127.0.0.1" unauthorized by CIDR restrictions on the role: %!w(<nil>)

The trailing %!w(<nil>) is a formatting bug (still present in v2.7.1), not a problem with your configuration. bao write on an existing role changes only the fields you pass. So token_policies is preserved.

Save your progress? Sign up for free

Drill 6: Response Wrapping

bao write -wrap-ttl=5m -f auth/approle/role/webshop/secret-id

Expected:

Key                              Value
---                              -----
wrapping_token:                  s.U2jG7vG91s440vXGikEIhpy0
wrapping_accessor:               pzz6YYhUUYSEP00moOEdEP9b
wrapping_token_ttl:              5m
wrapping_token_creation_time:    2026-10-08 09:00:39.508782 +0200 CEST
wrapping_token_creation_path:    auth/approle/role/webshop/secret-id
wrapped_accessor:                ed2e8be6-e375-8c95-c07c-ea980da81d76

Check, unwrap, unwrap a second time:

WRAP=$(bao write -wrap-ttl=5m -field=wrapping_token -f \
  auth/approle/role/webshop/secret-id)
bao write sys/wrapping/lookup token=$WRAP
SECRET_ID=$(BAO_TOKEN=$WRAP bao unwrap -field=secret_id); echo $SECRET_ID
BAO_TOKEN=$WRAP bao unwrap

Expected (abridged):

Key              Value
---              -----
creation_path    auth/approle/role/webshop/secret-id
creation_time    2026-10-08T09:00:48.524487+02:00
creation_ttl     5m
b5e26b57-4ac3-8426-5a25-3b11bbe9f959
Error unwrapping: Error making API request.
Code: 400. Errors:

* wrapping token is not valid or does not exist

Why lookup before unwrap? With it, the recipient checks whether creation_path is correct. If the token comes from a different path or has already been used, someone has tampered with it. Then: raise an alarm instead of logging in.

Wrapping works with any response, including KV:

KW=$(bao kv get -mount=secret -wrap-ttl=2m -format=json webshop/config \
  | jq -r .wrap_info.token)
bao unwrap -format=json $KW | jq -c '.data.data'

Expected:

{"db_pass":"lab-pw-1","db_user":"webshop"}

Warning: bao kv get -wrap-ttl=… -field=wrapping_token does not work. It reports No data found. Use -format=json and .wrap_info.token.

With curl you set the X-Vault-Wrap-TTL header:

curl -s -X POST -H "X-Vault-Token: $BAO_TOKEN" -H "X-Vault-Wrap-TTL: 60s" \
  $BAO_ADDR/v1/auth/approle/role/webshop/secret-id \
  | jq -c '.wrap_info | {ttl, creation_path}'

Expected:

{"ttl":60,"creation_path":"auth/approle/role/webshop/secret-id"}

Save your progress? Sign up for free

Drill 7: Enforce Secure Introduction

The deployer may only create SecretIDs in wrapped form and may not read the RoleID. Whoever knows only one half cannot get in:

cat > webshop-deployer.hcl <<'EOF'
# Only SecretIDs for webshop – and only wrapped
path "auth/approle/role/webshop/secret-id" {
  capabilities = ["update"]
  min_wrapping_ttl = "1m"
  max_wrapping_ttl = "10m"
}
EOF
bao policy write webshop-deployer webshop-deployer.hcl
D=$(bao token create -field=token -policy=webshop-deployer -ttl=1h)
BAO_TOKEN=$D bao write -f auth/approle/role/webshop/secret-id
BAO_TOKEN=$D bao write -wrap-ttl=5m -f auth/approle/role/webshop/secret-id | grep ttl
BAO_TOKEN=$D bao read auth/approle/role/webshop/role-id

Expected (abridged):

Code: 403. Errors:
    * permission denied
wrapping_token_ttl:              5m
Code: 403. Errors:
    * permission denied

Save your progress? Sign up for free

Drill 8: Tune Auth Methods

bao auth tune -default-lease-ttl=30m -max-lease-ttl=2h userpass/
bao read sys/auth/userpass/tune
bao auth list -detailed

Expected (abridged):

Success! Tuned the auth method at: userpass/
Key                  Value
---                  -----
default_lease_ttl    30m
max_lease_ttl        2h
token_type           default-service
Path         Plugin      Accessor                  Default TTL    Max TTL    ...
approle/     approle     auth_approle_e866d912     system         system     ...
token/       token       auth_token_c7cfa6a7       system         system     ...
userpass/    userpass    auth_userpass_75a6bdfb    1800           7200       ...

A new user without their own token_ttl now inherits 30 minutes:

bao write auth/userpass/users/anna password=lab-pw-anna token_policies=webshop-read
bao write -format=json auth/userpass/login/anna password=lab-pw-anna \
  | jq .auth.lease_duration

Expected:

1800

Save your progress? Sign up for free

Checkpoint

export BAO_TOKEN=root
R=$(bao read -field=role_id auth/approle/role/webshop/role-id)
W=$(bao write -wrap-ttl=2m -field=wrapping_token -f auth/approle/role/webshop/secret-id)
SID=$(BAO_TOKEN=$W bao unwrap -field=secret_id)
T=$(bao write -field=token auth/approle/login role_id=$R secret_id=$SID)
[ -n "$T" ] && echo "✔ AppRole-Login mit Wrapped SecretID" || echo "✘ AppRole-Login"
[ "$(BAO_TOKEN=$T bao kv get -mount=secret -field=db_user webshop/config)" = webshop ] \
  && echo "✔ webshop liest Secret" || echo "✘ Secret lesen"
bao auth list | grep -q '^userpass/' && echo "✔ userpass" || echo "✘ userpass"
[ "$(bao read -field=default_lease_ttl sys/auth/userpass/tune)" = 1800 ] \
  && echo "✔ userpass-TTL 30m" || echo "✘ userpass-TTL"

Challenge

Create the AppRole batch-job. Its SecretID should allow 3 logins, and its tokens should end hard after 5 minutes, without renewal. Prove that the fourth login fails.

Hint: Setting token_max_ttl equal to token_ttl prevents any renewal beyond the initial TTL.

Solution

bao write auth/approle/role/batch-job token_policies=webshop-read \
  token_ttl=5m token_max_ttl=5m secret_id_num_uses=3 secret_id_ttl=10m
R=$(bao read -field=role_id auth/approle/role/batch-job/role-id)
S=$(bao write -f -field=secret_id auth/approle/role/batch-job/secret-id)
for i in 1 2 3 4; do
  bao write -field=token auth/approle/login role_id=$R secret_id=$S >/dev/null 2>&1 \
    && echo "Login $i ✔" || echo "Login $i ✘"
done

Expected:

Success! Data written to: auth/approle/role/batch-job
Login 1 ✔
Login 2 ✔
Login 3 ✔
Login 4 ✘

Save your progress? Sign up for free

Enterprise Note

  • Deliver the RoleID and SecretID over two different channels: the RoleID via config management, the SecretID via wrapping from CI.
  • Enforce wrapping by policy with min_wrapping_ttl. Alert when an unwrap fails or creation_path does not match (audit log, Days 6 and 12).
  • In Kubernetes, use Kubernetes auth (Day 11) instead of AppRole. Then there is no secret zero.
  • userpass does not belong in production. Use OIDC or LDAP with MFA and group mapping (Day 6). Since v2.7.0, LDAP is no longer built in but is a plugin from openbao-plugins.
  • Set secret_id_bound_cidrs and token_bound_cidrs to real source networks, otherwise a stolen SecretID can be used anywhere.