Store and use everyday secrets with KV v2
Goal: keep static credentials in a versioned secret store and give people/applications only the paths they need. Prerequisites: a running server, named administrator access, and configured BAO_ADDR/CA trust.
Use this for API tokens, database passwords, registry credentials, configuration values and carefully controlled legacy SSH keys. For Linux access, prefer short-lived SSH certificates; for containers, use the Agent and Docker example.
1. Enable a versioned KV mount
As an OpenBao administrator, inspect existing engines first:
If there is no secret/ mount, create a new KV v2 engine:
Do not rerun enable against an existing mount. If secret/ already exists, confirm it is KV version 2. A v1→v2 upgrade changes API/policy paths and requires migration planning.
secret/config configures the engine. bao kv put -mount=secret team/demo ... writes an application secret; these are not the same operation.
2. Create a demo secret without logging its value
Generate a token for this local demonstration, not for a real upstream API:
The value travels through stdin; no literal secret is in the command or shell history. -cas=0 means “create only if this key has never existed.” If it already exists, inspect metadata instead of overwriting it blindly.
For several typed fields, load a protected JSON file. Example contents (placeholders only):
{
"username": "demo-app",
"password": "REPLACE_WITH_REAL_VALUE",
"database": "demo",
"enabled": true
}
Create the real file outside the repository with umask 077, protect it, and load it without echoing its contents:
bao kv put accepts the secret object directly. The raw HTTP API instead expects a data envelope. JSON preserves booleans/numbers; CLI key=value parameters normally become strings.
Do not turn a secret manager into a secret printer
bao kv get prints secret values by default. Use it only in a trusted, non-recorded terminal when inspection is necessary. Prefer metadata for checks and redirect field reads straight to a protected consumer file. Avoid set -x, tee, screenshots and pasting real credentials into docs or tickets.
3. Read, update and recover versions
Inspect history without displaying the secret payload:
To deliver one field to a temporary private file on a trusted Linux host:
umask 077
SECRET_FILE=$(mktemp)
bao kv get -mount=secret -field=api_token team/demo > "$SECRET_FILE"
test -s "$SECRET_FILE"
# Supply this file to the intended consumer, then remove it.
rm -f "$SECRET_FILE"
On a never-modified example, version 1 is current. Rotate the demo value using compare-and-set:
openssl rand -hex 32 | bao kv put -mount=secret -cas=1 team/demo api_token=-
bao kv metadata get -mount=secret team/demo
For later writes, use the actual current version from metadata. A CAS failure means someone changed the key since your read. kv put replaces the whole object; use kv patch for a partial change when you have the patch permission:
This patch example assumes the database secret is still at version 1. To read an older retained version into a protected file:
umask 077
OLD_SECRET_FILE=$(mktemp)
bao kv get -mount=secret -version=1 -field=api_token team/demo > "$OLD_SECRET_FILE"
# Use only for a controlled recovery step; it may be an obsolete credential.
rm -f "$OLD_SECRET_FILE"
Delete is not destroy or upstream revocation
The following are optional cleanup examples, not commands to run before the later tutorials:
bao kv delete -mount=secret -versions=1 team/demo
bao kv undelete -mount=secret -versions=1 team/demo
These soft-delete and restore version 1. Permanent operations require extra care:
Permanent deletion
kv destroy irreversibly destroys the selected version in the live store. kv metadata delete removes all versions and metadata for that key. Existing snapshots or other copies may still retain it. Neither command revokes the actual password/token at its upstream service.
bao kv destroy -mount=secret -versions=1 team/demo
# Alternative: remove ALL versions and metadata for this demo key.
bao kv metadata delete -mount=secret team/demo
Setting a retention limit eventually destroys older versions; it does not provide a permanent archive or expire credentials at their source. Rotate/revoke a real API token or password at its provider, update OpenBao, refresh consumers, then handle retained old versions according to your recovery policy.
4. Give a person scoped CLI and UI access
As administrator, create team-secrets. It manages only team/* data, and lists enough metadata for UI browsing. It cannot destroy versions or administer the platform:
bao policy write team-secrets - <<'HCL'
path "secret/data/team/*" {
capabilities = ["create", "read", "update", "patch", "delete"]
}
path "secret/metadata/team/*" {
capabilities = ["read", "list"]
}
path "secret/metadata/team" {
capabilities = ["list"]
}
path "secret/metadata" {
capabilities = ["list"]
}
HCL
The top-level metadata list permission reveals key names at that level. OpenBao list results are not filtered like secret reads; keep sensitive values out of key names. Remove broad browsing permissions if the person only needs direct CLI reads. Requests for unauthorized values remain denied.
Create a person using the userpass method already enabled in administration:
set +x
read -r -s -p 'New OpenBao password for alice: ' PASSWORD
printf '\n'
printf '%s' "$PASSWORD" | bao write auth/userpass/users/alice \
password=- token_policies=team-secrets token_ttl=1h token_max_ttl=8h
unset PASSWORD
Test as Alice in a separate shell/token cache, not the administrator shell:
export BAO_TOKEN_PATH="$HOME/.bao-alice-token"
unset BAO_TOKEN
bao login -no-print -method=userpass username=alice
bao token capabilities secret/data/team/demo
bao token capabilities secret/data/apps/docker-demo
Expect read/write capabilities for the first path and deny for the application path. Default token policy supports self-service token operations and UI introspection; do not remove it without checking the workflow.
In the browser, log in as Alice with userpass, open Secrets → secret, then team/demo. Create/edit the appropriate key/value fields and inspect version history. UI labels can change by release; permission checks are the same as the CLI. If browsing is denied, inspect the exact metadata path rather than assigning a platform-admin policy.
For a single read-only application, use an even narrower policy:
Attach that policy through the application's authentication method (AppRole in the Docker guide). The app does not need metadata listing, writes, policy administration or other app secrets.
5. Understand logical paths versus API paths
For a KV v2 secret at secret/apps/database:
| Context | Path / access |
|---|---|
| CLI | bao kv get -mount=secret apps/database |
| HTTP read | GET /v1/secret/data/apps/database |
| HTTP metadata | GET /v1/secret/metadata/apps/database |
| Read policy | secret/data/apps/database with read |
| Agent template | secret "secret/data/apps/database", values under .Data.data |
| API read response | Values under data.data |
Do not add data/ to a logical bao kv path. Do include it in raw API and ACL paths. Policy paths do not start with /v1/.
A raw HTTP KV v2 create request has this shape:
KV v2 policies restrict paths and operations, not individual JSON fields inside one secret. Store unrelated credentials under separate keys/paths if consumers need different access.
6. Other practical secret types
Registry credentials for Docker pulls
Create secret/infra/registry with username and password fields using a protected JSON input, then use Docker's stdin login support on a trusted deployment host:
REGISTRY_USER=$(bao kv get -mount=secret -field=username infra/registry)
bao kv get -mount=secret -field=password infra/registry \
| docker login registry.example.com --username "$REGISTRY_USER" --password-stdin
unset REGISTRY_USER
The username is assumed non-secret. Docker may persist login credentials in its config; configure an appropriate credential helper. This is a registry login, not a runtime Compose secret, and not an excuse to put credentials in a Dockerfile.
Legacy SSH private keys
Prefer SSH certificates: users keep their private keys locally and OpenBao signs only public keys. If a legacy automation system truly requires a shared private key, store it under a dedicated restricted path:
On the authorized consumer host:
umask 077
KEY_DIR=$(mktemp -d)
bao kv get -mount=secret -field=private_key infra/legacy-ssh > "$KEY_DIR/id_ed25519"
chmod 0600 "$KEY_DIR/id_ed25519"
ssh -o IdentitiesOnly=yes -i "$KEY_DIR/id_ed25519" [email protected]
rm -f "$KEY_DIR/id_ed25519"
rmdir "$KEY_DIR"
Keep normal SSH host-key verification. Protect this private-key path with an explicit read policy and rotate the key at the target hosts when needed. KV does not issue short-lived SSH credentials or remove old authorized_keys entries. File removal is not guaranteed secure erasure, and command failures can leave temporary files: handle cleanup in real automation.
Database passwords, PKI and encryption
- Static database credentials: KV can hold an existing password, but rotation must also update the database and consuming application. Render a connection config file rather than exposing a password in command-line arguments.
- Dynamic database credentials: the database engine can create leased, limited accounts with supported databases. Keep a long-running Agent/client and handle lease renewal, revocation and reconnects; the one-shot Docker KV example is not that design.
- TLS certificates: the PKI engine issues certificates under constrained roles. Plan CA custody, renewal and trust distribution before replacing your existing PKI.
- Encryption without exporting keys: Transit provides encryption/signing APIs; it does not store application ciphertext for you.
- CI/webhooks/cloud tokens: separate paths and workload policies, use provider-side expiration/rotation, and prefer dynamic/identity-based authentication where available.