Skip to content
Hands-on IT IT Drills

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_policies in 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.hcl

Why 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.hcl

Terminal 2:

cd ~/bao-lab/tag06
export BAO_ADDR=http://127.0.0.1:8200 BAO_TOKEN=root
bao audit list -detailed

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

Expected (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 = true re-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.lab

Expected (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; echo

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

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

Expected:

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 list

Expected:

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 -u

Expected (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. socket or syslog) 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.