Plugin system

OpenBao supports 4 types of plugins: auth methods, secret engines, database providers, and Key Management Service (KMS) providers. This concept allows both built-in and external plugins to be treated like building blocks and to keep the OpenBao core small.

A plugin is uniquely identified by its type (one of secret, auth, database, or kms), name (e.g. kv), and version (e.g v1.0.0). An empty version implies either the built-in plugin or the single unversioned plugin that can be registered. Auth method and secrets engine plugin can exist at multiple different mount paths. Different versions of a plugin may be at each location, with each version differing from OpenBao's version.

To use a plugin, an operator needs to:

1. Install the plugin.
2. Register the plugin with OpenBao.
3. Use the plugin.

Plugin installation

Built-in plugins

Built-in plugins are compiled into the bao binary and can be used directly. No installation or upgrade is needed. Built-in plugins cover commonly used integrations, such as the kv secrets engine.

External plugins

External plugins are completely separate, standalone binaries that OpenBao executes and communicates with over gRPC. They are not shipped in the main OpenBao binary and must be downloaded separately.

External plugins maintained by the OpenBao project are available from the openbao-plugins repository. To learn how to create your own plugins, visit the developer guide.

See the plugin installation guide for how to install external plugins.

Plugin upgrade

Built-in plugins don't need to be upgraded separatedly (because they are part of the OpenBao binary). See the plugin upgrade guide for how to upgrade external plugins.

Plugin registration

Plugins need to be registered so that OpenBao knows about them. Built-in plugins are registered by default.

The metadata of registered plugins is persisted in OpenBao's storage backend in the plugin catalog. This means that OpenBao must be unsealed before these plugins can be used. kms plugins cannot be (and need not be) registered since they must be available in a sealed state.

External plugins can be registered with OpenBao in up to two ways, depending on the plugin type:

1. Declarative: All plugin types can be statically declared via OpenBao's server configuration file. This is the preferred, modern approach. To declare a plugin, edit your config file as follows:

   1. Add a plugin stanza
   2. Add plugin_auto_register = true
   3. If you are using an OCI-distributed plugin: Add plugin_auto_download = true

   When configured like this, OpenBao automatically downloads and/or registers the plugins when the server starts or when a SIGHUP is received.

2. API-driven: Plugin types auth, database, secret can alternatively be registered by calling the API. This requires OpenBao to be unsealed and a token with sufficient permission be available.

   $ bao plugin register -sha256=<hex digest of plugin binary> secret passthrough-plugin
   
   Success! Registered plugin: passthrough-plugin

The plugin list command lists all available plugins.

Plugin usage

How a plugin is used varies by its type. See their respective documentation for details:

• auth
• database
• kms
• secret

Plugin versioning

OpenBao supports managing, running and upgrading plugins using semantic version information.

The plugin catalog optionally supports specifying a semantic version when registering an external plugin. Multiple versions of a plugin can be registered in the catalog simultaneously, and a version can be selected when mounting a plugin or tuning an existing mount in-place.

If no version is specified when creating a new mount, the following precedence is used for any available plugins whose type and name match:

• The plugin registered with no version
• The plugin with the most recent semantic version among any registered versions
• The plugin built into OpenBao

Built-In versions

OpenBao will report a version for built-in plugins to indicate what version of the plugin code got built into OpenBao as a dependency. For example:

$ bao plugin list
Name                Version
----                -------
approle                         auth        v2.0.0+builtin.bao
cert                            auth        v2.0.0+builtin.bao
jwt                             auth        v2.0.0+builtin.bao
kerberos                        auth        v2.0.0+builtin.bao
kubernetes                      auth        v2.0.0+builtin.bao
ldap                            auth        v2.0.0+builtin.bao
oidc                            auth        v2.0.0+builtin.bao
radius                          auth        v2.0.0+builtin.bao
userpass                        auth        v2.0.0+builtin.bao
cassandra-database-plugin       database    v2.0.0+builtin.bao
influxdb-database-plugin        database    v2.0.0+builtin.bao
mysql-aurora-database-plugin    database    v2.0.0+builtin.bao
mysql-database-plugin           database    v2.0.0+builtin.bao
mysql-legacy-database-plugin    database    v2.0.0+builtin.bao
mysql-rds-database-plugin       database    v2.0.0+builtin.bao
postgresql-database-plugin      database    v2.0.0+builtin.bao
redis-database-plugin           database    v2.0.0+builtin.bao
valkey-database-plugin          database    v2.0.0+builtin.bao
kubernetes                      secret      v2.0.0+builtin.bao
kv                              secret      v2.0.0+builtin.bao
ldap                            secret      v2.0.0+builtin.bao
openldap                        secret      v2.0.0+builtin.bao
pki                             secret      v2.0.0+builtin.bao
rabbitmq                        secret      v2.0.0+builtin.bao
ssh                             secret      v2.0.0+builtin.bao
totp                            secret      v2.0.0+builtin.bao
transit                         secret      v2.0.0+builtin.bao

The bao metadata identifier indicates that plugin's code was within the OpenBao repo. For plugins within the OpenBao repo, OpenBao's own major, minor, and patch versions are used to form the plugin version.

The builtin metadata identifier is reserved and cannot be used when registering external plugins.