OpenBao architecture
OpenBao is a secrets and encryption management system. It provides capabilities for storing, generating, encrypting, revoking, auditing secrets (such as API keys, certificates, passwords) and allows administrators to audit and manage access policies. OpenBao is also able to generate secrets on demand, credentials leasing/renewal and revocation, and encryption-as-a-service.
This article describes the internal architecture of OpenBao, its core components, workflows, and how it ensures secrets management.
Main features
OpenBao provides the following features for managing sensitive data:
-
Centralized secrets management. OpenBao acts as a single, secure system of record for secrets such as API keys, certificates, passwords, and tokens.
-
Dynamic secrets. OpenBao can generate secrets on demand. For example, it can issue temporary database credentials with a defined lease time.
-
Leasing and automatic revocation. Every secret and token in OpenBao is associated with a lease. When the lease expires, the secret is automatically revoked. Clients may renew leases if policies allow, but once the maximum lifetime is reached, secrets are invalidated. This mechanism enforces credential rotation and minimizes risk.
-
Encryption-as-a-service. OpenBao provides an interface for performing cryptographic operations such as encryption, decryption, and key derivation without exposing the encryption keys themselves. Applications can securely delegate cryptographic functions to OpenBao instead of handling keys directly.
-
Fine-grained access control. Access to secrets and operations is controlled by policies. Policies are path-based and follow a deny-by-default model, ensuring that only explicitly authorized actions are permitted.
-
Auditing and logging. Every request and response passing through OpenBao can be captured by audit devices. Logs contain detailed metadata about client identity, requested paths, and operations.
High-level workflow
OpenBao’s request lifecycle typically involves the following stages:
-
Authentication
A client submits credentials or uses an authentication method (e.g. username/password, token, GitHub, LDAP, or public/private key). OpenBao verifies the client’s identity.
-
Validation
Optional external verification using trusted sources or identity providers. For example, GitHub, LDAP, AppRole.
-
Authorization
Applying policy rules (ACL-style), which define paths or operations the client is permitted to perform.
-
Access
Once authorized, a client can request secrets, generate dynamic secrets, encrypt/decrypt data, etc. Secrets may have leases (expiry). After lease expiration, secrets are revoked.
Components
-
Barrier
The barrier is the cryptographic encryption layer that protects all sensitive data. Every value written to the underlying storage backend is encrypted before being stored.
-
Storage Backend
The storage backend is the physical persistence layer, such as a file system or a cloud storage service. The backend only stores encrypted blobs from the barrier. It stores secrets, tokens, policies, leases, and audit logs but never has access to plaintext data.
-
Server
The OpenBao server is the central daemon that coordinates all operations. It handles client requests, applies authentication and authorization logic, interacts with the barrier for encryption/decryption, manages the lifecycle of leases, and routes to the correct Secrets Engine or audit device.
-
Token Store
The token store is an internal component that manages tokens issued to clients after successful authentication. Tokens represent a client identity, carry associated policies, and may have leases attached. The token store ensures tokens can be validated and revoked.
-
Policy Store
The policy store holds access control policies. Policies are written in ACL style and mapped to paths. They define exactly which operations a client can perform. The server enforces these rules during authorization.
-
Secrets Engine
Secrets Engine are pluggable components mounted at paths inside OpenBao. They can generate dynamic secrets (e.g. database credentials), provide encryption services, or store static key/value secrets. Each engine runs inside the server and communicates with the barrier for secure persistence.
-
Audit devices
Audit devices record every request and response passing through OpenBao. Multiple audit devices can be configured (e.g. local files, syslog, external log services). Audit logs are themselves protected and must be accessible only to administrators.
-
Expiration Manager
The expiration manager tracks leases associated with tokens and secrets. It ensures that expired secrets are revoked automatically and that renewable secrets can be extended when permitted.
-
Rollback Manager
The rollback manager ensures consistency in case of failures. If a Secrets Engine request fails, rollback entries ensure partial state is cleaned up.
Main concepts
Sealing and unsealing
When the server starts, it is in the sealed state. The root key must be reconstructed before OpenBao can start working.
By default, OpenBao uses Shamir’s Secret Sharing to split the unseal key into a number of shards. A threshold number of shards is needed to reconstruct the key. This supports distributed key recovery and prevents single-point compromise.
Optionally, external key management systems (KMS) or hardware security modules (HSM) may be used for auto-unsealing or root key protection.
Authentication
Clients authenticate using supported methods (tokens, public/private keys, LDAP, GitHub, etc.). The server validates credentials through the chosen authentication method. After successful authentication and authorization, an OpenBao token is issued and associated with the applicable policies.
Policy enforcement
When a client makes a request, the server checks the policies associated with its token against the path and operation. Policies follow a deny-by-default model, which means that the access is granted only if explicitly allowed.
Token management
Tokens are the main client ID once the client is verified. Tokens may carry leases, be renewable, or be child tokens of another. The token store validates tokens on each request, enforces TTLs, and supports revocation.