Why teams look at OpenBao
OpenBao is an identity-based secrets and encryption management system. Clients authenticate, policies decide what they may read or do, and OpenBao returns static secrets, short-lived credentials, certificates or cryptographic operations. Every request can be written to an audit device, which gives security teams one place to see who used which secret.
In August 2023 HashiCorp announced that future releases of its products, including Vault, would use the Business Source License 1.1. OpenBao continues from Vault's earlier MPL-licensed code under the Mozilla Public License 2.0, as a Linux Foundation project and OpenSSF sandbox project. IBM completed its acquisition of HashiCorp in February 2025. OpenBao suits organizations that want a secrets manager under an OSI-approved license with community governance.
OpenBao keeps the Vault concepts, API style and much of the CLI, so skills and many clients carry over. Plugins, storage options, token formats and some features differ by release, so plan against the OpenBao documentation for the version you deploy.
The building blocks to design
A secrets platform is mostly a set of decisions about identity, paths and lifetimes.
Auth methods
Map each client type to an auth method: OIDC or LDAP for people, Kubernetes or JWT for workloads, AppRole or certificates for other systems. Every method should resolve to an entity with a known owner.
Secrets engines
KV for static secrets, database engines for short-lived credentials, PKI for internal certificates, Transit for encryption as a service and SSH for signed keys. Set default and maximum lease TTLs per mount so credentials expire on their own.
Policies
Policies grant capabilities on paths and deny everything else. Keep them in version control and test each with a token that holds only that policy.
Namespaces
OpenBao 2.3 added namespaces for tenant isolation, each with its own mounts, auth methods, policies and tokens. They suit shared platforms serving several business units.
Choose storage and seal options
Integrated storage replicates data between OpenBao nodes with Raft, with no external database. Run three or five voting nodes across failure domains on low-latency disks, and monitor leadership changes.
OpenBao also documents PostgreSQL as a production backend. It fits teams with a mature, highly available PostgreSQL service, which then becomes part of the secrets platform's recovery plan.
Without a seal configuration, the root key is split into unseal key shares and each node needs a quorum of holders after every restart. Name the holders, store shares separately and rehearse an unseal.
Seal options include cloud KMS services, KMIP, PKCS#11 HSMs and Transit on another OpenBao cluster. Recent releases moved several KMS integrations to plugins, so check your version. The KMS key becomes a recovery dependency.
Plan the cluster around its failure modes
Sizing depends more on request patterns than on the number of secrets stored.
| Concern | Decision | Check |
|---|---|---|
| Quorum | Place Raft voters so that losing one zone or rack still leaves a majority. | Stopping one node leaves the cluster serving requests, and the stopped node rejoins cleanly. |
| Request load | Estimate logins, dynamic credential requests, certificate issuance and Transit operations per second. | A load test with representative clients stays within agreed latency on the active node. |
| Audit write path | Give audit devices fast, monitored storage or a reliable log endpoint. | A full disk or unreachable endpoint triggers an alert before requests start failing. |
| Load balancing | Route clients through a load balancer that uses the health endpoint to find active and standby nodes. | Clients keep working during a leader step-down. |
Harden access and audit
Revoke the initial root token once administrator policies and auth methods are in place, and generate a new root token only through the documented quorum process when one is needed. Give administrators personal identities through OIDC or LDAP with short token lifetimes. Keep policies, mounts and auth configuration as code so every change is reviewed and repeatable.
OpenBao will not respond to requests when no enabled audit device (file, syslog, socket or HTTP) can record them. That protects the audit trail and makes audit storage an availability dependency, so enable two devices where possible. Since v2.3.2, creating audit devices through the API requires an explicit unsafe option in the server configuration; the project points operators to declaring them in configuration.
Use internal CA certificates on the API and cluster ports, restrict network access to them, and review swap and core dump settings on the hosts. Fixes ship in the next release, so staying close to the latest version is part of the security posture.
Migrate from HashiCorp Vault
OpenBao's migration guide describes an in-place migration in which OpenBao replaces the Vault process on each node in turn. It was tested from Vault 1.14.1 Community Edition with Raft storage and Shamir unseal to OpenBao 2.2.0. Vault Enterprise was not tested, older Vault versions should first be upgraded to 1.14.1, and newer Vault versions are untested and unsupported, with no guarantee of storage compatibility.
Before migrating, list every secrets engine and auth method in use. OpenBao ships without many plugins by default, and mounts whose plugin is missing are skipped at startup. New tokens use a different format and old ones stay valid until their TTL, so check clients that parse tokens. File audit devices need write access to the existing log, and disable_mlock should be removed from the configuration.
Clusters on later Vault versions or Vault Enterprise usually need a logical migration: build a new OpenBao cluster, apply policies, mounts and auth methods from code, copy static secrets, reissue certificates or import the CA where appropriate, and move applications in groups. Applications request new dynamic credentials from the new cluster.
Backup, recovery and upgrades
What should we back up?
Take scheduled Raft snapshots with bao operator raft snapshot save, or back up the PostgreSQL storage, and copy them off the cluster with configuration and policy code. Protect the unseal key shares or KMS key under separate control; a snapshot cannot be used without them.
How do we rehearse a recovery?
Restore a snapshot into an isolated cluster, unseal it, check policies, mounts and sample secrets, then issue a certificate and a dynamic credential.
How do upgrades work?
Take a snapshot, upgrade standby nodes one at a time and confirm each rejoins, then step down the active node and upgrade it last. Read the release notes in between for removed plugins and configuration changes.
Which version should we run?
The OpenBao support policy is best effort, with fixes going into the next release, and releases arrive roughly monthly. Plan regular upgrades and test them in a staging cluster so you can move quickly when an advisory is published.
OpenBao operating ownership
A secrets platform needs owners for the cluster, the policies, the keys and the applications that consume it.
Platform team
- Runs the cluster, storage, load balancer and TLS.
- Takes snapshots and applies upgrades.
- Monitors leadership, latency, leases and audit devices.
Key custodians
- Hold unseal or recovery key shares under a written procedure.
- Join unseal, rekey and root token operations.
- Control access to the auto-unseal KMS or HSM key.
Security
- Reviews policy changes and privileged identities.
- Watches audit logs for unusual access.
- Tracks advisories and upgrade timing.
Application teams
- Request mounts and policies through change control.
- Use dynamic credentials and renew leases.
- Remove secrets for retired services.
OpenBao deployment questions
Will our Vault clients work with OpenBao?
Many clients that use the Vault HTTP API work unchanged, and OpenBao namespaces accept the same namespace header. Test each client, especially those that parse token strings or depend on a plugin OpenBao does not ship.
Can OpenBao be our internal certificate authority?
The PKI engine can issue short-lived certificates from an intermediate CA. Keep the root CA offline, define roles that limit names and lifetimes, and decide how certificates are revoked and how the CRL or OCSP responder is published.
Scope and handover
Effort depends on the number of applications and teams, the auth methods and secrets engines required, whether a Vault migration is in scope, seal and HSM choices, availability targets and the change process for policies. Application onboarding usually takes longer than building the cluster.
DeployOpen designs the cluster, seal and policy structure, deploys and hardens OpenBao in your environment, integrates SSO for administrators and workload identity for applications, runs Vault migrations, sets up snapshots and a restore rehearsal, and documents upgrades. Handover includes the policy repository, key custodian procedure, mount inventory, restore test record and upgrade runbook.
