Join our Newsletter — 33% off our NHI Course
Home› Guides› OpenBao Security Guide: Hardening the Open Source Secrets…
Guide Secrets Management

OpenBao Security Guide: Hardening the Open Source Secrets Manager and Planning a Migration

PDF for newsletter subscribers · free to read online

← All guides
By NHI Mgmt Group, edited by Lalit Choda Updated 14 November 2026 16 min read
On this page

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-root and 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 modelWhat this means in practiceCustomer-side control
Arbitrary control of the storage backendWhoever controls storage can delete data or roll state backRestrict storage access to OpenBao nodes, encrypted and access-logged snapshots, separate storage administrators
Leakage of the existence of secret materialStorage readers can see that secrets exist and roughly whereTreat storage as sensitive, avoid revealing names in mount paths
Memory analysis of a running serverHost memory access can expose decrypted dataDedicated hosts, no shared tenancy, swap disabled or encrypted, core dumps off
Flaws in external systems used by OpenBaoA compromised identity provider issuing malicious JWT claims, or a database whose admin is compromisedHarden and monitor identity providers and targets of dynamic secrets
Malicious plugins or code execution on the hostHost write access undermines integritySigned and pinned plugins, minimal host access, immutable images
Flaws in clients that access OpenBaoA stolen client token works at that client's privilegeShort 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.

OptionHow it worksStrengthsOperational 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 requiredManual 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 keysUnattended restarts, keys held in hardened devicesStrict lifecycle dependency: if the seal key is permanently deleted, the cluster cannot be recovered, even from backups
Static key auto-unsealA static key held in another store (the docs give Kubernetes Secrets as an example) unseals automaticallyAvoids scripting the Shamir process, which the docs discourageSecurity 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.

  1. Use the initial root token only to bootstrap: enable an administrator auth method, write administrator policies, enable audit devices, then revoke it.
  2. Prefer declarative self-initialisation for repeatable builds: the initialize stanza 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 that TRACE logging during self-initialisation records request and response pairs and therefore contains sensitive information.
  3. Keep administrators off root: give named administrators scoped policies through an auth method tied to your identity provider, with MFA at the provider.
  4. 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.
  5. Keep the unauthenticated endpoints closed: disable_unauthed_generate_root_endpoints defaults to true from v2.5.3 and disable_unauthed_rekey_endpoints defaults 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.

ParameterDocumented defaultRecommended setting
tls_disablefalseLeave false; terminate TLS on OpenBao itself, end to end
tls_min_versiontls12tls12 or tls13; the docs warn that TLS 1.1 and lower are widely considered insecure
tls_require_and_verify_client_certfalseTurn on for listeners serving only known workloads, with tls_client_ca_file
address / cluster_address127.0.0.1:8200 / 127.0.0.1:8201Bind client and cluster traffic to separate interfaces; firewall 8201 to cluster peers only
x_forwarded_for_authorized_addrsUnset (required to enable)Set only to your load balancer addresses so client IPs in audit logs are trustworthy
unauthenticated_metrics_accessfalseKeep false; or use a dedicated metrics_only listener for monitoring and disallow_metrics on client listeners
unauthenticated_pprof_accessfalseKeep false in production
unauthenticated_in_flight_requests_accessfalseKeep false
max_request_size / max_request_duration33554432 bytes / 90sKeep 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_raw at its default of false and hmac_accessor at 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 = true in 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 (the audit stanza) and leave the unsafe flag off. Likewise leave allow_audit_log_prefixing off unless you need the prefix option.
  • 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_test option exists, but the default probe protects you from enabling a device that cannot write.
  • Large list responses: elide_list_responses keeps 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, plus sudo for root-protected paths) and use explicit deny for sensitive paths such as sys/ 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) and r. (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 -recovery allows sys/raw access 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.

AreaWhat the migration guide statesSecurity action
VersionsTested 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 untestedPin both versions in the change record; test on a restored copy first
Storage and sealTested with Raft and Shamir; Auto Unseal not covered; clusters bootstrapped before upstream 1.3 may need a rekeyPlan seal migration as a separate change; verify key holders are available
PluginsMounts whose plugin OpenBao does not include are skipped at startup and reads return no valueInventory with secrets list and auth list beforehand; move or disable those mounts after handling their data
TokensNew tokens use the OpenBao [sbr]. format; existing tokens stay valid until their TTL expiresUpdate secret scanners and any client that parses token format
ConfigurationLargely compatible; remove disable_mlock; use a separate storage path per nodeReview the config against current OpenBao defaults, including audit and listener settings above
Audit fileOpenBao must be able to write to the existing audit fileFix ownership after stopping the old service so audit never lapses
  1. Take a Raft or atomic filesystem snapshot and confirm it restores.
  2. Install and configure OpenBao on every node without starting it, using a different storage path to make rollback easier.
  3. Upgrade followers one at a time: stop the old service, start OpenBao, join with bao operator raft join, unseal, and confirm voter status with bao operator raft list-peers.
  4. Step the leader down, confirm a new leader, then upgrade the former leader last.
  5. After cutover, re-run the hardening review: listener flags, audit device configuration, root token revocation and policy review.
  6. 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 controlNIST SP 800-53 Rev 5NIST CSF 2.0
Seal design, KMS key protectionSC-12 Cryptographic Key Establishment and Management, SC-28 Protection of Information at RestPR.DS-01
Root token revocation, scoped admin policiesAC-6 Least Privilege, AC-3 Access EnforcementPR.AA-05
Workload auth methods, short TTLs, dynamic secretsIA-5 Authenticator Management, IA-9 Service Identification and AuthenticationPR.AA-05
TLS on listeners and cluster trafficSC-8 Transmission Confidentiality and IntegrityPR.DS-02
Multiple audit devices, external log storeAU-2 Event Logging, AU-9 Protection of Audit Information, AU-12 Audit Record GenerationDE.CM-09
Declarative configuration, migration change controlCM-3 Configuration Change ControlPR.PS-01
Snapshots and restore testsCP-9 System BackupPR.DS-11
Security updatesSI-2 Flaw RemediationPR.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-root break-glass procedure.
  • Confirm disable_unauthed_generate_root_endpoints and disable_unauthed_rekey_endpoints are true on every listener.
  • Set tls_min_version to 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_creation off.
  • 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

Related NHI Mgmt Group resources: Secrets Management Guide · Secrets Zero Problem Guide · Dynamic Secrets and Ephemeral Credentials Guide · Kubernetes Secrets vs External Secret Stores

PDF for subscribers

Take this guide with you

Every section, table and checklist in one PDF, with links to the sources and related guides. Subscribe to our weekly NHI & AI Identity Journal and we’ll email you a download link.

Free weekly newsletter

Subscribe to the NHI & AI Identity Journal

The latest on NHI and Agentic AI security – articles, research, breaches, news and events every week.

Bonus 33% off our NHI Course when you subscribe.

NHIMG Editorial Note
Researched and written by the NHI Mgmt Group editorial team using AI tools, under the editorial direction of Lalit Choda. Facts are drawn from the sources listed on this page and checked by our automated quality process. Last updated 14 November 2026. Spotted an error? Use our contact page.
NHI Mgmt Group, the independent authority on Non-Human Identity, IAM and Agentic AI security. nhimg.org

PDF Downloads for Newsletter Subscribers

Get the guide

Enter your details and we’ll email you a download link.

The full guide is free to read online. The PDF is a thank you for subscribing.

Fill in all fields marked * and tick the PDF box to continue.