OpenBao holds the credentials that unlock everything else, so a poorly planned seal, a lingering root token or a silent audit gap turns one server into the most valuable target in the estate. OpenBao is an identity-based secrets and encryption management system, an OpenSSF Sandbox project distributed under the Mozilla Public License 2.0, that stores static secrets, issues dynamic credentials with leases, and encrypts data on behalf of applications. This guide covers the customer-side settings that decide how secure a deployment is: seal and unseal design, root token handling, listener and TLS configuration, audit devices, policies and namespaces, storage and recovery, and the controls to keep in place when moving an existing cluster onto OpenBao. It is written for platform, security and identity engineers running OpenBao in production or planning to.
This is an independent guide from NHI Mgmt Group, based on OpenBao's public documentation as of November 2026. It is not sponsored or reviewed by the OpenBao project. Product features change, so confirm settings against OpenBao's current documentation.
Key takeaways
- Design the seal before the first init. The seal decides who can bring OpenBao back after a restart; with Auto Unseal, permanently losing the KMS or HSM key means the cluster cannot be recovered, even from backups.
- Revoke the initial root token after setup. The project recommends using root tokens only for initial setup or emergencies and revoking them immediately, generating a new one with
bao operator generate-rootand a quorum when needed. - Run at least two audit devices. OpenBao stops answering requests when no enabled audit device can record them, which protects accountability but makes a single audit device an availability risk.
- Keep the listener defaults that protect you. Unauthenticated rekey and generate-root endpoints are disabled by default in current releases, metrics and profiling endpoints require authentication by default, and TLS 1.2 is the default minimum.
- Treat migration as a change with a rollback plan. The project's migration guide is tested for specific versions, Raft storage and Shamir seals; inventory mounts first because mounts without an included plugin are skipped at startup.
Security model: what OpenBao protects and what you must
OpenBao's documented threat model covers eavesdropping on client, storage and cluster traffic, tampering with data at rest or in transit, access without authentication or authorisation, access without accountability (if audit logging is enabled, requests and responses must be logged before the client receives secret material), confidentiality of stored data and availability through high availability. The same page lists what is out of scope, and each item is a customer-side responsibility.
| Out of scope in the OpenBao threat model | What this means in practice | Customer-side control |
|---|---|---|
| Arbitrary control of the storage backend | Whoever controls storage can delete data or roll state back | Restrict storage access to OpenBao nodes, encrypted and access-logged snapshots, separate storage administrators |
| Leakage of the existence of secret material | Storage readers can see that secrets exist and roughly where | Treat storage as sensitive, avoid revealing names in mount paths |
| Memory analysis of a running server | Host memory access can expose decrypted data | Dedicated hosts, no shared tenancy, swap disabled or encrypted, core dumps off |
| Flaws in external systems used by OpenBao | A compromised identity provider issuing malicious JWT claims, or a database whose admin is compromised | Harden and monitor identity providers and targets of dynamic secrets |
| Malicious plugins or code execution on the host | Host write access undermines integrity | Signed and pinned plugins, minimal host access, immutable images |
| Flaws in clients that access OpenBao | A stolen client token works at that client's privilege | Short token TTLs, narrow policies, workload authentication rather than static tokens |
The practical reading: OpenBao protects secrets well inside its boundary, and the boundary is the host, the storage and the identities you let in. See the Secrets Management Guide for the wider programme this sits in.
Seal and unseal design
Data is encrypted with an encryption key held in the keyring; the keyring is encrypted by the root key; and the root key is encrypted by the unseal key. A server starts sealed and can do almost nothing except unseal and report seal status until the root key is recovered.
| Option | How it works | Strengths | Operational risk to manage |
|---|---|---|---|
| Shamir seal (default) | Unseal key split into shares; a threshold of shares reconstructs it. Each node must be unsealed separately. | No external dependency; quorum of people required | Manual unseal after every restart; share holders must be available and trained |
| Auto Unseal (KMS or HSM) | The seal stanza delegates root key decryption to an HSM or cloud KMS; initialisation yields recovery keys instead of unseal keys | Unattended restarts, keys held in hardened devices | Strict lifecycle dependency: if the seal key is permanently deleted, the cluster cannot be recovered, even from backups |
| Static key auto-unseal | A static key held in another store (the docs give Kubernetes Secrets as an example) unseals automatically | Avoids scripting the Shamir process, which the docs discourage | Security now equals the security of that static key store |
- Recovery keys are authorisation only: with Auto Unseal, recovery keys authorise quorum operations such as generating a root token, but they cannot decrypt the root key and cannot unseal the cluster if the seal mechanism is unavailable.
- Protect the seal key like the crown jewels: the documentation recommends careful controls around the seal mechanism, such as organisation-level policies that prevent deletion of the KMS key. Add deletion protection, separate key administrators from OpenBao administrators and alert on any key policy change.
- Plugin seals: from OpenBao v2.6.0, Auto Unseal mechanisms can be installed as external KMS plugins, and the seal documentation notes that in v2.7.0 many vendor-specific mechanisms move out of the standalone binary to plugins. Check the deprecation notice before upgrading a cluster that relies on a built-in seal.
- Emergency seal: the seal API discards the root key from memory and requires a fresh unseal. It needs a single operator with root privileges, so include it in the incident response plan as the fastest way to lock data after a detected intrusion.
The design question is the same as for any bootstrap credential. See the Secrets Zero Problem Guide.
Root tokens, quorum operations and break-glass
Root tokens carry the root policy and can do anything; they are the only tokens that can be set to never expire without renewal. They can be created in three ways: the initial root token from bao operator init (no expiration), another root token, or bao operator generate-root with a quorum of unseal or recovery key holders.
- Use the initial root token only to bootstrap: enable an administrator auth method, write administrator policies, enable audit devices, then revoke it.
- Prefer declarative self-initialisation for repeatable builds: the
initializestanza provisions audit, auth and secret mounts on first start from configuration, so the initial root token never has to be handled interactively. The documentation warns thatTRACElogging during self-initialisation records request and response pairs and therefore contains sensitive information. - Keep administrators off root: give named administrators scoped policies through an auth method tied to your identity provider, with MFA at the provider.
- Treat generate-root as break-glass: require at least two people, record the session, and revoke the token when the task ends. The documentation advises multiple eyes on a terminal whenever a root token is in use.
- Keep the unauthenticated endpoints closed:
disable_unauthed_generate_root_endpointsdefaults to true from v2.5.3 anddisable_unauthed_rekey_endpointsdefaults to true from v2.5.0. Leave both set; the docs describe the legacy endpoints as a security risk on public listeners.
See the Break-Glass Account Guide for the surrounding procedure.
Listener and TLS configuration
The tcp listener stanza holds most of the network-facing settings. These are the ones to set and verify on every node.
| Parameter | Documented default | Recommended setting |
|---|---|---|
tls_disable | false | Leave false; terminate TLS on OpenBao itself, end to end |
tls_min_version | tls12 | tls12 or tls13; the docs warn that TLS 1.1 and lower are widely considered insecure |
tls_require_and_verify_client_cert | false | Turn on for listeners serving only known workloads, with tls_client_ca_file |
address / cluster_address | 127.0.0.1:8200 / 127.0.0.1:8201 | Bind client and cluster traffic to separate interfaces; firewall 8201 to cluster peers only |
x_forwarded_for_authorized_addrs | Unset (required to enable) | Set only to your load balancer addresses so client IPs in audit logs are trustworthy |
unauthenticated_metrics_access | false | Keep false; or use a dedicated metrics_only listener for monitoring and disallow_metrics on client listeners |
unauthenticated_pprof_access | false | Keep false in production |
unauthenticated_in_flight_requests_access | false | Keep false |
max_request_size / max_request_duration | 33554432 bytes / 90s | Keep or lower to match real payloads |
OpenBao no longer uses mlock as of 2.0.0 (the migration guide asks you to remove disable_mlock from older configurations), so protect memory at the host: disable swap or use encrypted swap, disable core dumps for the service, and run OpenBao as a dedicated unprivileged user on a single-purpose host.
Audit devices
Audit logs are the record of who read which secret, and OpenBao treats them as part of the security boundary.
- Fail-closed behaviour: OpenBao will not respond to requests when no enabled audit device can record them. With multiple devices, a request succeeds if at least one device writes the record, unless a device fails in a blocking way (a write that never completes), in which case requests wait until it can write. The documentation highly recommends configuring multiple audit devices.
- Hashing: most strings in requests and responses are hashed with a salted HMAC-SHA256 so secrets are not in plaintext in logs. Keep
log_rawat its default of false andhmac_accessorat its default of true. Once an audit device is disabled, you can no longer HMAC values for comparison with its old entries, so do not disable and re-enable devices casually. - Configuration-managed audit: from v2.3.2, creating audit devices through the API requires
unsafe_allow_api_audit_creation = truein server configuration, because API creation can write files at arbitrary host paths or send network requests to arbitrary addresses. Define audit devices in the server configuration (theauditstanza) and leave the unsafe flag off. Likewise leaveallow_audit_log_prefixingoff unless you need theprefixoption. - Cluster-wide replication: audit device configuration is replicated to all nodes by default, so confirm every node can reach the destination before enabling a device, or the cluster may be blocked from serving requests. The
skip_testoption exists, but the default probe protects you from enabling a device that cannot write. - Large list responses:
elide_list_responseskeeps list bodies out of audit records where a backend cannot handle large entries; weigh this against investigation needs.
Ship audit logs to a separate log platform with its own administrators, so an OpenBao administrator cannot alter the record of their own actions.
Policies, auth methods and namespaces
- Deny by default: policies are deny by default, so an empty policy grants nothing. Write path-based policies with the minimum capabilities (
read,list,create,update,patch,delete,scan, plussudofor root-protected paths) and use explicitdenyfor sensitive paths such assys/where broad globs are unavoidable. - Be careful with list and scan: the policy documentation notes that listing always operates on a prefix, so these capabilities must be granted on prefix paths. Grant them separately from read and only where a caller genuinely needs to enumerate key names.
- Workload authentication: the auth method documentation describes Userpass as easiest on developer machines and AppRole as the recommended choice for servers. Where the platform provides identity (Kubernetes service accounts, JWT/OIDC from a CI system, client certificates), bind roles to those claims so no static secret has to be delivered. See the Dynamic Secrets and Ephemeral Credentials Guide.
- Token shape: OpenBao tokens use the prefixes
s.(service),b.(batch) andr.(recovery) and match[sbr]\.[a-zA-Z0-9]{24,}. Add that pattern to secret scanning in repositories, chat and ticketing so leaked tokens are caught. - Namespaces for tenancy: namespaces create isolated environments with their own secret engines, auth methods, policies, entities, groups and tokens, so a platform team can delegate administration per tenant. Child namespaces can inherit elements from parents, so review parent-level policies and groups for unintended reach into children.
Running OpenBao for Kubernetes workloads raises the delivery question (sidecar, CSI driver, operator sync to native Secrets). See Kubernetes Secrets vs External Secret Stores.
Storage, backup and recovery
- Choose the backend deliberately: OpenBao supports Integrated Storage (Raft) and PostgreSQL, and the storage documentation recommends PostgreSQL as an easier backend to operate safely than Raft. Either way, restrict backend access to OpenBao nodes, since control of storage is outside the threat model.
- Snapshots: take Raft snapshots or atomic filesystem snapshots on a schedule, encrypt them, store them away from the cluster and test restores. A snapshot is only restorable while the seal key or unseal shares that protect it still exist.
- Recovery mode: starting a node with
-recoveryallowssys/rawaccess with a single, non-persisted recovery token for repairing storage. It shrinks a Raft cluster to one node, which must be reformed afterwards. Restrict who can restart nodes with this flag and alert on it. - Updates: apply OpenBao security updates promptly and follow the project's security advisories.
Planning a migration onto OpenBao
The OpenBao project publishes an in-place migration guide for clusters running the upstream Community Edition codebase it was forked from. OpenBao replaces the server process on each node and all configuration, endpoints and URLs stay the same. The guide's tested scope is narrow, so plan around it.
| Area | What the migration guide states | Security action |
|---|---|---|
| Versions | Tested from upstream release 1.14.1 (Community Edition) to OpenBao 2.2.0; older clusters upgrade to 1.14.1 first; newer upstream versions are untested with no storage compatibility guarantee; Enterprise editions untested | Pin both versions in the change record; test on a restored copy first |
| Storage and seal | Tested with Raft and Shamir; Auto Unseal not covered; clusters bootstrapped before upstream 1.3 may need a rekey | Plan seal migration as a separate change; verify key holders are available |
| Plugins | Mounts whose plugin OpenBao does not include are skipped at startup and reads return no value | Inventory with secrets list and auth list beforehand; move or disable those mounts after handling their data |
| Tokens | New tokens use the OpenBao [sbr]. format; existing tokens stay valid until their TTL expires | Update secret scanners and any client that parses token format |
| Configuration | Largely compatible; remove disable_mlock; use a separate storage path per node | Review the config against current OpenBao defaults, including audit and listener settings above |
| Audit file | OpenBao must be able to write to the existing audit file | Fix ownership after stopping the old service so audit never lapses |
- Take a Raft or atomic filesystem snapshot and confirm it restores.
- Install and configure OpenBao on every node without starting it, using a different storage path to make rollback easier.
- Upgrade followers one at a time: stop the old service, start OpenBao, join with
bao operator raft join, unseal, and confirm voter status withbao operator raft list-peers. - Step the leader down, confirm a new leader, then upgrade the former leader last.
- After cutover, re-run the hardening review: listener flags, audit device configuration, root token revocation and policy review.
- Roll back by restoring the snapshot onto the original service if validation fails; the separate storage path keeps the original data intact.
Detection and measurement
Feed audit logs and server logs to the SOC and alert on these events: root token creation or use, generate-root or rekey operations, seal and unseal events, audit device enable or disable, policy writes to administrative paths, auth method changes, recovery mode starts, and spikes in permission-denied responses for a single identity.
- Root token count: active root tokens outside a recorded break-glass window. Target: zero.
- Audit redundancy: nodes with at least two healthy audit devices. Target: 100%.
- Static credential share: percentage of workloads authenticating with platform identity (Kubernetes, JWT/OIDC, certificates) rather than long-lived tokens or secret IDs.
- Dynamic secret coverage: share of database and cloud credentials issued with leases rather than stored statically.
- Restore test age: days since a snapshot was last restored successfully.
- Patch latency: days from an OpenBao security release to deployment.
Common failure patterns
- Keeping the initial root token "just in case", stored in a wiki or CI variable where it outlives everyone's memory of it.
- A single audit device on a network destination, so an outage at the log platform stops every application that reads secrets.
- Treating the KMS key as ordinary cloud configuration, so a clean-up script or account closure deletes the seal key and makes every backup unusable.
- Turning on API audit creation or unauthenticated metrics to fix a deployment problem and never turning them off.
- Broad globs in administrator policies, such as full capabilities on
*, recreating root by another name. - Migrating without a mount inventory, discovering after cutover that a secrets engine is skipped and applications receive no value.
Framework mapping
| OpenBao control | NIST SP 800-53 Rev 5 | NIST CSF 2.0 |
|---|---|---|
| Seal design, KMS key protection | SC-12 Cryptographic Key Establishment and Management, SC-28 Protection of Information at Rest | PR.DS-01 |
| Root token revocation, scoped admin policies | AC-6 Least Privilege, AC-3 Access Enforcement | PR.AA-05 |
| Workload auth methods, short TTLs, dynamic secrets | IA-5 Authenticator Management, IA-9 Service Identification and Authentication | PR.AA-05 |
| TLS on listeners and cluster traffic | SC-8 Transmission Confidentiality and Integrity | PR.DS-02 |
| Multiple audit devices, external log store | AU-2 Event Logging, AU-9 Protection of Audit Information, AU-12 Audit Record Generation | DE.CM-09 |
| Declarative configuration, migration change control | CM-3 Configuration Change Control | PR.PS-01 |
| Snapshots and restore tests | CP-9 System Backup | PR.DS-11 |
| Security updates | SI-2 Flaw Remediation | PR.PS-02 |
Practitioner checklist
- Decide Shamir or Auto Unseal before initialisation, and put deletion protection and separate administration on any seal key.
- Revoke the initial root token after bootstrap and document the
generate-rootbreak-glass procedure. - Confirm
disable_unauthed_generate_root_endpointsanddisable_unauthed_rekey_endpointsare true on every listener. - Set
tls_min_versionto tls12 or tls13 and keep metrics, pprof and in-flight endpoints authenticated. - Define at least two audit devices in server configuration and leave
unsafe_allow_api_audit_creationoff. - Write deny-by-default policies, grant list and scan separately, and keep administrators off root.
- Authenticate workloads with platform identity and add the
[sbr].token pattern to secret scanning. - Snapshot on a schedule, encrypt and store off-cluster, and test a restore each quarter.
- For migrations, inventory mounts, pin tested versions and keep a separate storage path for rollback.
Standards and references
- OpenBao: Security model
- OpenBao: Seal/Unseal
- OpenBao: Seal configuration
- OpenBao: Audit devices
- OpenBao: TCP listener configuration
- OpenBao: Tokens
- OpenBao: Policies
- OpenBao: Migration guide
- NIST: SP 800-53 Rev. 5 Security and Privacy Controls
Related NHI Mgmt Group resources: Secrets Management Guide · Secrets Zero Problem Guide · Dynamic Secrets and Ephemeral Credentials Guide · Kubernetes Secrets vs External Secret Stores