OpenBao Features - Declarative Plugins | OpenBao
Skip to main content<br>This is the fourth part of a multi-part series on OpenBao's features.
Last time we talked about how to<br>declaratively configure audit devices and initialize OpenBao. We saw how this<br>made integration of OpenBao in a wider ecosystem or product (such as<br>EdgeX) easier.
Like the last part, this part focuses on the operator experience, but for<br>consumption of OpenBao's plugins: auth methods, secrets engines, auto-unseal<br>devices, and more.
Our motivation here is to build towards a more OpenTofu-like,<br>extensible ecosystem. Easier consumption, community-maintained<br>plugins, and a future plugin<br>registry will lead to more developers writing plugins and expand the<br>usefulness of OpenBao for everyone.
Question<br>What integrations would you like OpenBao to have? How would you like to see<br>writing plugins made easier?Contact us to share your thoughts or<br>contribute to the ecosystem!
Overview
Nearly everything within OpenBao is pluggable. OpenBao supports several types of plugins currently:
TypeDescriptionAuth Allow bringing sources of identity--JWTs, certificates, passwords--and exchanging them for OpenBao tokens.Secret Allow generating credentials (whether passwords for databases, PKI certificates, static secrets, and more) and protected through OpenBao's tokens and authorization policies.Database Implement database-specific logic for updating and managing access for use with the database dynamic secret engine.KMS Implement specialized interfaces for using HSM and KMS devices (such as YubiHSM or GCP CloudKMS) for auto-unseal (and external keys in the upcoming v2.7.0).<br>Plugins have two primary classifications:
ClassificationDescriptionBuiltin Distributed as part of the main bao binary artifact. No external process is started.External Distributed as stand-alone binaries, requiring installation and configuration to use. Spawns an external process (managed by the OpenBao server) to handle plugin requests.<br>For example, secrets-pki is a builtin secret<br>plugin, but secrets-aws<br>is an external secret plugin. auth-aws<br>also exists and is an external auth plugin.
Usage
OpenBao since v2.5.x supported<br>declarative plugin configuration. Three<br>mandatory configuration parameters are<br>required for these demos:
// Only plugins from the specified directory will be loaded. This helps
// to prevent arbitrary binaries from being executed and leading to
// generalized RCE.
plugin_directory = "/openbao/plugins"
// Setting this allows the server process to automatically download new
// plugins if they're not registered. Otherwise OpenBao will not contact
// the internet by default. This will occur on all nodes (active and
// standby).
plugin_auto_download = true
// Setting this allows automatic registration of the plugin into the
// plugin catalog. This is allows operators to immediately use the plugin
// without having to manually register it using API commands:
//
// https://openbao.org/api-docs/system/plugins-catalog/
plugin_auto_register = true
With that in mind, adding an external plugin is greatly simplified:
// Defines a new secret engine, named "aws".
plugin "secret" "aws" {
// ## Distribution Information ##
// Image is the container registry's address. It is strongly recommended
// to pull from a trusted, local registry mirror instead of a public
// registry.
//
// See also: https://github.com/openbao/openbao-plugins/pkgs/container/openbao-plugin-secrets-aws/1056268559?tag=v0.3.1
image = "ghcr.io/openbao/openbao-plugin-secrets-aws"
// The version of the plugin itself; must be a semantic version and also a
// tag on the above registry.
//
// See also: https://semver.org/
version = "v0.3.1"
// Within the image, the path to the plugin binary. For OpenBao's
// community maintained plugins, this is the same as the plugin itself.
binary_name = "openbao-plugin-secrets-aws"
// ## Execution Information ##
// This contains the hash of the plugin binary and is required regardless
// of distribution mechanism.
//
// If the above registry were to change the tag to point at a different
// version of the image, this sha256sum prevents us from pulling an
// unexpected plugin binary.
sha256sum = "641ae1858c0f660b4c3761286d627e1dcfd33dc35e7c83eb81ca9050b5bdc6d8"
// args = [ ... ] and env = [ ... ] are optional parameters if the plugin
// requires additional information.
...and send a SIGHUP or restart the server. That's it! You should now see<br>messages in the server logs like:
[INFO] plugins: starting OCI plugin downloading
[DEBUG] plugins: processing plugin: plugin=secret-aws url=ghcr.io/openbao/openbao-plugin-secrets-aws:v0.3.1 binary_name=openbao-plugin-secrets-aws
[INFO] plugins: downloading plugin from OCI registry: plugin=secret-aws url=ghcr.io/openbao/openbao-plugin-secrets-aws:v0.3.1
[DEBUG] plugins: local platform: plugin=secret-aws platform=linux/amd64
[DEBUG] plugins: extracting plugin from OCI image: plugin=secret-aws...