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-1Expected (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/thomasExpected (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; echoExpected (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=rootExpected:
{"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/webshopExpected (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-idExpected:
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_IDExpected (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=approlereportsUnknown 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/32Expected (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-idExpected:
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 unwrapExpected (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_tokendoes not work. It reportsNo data found. Use-format=jsonand.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-idExpected (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 -detailedExpected (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_durationExpected:
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 ✘"
doneExpected:
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 orcreation_pathdoes 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_cidrsandtoken_bound_cidrsto real source networks, otherwise a stolen SecretID can be used anywhere.