DOCSEARCHbyAlgolia
Submit Docs

OpenBao Documentation

repository·main·Indexed 27 days ago

https://github.com/openbao/openbao

A community-led, open-governance software solution for managing, storing, and distributing sensitive data such as secrets, certificates, and keys. Includes documentation for the Go API package, as well as guides for developing, compiling, and registering plugins for JWT and Kubernetes authentication, the Kubernetes secrets backend, and the Valkey database plugin.

Tokens
256.4K
Snippets
727
Records
1.5K
Agent score
90%

What's inside OpenBao

  1. Overview of the PKI secrets engine

    main

    The PKI secrets engine in OpenBao generates dynamic X.509 certificates. It automates the certificate lifecycle by replacing manual private key generation, CSR submission, and CA signing processes with OpenBao's built-in authentication and authorization.

    Key benefits include:

    • Scalability: Using short TTLs reduces the need for revocations and keeps Certificate Revocation Lists (CRLs) manageable.
    • Ephemeral Certificates: Certificates can be fetched and stored in memory at application startup and discarded at shutdown, avoiding disk writes.
    • Unique Identity: Allows each application instance to have its own unique certificate, simplifying rollover and eliminating shared credentials.

  2. Overview of OpenBao Telemetry Metrics

    main
    OpenBao provides a comprehensive set of telemetry metrics to monitor the health, performance, and usage of the system. These metrics are categorized by functional areas such as core Vault operations, storage engines (Raft, Bolt, PostgreSQL), secret engines (PKI, KV), identity management, and system components like the audit device, lease expiration, and log shippers. Monitoring these metrics allows developers and operators to track request latency, error rates, resource utilization (memory, goroutines), and storage health.

  3. Overview of the Transit secrets engine

    main

    The Transit secrets engine provides 'cryptography as a service'. It handles cryptographic functions on data in-transit without storing the data itself.

    Key capabilities include:

    • Encryption/Decryption: Encrypt data from applications while storing the ciphertext in your own primary data store.
    • Signing/Verification: Sign and verify data using asymmetric keys.
    • Hashing/HMAC: Generate hashes and HMACs.
    • Randomness: Act as a source of random bytes.
    • Key Derivation: Derive new keys from a base key using a user-supplied context.
    • Convergent Encryption: Optionally allow the same input values to produce the same ciphertext (useful for limited database lookups).
    • Datakey Generation: Request high-entropy keys encrypted with a named key.

  4. Overview of OpenBao CSI Provider

    main

    The OpenBao CSI Provider allows Kubernetes pods to consume OpenBao secrets using CSI Secrets Store volumes.

    Key Features:

    • Supports all OpenBao secret engines.
    • Authenticates using the requesting pod's Kubernetes service account.
    • Supports TLS/mTLS communications.
    • Renders secrets to files.
    • Performs dynamic lease caching and renewal via Agent.
    • Can sync secrets to Kubernetes secrets for use as environment variables.

    Important Requirements:

    • The CSI Secret Store Driver must be installed.
    • To use provider: openbao, you must use OpenBao Helm Chart version 0.18.0 or later (which includes OpenBao CSI Provider version 2.0.0 or later).

  5. Overview of the SSH secrets engine API

    main

    The SSH secrets engine API allows you to manage SSH Certificate Authority (CA) functionality within OpenBao. This includes managing authority information, roles, and issuers.

    Note on Pathing: These API instructions assume the SSH secrets engine is enabled at the /ssh path. If you have enabled the engine at a different mount point, you must update your API calls to use your specific path.

  6. Overview of OpenBao Web UI Modernization RFC

    main

    OpenBao is transitioning its Web UI from EmberJS to a modern React with TypeScript architecture. This modernization aims to improve extensibility, security, and developer experience by decoupling the UI from the OpenBao backend.

    Key Improvements

    • Modern Stack: Uses React, TypeScript, Material Design, and Vite/RSPack for builds.
    • Plugin Architecture: Introduces a secure, sandboxed plugin system (using Web Workers or iframes) to allow for optional UI extensions (e.g., AI agents, specific Auth integrations) without bloating the core UI.
    • Observability: Includes built-in dashboards for system health, usage analytics, and audit visualization, with support for Prometheus and Grafana exporters.
    • Integration Hub: A unified interface for managing connections to external tools like CI/CD, logging, IdP, and certificate management.
    • Security: Enforces CSP, SRI, CSRF, and HTTPS. Plugins are sandboxed and cannot access raw secrets unless explicitly authorized.

  7. Overview of Vault Agent features

    main

    Vault Agent is a client daemon designed to simplify interactions with Vault by providing the following core features:

    • Automatic authentication: Handles the initial authentication process with Vault.
    • Secure delivery/storage of tokens: Manages the secure handling of Vault tokens.
    • Lifecycle management: Automatically manages token renewal and re-authentication to ensure continuous access.
    • Caching: Provides caching mechanisms to reduce load on the Vault server.
    • Templating: Supports template features for dynamic configuration generation.

  8. Overview of OpenBao features

    main

    OpenBao is a software solution designed to manage, store, and distribute sensitive data such as secrets, certificates, and keys. Key capabilities include:

    • Secure Secret Storage: Encrypts arbitrary key/value secrets before writing them to persistent storage (e.g., disk, PostgreSQL).
    • Dynamic Secrets: Generates on-demand credentials for systems like AWS or SQL databases and automatically revokes them when the lease expires.
    • Data Encryption: Provides encryption and decryption services without storing the data itself, allowing developers to use defined parameters for securing data in external databases.
    • Leasing and Renewal: Every secret is associated with a lease. Clients can use built-in APIs to renew leases, and OpenBao automatically revokes secrets when leases expire.
    • Revocation: Supports revoking individual secrets or entire trees of secrets (e.g., all secrets for a specific user or type) to assist in key rolling or incident response.

  9. Overview of OpenBao identity-based secrets management

    main

    OpenBao is an identity-based secrets and encryption management system designed to centralize and secure sensitive data such as API tokens, encryption keys, passwords, and certificates. It provides encryption services gated by authentication and authorization methods, accessible via a UI, CLI, or HTTP API.

    Key capabilities include:

    • Secure Secret Storage: Encrypts arbitrary key/value secrets before writing them to persistent storage.
    • Dynamic Secrets: Generates on-demand credentials for systems like Kubernetes or SQL databases and automatically revokes them when the lease expires.
    • Data Encryption: Provides encryption and decryption services without requiring the system to store the data itself.
    • Leasing and Renewal: Associates a lease with every secret; secrets are automatically revoked when the lease ends, though clients can renew leases via built-in APIs.
    • Revocation: Supports revoking individual secrets or entire trees of secrets (e.g., all secrets belonging to a specific user or type) to assist in key rolling or incident response.

  10. Overview of the PKI secrets engine API

    main

    The PKI secrets engine API allows for managing Public Key Infrastructure (PKI) including Certificate Authority (CA) management, certificate issuance, revocation, and ACME support.

    Important Note on Pathing: This documentation assumes the PKI secrets engine is enabled at the /pki path. If you have enabled the engine at a different location, you must update your API calls to use your specific mount path.

    Multi-Issuer Functionality: OpenBao supports multiple Certificate Authority (CA) certificates ("issuers") within a single mount to facilitate rotation. Key behaviors include:

    • CRL configuration is shared across all issuers in a mount.
    • Authority access URLs are shared across all issuers.
    • Serial numbers are unique across all issuers in the mount.
    • Each issuer may maintain its own distinct CRL.

    Warning: It is strongly recommended to limit the scope of CAs within a single mount and avoid mixing different types of CAs (e.g., do not mix root CAs and intermediate CAs in the same mount).

  11. Understand OpenBao Integrated Storage and Raft Consensus

    main

    OpenBao's Integrated Storage uses the Raft consensus protocol to provide consistency. It relies on a peer set of nodes to maintain a replicated log and a Finite State Machine (FSM) to manage cluster state.

    Key concepts:

    • Leader: The active node responsible for ingesting new log entries, replicating them to followers, and managing commits. Non-leader nodes act as standby nodes.
    • Log: An ordered sequence of entries used to track cluster changes.
    • Quorum: A majority of members in a peer set. For a set of size n, quorum requires at least (n+1)/2 members. If quorum is lost, the cluster becomes unavailable.
    • FSM (Finite State Machine): In OpenBao, BoltDB is used as the FSM to maintain cluster state. Writes are blocked until they are both committed (stored on a quorum) and applied to the FSM.
    • Node States: Nodes transition between follower, candidate, and leader states.

  12. Understand the Unified Standby Approach for Read Scaling

    main

    OpenBao is moving from a strict active-passive HA model to a unified standby model to enable horizontal read scalability.

    Old Model:

    • Active Node: Handles all read and write requests.
    • Standby Nodes: Forward all requests to the active node, resulting in resource underutilization.

    Unified Model:

    • All Standby Nodes: Capable of serving read requests by default. They maintain a consistent replica of the active node's state by applying the write-ahead log (WAL) in near real-time.
    • Active Node: Continues to handle all write operations.

    This approach eliminates the distinction between 'performance standby' and 'regular standby' nodes, simplifying operations and improving resource utilization.