Skip to main content
Version: Development

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. 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.

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.

See Plugin Upgrade Procedure for details on how to upgrade a built-in plugin in-place.

Plugin distribution methods​

Built-In plugins​

Built-in plugins are shipped with OpenBao, often for commonly used integrations, and can be used without any prerequisite steps.

External plugins​

External plugins are not shipped with OpenBao and require additional operator steps to be installed, configured, and registered with OpenBao before they can be used.

OpenBao's external plugins are completely separate, standalone applications that OpenBao executes and communicates with over gRPC. To run an external plugin, a binary of the plugin is required. Plugin binaries can be obtained from the openbao-plugins repository or they can be built from source.

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

  1. Declarative plugins can be used to register all types of available plugins statically via OpenBao's server configuration file. This is the preferred, modern approach to plugin registration. Additionally, declarative plugins can automatically download plugin binaries from an OCI registry if configured to do so. Plugin types supported by the plugin catalog API registered via declarative plugins are reconciled against the plugin catalog and will show up in API responses as well (see more on the API-driven plugin catalog below).

  2. The API-driven plugin catalog can be used to manage plugins already present on the file system via the API given OpenBao is unsealed. Naturally, these endpoints do not support plugins of type kms, which provide Auto-Unseal functionality immediately required at server startup. To manage plugins of this type, use declarative plugins as described above.

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 secret
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.