Day 6: Identity, Groups and Audit
Goal: Map several logins to one person, grant permissions through groups and prove every access in the audit log · Duration: approx. 90 min · Prerequisite: Day 3
Briefing
- Entity = a person or a service. Alias = their login in an auth method.
- Policies on an entity or group end up as
identity_policiesin every token – no matter which method was used to log in. - Internal groups collect entities and grant shared policies.
- Audit devices log every request and response. Secrets appear only as HMAC.
- In OpenBao 2.7, audit devices are created declaratively in the server configuration, not via the API.
Entity "thomas" (policy webshop-read)
├─ Alias userpass/thomas
├─ Alias approle/<role_id>
└─ Member of group "platform-team" (policy ops-admin)
Drill 1: Dev Server with an Audit Configuration
mkdir -p ~/bao-lab/tag06 && cd ~/bao-lab/tag06
cat > audit.hcl <<EOF
audit "file" "file" {
description = "Lab-Audit-Log"
options {
file_path = "$HOME/bao-lab/tag06/audit.log"
}
}
EOF
cat audit.hclWhy an unquoted EOF? $HOME must be
substituted while writing – OpenBao expands neither ~ nor
variables.
Terminal 1:
bao server -dev -dev-root-token-id=root -config=$HOME/bao-lab/tag06/audit.hclTerminal 2:
cd ~/bao-lab/tag06
export BAO_ADDR=http://127.0.0.1:8200 BAO_TOKEN=root
bao audit list -detailedExpected (abridged):
Path Type Description Replication Options
---- ---- ----------- ----------- -------
file/ file Lab-Audit-Log replicated file_path=.../tag06/audit.log
In the log of Terminal 1:
[INFO] core: enabled audit backend: path=file/ type=file
Save your progress? Sign up for free
Drill 2: The API Route Is Blocked
bao audit enable file file_path=/tmp/audit.log
bao audit disable fileExpected (abridged):
Error enabling audit device: Error making API request.
...
* cannot enable audit device via API; use declarative, config-based audit device
management instead
...
* cannot disable configuration-managed audit device
Why? Anyone who can put an audit device on an arbitrary path via the API can write files on the server. That is why in OpenBao (tested with 2.7.1) it is a matter of configuration.
Warning: The configuration option
unsafe_allow_api_audit_creation = truere-enables the old route. Only for migrations, never permanently.
Save your progress? Sign up for free
Drill 3: Prepare Logins
bao auth enable userpass
bao auth enable approle
# Lab password
bao write auth/userpass/users/thomas password=lab-pw-thomas token_policies=default
bao write auth/approle/role/webshop token_policies=default
bao policy write webshop-read - <<'EOF'
path "secret/data/webshop/*" {
capabilities = ["read"]
}
EOF
bao policy write ops-admin - <<'EOF'
path "sys/mounts" {
capabilities = ["read"]
}
EOF
bao kv put -mount=secret webshop/config db_host=db.webshop.labExpected (abridged):
Success! Enabled userpass auth method at: userpass/
Success! Enabled approle auth method at: approle/
Success! Data written to: auth/userpass/users/thomas
Success! Data written to: auth/approle/role/webshop
Success! Uploaded policy: webshop-read
Success! Uploaded policy: ops-admin
Save your progress? Sign up for free
Drill 4: Entity and Two Aliases
Scenario: Thomas logs in interactively via userpass, his CI scripts via AppRole. Both should be one identity.
bao write identity/entity name=thomas policies=webshop-read metadata=team=platform
ENT=$(bao read -field=id identity/entity/name/thomas)
UP=$(bao auth list -format=json | jq -r '."userpass/".accessor')
AR=$(bao auth list -format=json | jq -r '."approle/".accessor')
RID=$(bao read -field=role_id auth/approle/role/webshop/role-id)
echo "$ENT $UP $AR $RID"
bao write identity/entity-alias name=thomas canonical_id="$ENT" mount_accessor="$UP"
bao write identity/entity-alias name="$RID" canonical_id="$ENT" mount_accessor="$AR"Expected (abridged):
Key Value
--- -----
aliases <nil>
id 83a2bcc0-6365-3193-f308-6b054a2e0503
name thomas
83a2bcc0-... auth_userpass_64fa3a5d auth_approle_51344df3 78e42b65-f57d-...
Key Value
--- -----
canonical_id 83a2bcc0-6365-3193-f308-6b054a2e0503
id 21370341-2799-0971-7c74-e749258e862a
...
Why role_id? The alias name must match what the auth
method supplies as the name: for userpass the username, for AppRole the
role_id.
Save your progress? Sign up for free
Drill 5: Same Identity, Whatever the Login
T1=$(bao login -method=userpass -no-store -field=token \
username=thomas password=lab-pw-thomas)
SID=$(bao write -f -field=secret_id auth/approle/role/webshop/secret-id)
T2=$(bao write -field=token auth/approle/login role_id="$RID" secret_id="$SID")
for T in $T1 $T2; do
BAO_TOKEN=$T bao token lookup -format=json \
| jq -c '.data | {entity_id, policies, identity_policies}'
done
BAO_TOKEN=$T2 bao kv get -mount=secret -field=db_host webshop/config; echoExpected (abridged):
The token was not stored in token helper. Set the BAO_TOKEN environment
variable or pass the token below with each request to Vault.
{"entity_id":"83a2bcc0-...","policies":["default"],"identity_policies":["webshop-read"]}
{"entity_id":"83a2bcc0-...","policies":["default"],"identity_policies":["webshop-read"]}
db.webshop.lab
Why? The auth methods only grant default;
webshop-read comes through the entity.
Save your progress? Sign up for free
Drill 6: Internal Group
BAO_TOKEN=$T1 bao read sys/mounts
bao write identity/group name=platform-team type=internal \
policies=ops-admin member_entity_ids="$ENT" metadata=owner=platform
bao read identity/group/name/platform-team | grep -E '^name|^type|policies|member_entity'Expected (abridged):
Code: 403. Errors:
...
* permission denied
Key Value
--- -----
id 0acaef95-10e4-aca9-4349-36ce412ed2c8
name platform-team
member_entity_ids [83a2bcc0-6365-3193-f308-6b054a2e0503]
name platform-team
policies [ops-admin]
type internal
The same token again:
BAO_TOKEN=$T1 bao token lookup -format=json | jq -c .data.identity_policies
BAO_TOKEN=$T1 bao read sys/mounts >/dev/null && echo "sys/mounts OK"Expected:
["webshop-read","ops-admin"]
sys/mounts OK
Why without a new login? Identity policies are re-evaluated on every request – existing tokens receive group permissions immediately (and lose them just as immediately).
Save your progress? Sign up for free
Drill 7: identity lookup
Who is behind a login?
bao write identity/lookup/entity alias_name=thomas alias_mount_accessor="$UP" \
| grep -E '^name|^policies|group_ids'
bao read -format=json identity/entity/name/thomas \
| jq '.data | {name, group_ids, aliases: [.aliases[] | {name, mount_type}]}'Expected (abridged):
direct_group_ids [0acaef95-10e4-aca9-4349-36ce412ed2c8]
group_ids [0acaef95-10e4-aca9-4349-36ce412ed2c8]
inherited_group_ids []
name thomas
policies [webshop-read]
{
"name": "thomas",
"group_ids": [
"0acaef95-10e4-aca9-4349-36ce412ed2c8"
],
"aliases": [
{ "name": "thomas", "mount_type": "userpass" },
{ "name": "78e42b65-f57d-d9b6-dfe6-ec20cb9d5335", "mount_type": "approle" }
]
}
Save your progress? Sign up for free
Drill 8: Read the Audit Log with jq
Every request produces two lines: request and
response.
bao kv put -mount=secret webshop/api key=lab-api-key-123 >/dev/null
tail -n 2 audit.log | jq -c '{type, path: .request.path, op: .request.operation}'
tail -n 1 audit.log | jq '{type, auth: {display_name: .auth.display_name,
client_token: .auth.client_token}, data: .request.data.data}'Expected (abridged):
{"type":"request","path":"secret/data/webshop/api","op":"create"}
{"type":"response","path":"secret/data/webshop/api","op":"create"}
{
"type": "response",
"auth": {
"display_name": "token",
"client_token": "hmac-sha256:2616579cf63515c302eb664526795d32910c1fed98eaa49cba..."
},
"data": {
"key": "hmac-sha256:95016fd2c3da41aa946b8c7143377cc9ab02a3d2022a3ff80958e966..."
}
}
Why HMAC? Tokens, passwords and secret values never appear in plain text in the log – yet you can still recognize them (Drill 9).
Useful queries:
# all denied requests
jq -r 'select(.type=="response" and .error != null)
| [.time, .request.path, .error] | @tsv' audit.log
# what did Thomas do (all logins)
jq -r --arg e "$ENT" 'select(.type=="response" and .auth.entity_id==$e)
| [.time, .auth.display_name, .request.path] | @tsv' audit.log | tail -4
# the login password is hashed too
jq -c 'select(.type=="request" and .request.path=="auth/userpass/login/thomas")
| .request.data' audit.log | head -1Expected (abridged):
2026-10-08T07:00:05.939609Z sys/mounts 1 error occurred:\n\t* permission denied\n\n
2026-10-08T06:59:52.367472Z approle secret/data/webshop/config
2026-10-08T06:59:58.996794Z userpass-thomas auth/userpass/login/thomas
2026-10-08T06:59:59.060252Z userpass-thomas auth/token/lookup-self
2026-10-08T06:59:59.123846Z userpass-thomas sys/mounts
{"password":"hmac-sha256:70ec037387f5b2277121afdc43be9dae2de58eb83eed149a9d2e5..."}
Save your progress? Sign up for free
Drill 9: audit-hash – Find a Secret in the Log
A forensics question: “Was the API key lab-api-key-123
written or read?”
H=$(bao write -field=hash sys/audit-hash/file input=lab-api-key-123)
echo "$H"
grep -c "$H" audit.logExpected:
hmac-sha256:95016fd2c3da41aa946b8c7143377cc9ab02a3d2022a3ff80958e96640b50639
4
Why 4? Request and response of kv put – plus request and
response of the audit-hash call itself, because its
input is also logged as a hash.
Why per device? Every audit device has its own HMAC salt, hence the
device path (file) in the endpoint.
Save your progress? Sign up for free
Drill 10: A Second Device via SIGHUP
cat >> audit.hcl <<'EOF'
audit "file" "stdout" {
options {
file_path = "stdout"
hmac_accessor = "false"
}
}
EOF
kill -HUP "$(pgrep -f 'bao server -dev')"
sleep 1
bao audit listExpected:
Path Type Description
---- ---- -----------
file/ file Lab-Audit-Log
stdout/ file n/a
From now on, Terminal 1 shows every request as JSON. Because of
hmac_accessor=false, the token accessor field
appears there in plain text.
Warning: If no audit device is writable, OpenBao refuses all requests. Run at least two devices on different targets.
Save your progress? Sign up for free
Checkpoint
#!/usr/bin/env bash
check() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"; else echo "✘ $1"; fi; }
ENT=$(bao read -field=id identity/entity/name/thomas 2>/dev/null)
check "Entity thomas existiert" "[ -n '$ENT' ]"
check "Entity hat 2 Aliases" \
"bao read -format=json identity/entity/name/thomas \
| jq -e '.data.aliases|length == 2'"
check "Gruppe platform-team enthält thomas" \
"bao read -format=json identity/group/name/platform-team | jq -e --arg e '$ENT' \
'.data.member_entity_ids|index(\$e)'"
check "Audit-Device file aktiv" "bao audit list | grep -q '^file/'"
check "Audit-Log enthält Einträge" "[ -s ~/bao-lab/tag06/audit.log ]"Challenge
Create the user anna (userpass) with her own entity, add
her to platform-team and then find all paths in the audit
log that Anna called.
Hint: member_entity_ids replaces the
list – specify both IDs.
Solution
bao write auth/userpass/users/anna password=lab-pw-anna token_policies=default
bao write identity/entity name=anna
ANNA=$(bao read -field=id identity/entity/name/anna)
bao write identity/entity-alias name=anna canonical_id="$ANNA" mount_accessor="$UP"
bao write identity/group/name/platform-team member_entity_ids="$ENT,$ANNA"
TA=$(bao login -method=userpass -no-store -field=token username=anna password=lab-pw-anna)
BAO_TOKEN=$TA bao read sys/mounts >/dev/null && echo "anna: sys/mounts OK"
jq -r --arg e "$ANNA" 'select(.type=="request" and .auth.entity_id==$e)
| .request.path' audit.log | sort -uExpected (abridged, may differ):
anna: sys/mounts OK
sys/mounts
Save your progress? Sign up for free
Enterprise Note
- Don’t maintain entities by hand: OIDC/LDAP logins create entities automatically; external groups mirror IdP groups (Day 13).
- Audit devices belong in the versioned server configuration; apply changes via SIGHUP or a rolling restart (Day 12).
- Collect the audit log centrally (Fluent Bit/Vector → SIEM), rotate logs with SIGHUP, monitor disk usage.
- A second device (e.g.
socketorsyslog) as a fallback – otherwise a full volume blocks the entire cluster. - The audit log is sensitive: HMAC protects only values, not paths, metadata or entity IDs.