open-vault/website/source/guides/operations/plugin-backends.html.md

layout	page_title	sidebar_title	sidebar_current	description
guides	Plugin Backends - Guides	Building Plugin Backends	guides-operations-plugin-backends	Learn how to build, register, and mount a custom plugin backend.

Introduction

Plugin backends utilize the plugin system to enable third-party secrets engines and auth methods.

It is worth noting that even though database secrets engines operate under the same underlying plugin mechanism, they are slightly different in design than plugin backends demonstrated in this guide. The database secrets engine manages multiple plugins under the same backend mount point, whereas plugin backends are kv backends that function as either secret or auth methods.

This guide provides steps to build, register, and mount non-database external plugin backends.

Setup Vault

Set plugin_directory to the desired path in the Vault configuration file. The path should exist and have proper lockdown on access permissions.

# /etc/vault/config.d/plugins.hcl
plugin_directory = "/etc/vault/vault_plugins"

If the Vault server is already running, you will need to tell it to reload its configuration by sending SIGHUP. If you stop and start the Vault server, you will need to unseal it again.

Compile Plugin

Build the custom binary, and move it inside the plugin_directory path configured above. This guide uses mock-plugin that comes from Vault's logical/plugin/mock package.

Download the source (you would probably use your own plugin):

$ go get -f -u -d github.com/hashicorp/vault
# ...
$ cd $GOPATH/src/github.com/hashicorp/vault/logical/plugin/mock/mock-plugin

Compile the plugin:

$ go build -o my-mock-plugin

Put the plugin in the directory:

$ mv my-mock-plugin /etc/vault/vault_plugins

Alternatively, if you wanted a custom version of a plugin built into Vault, such as AppRole:

$ cd $GOPATH/src/github.com/hashicorp/vault/builtin/credential/approle/cmd/approle
$ go build
$ mv approle /etc/vault/vault_plugins

Register in Plugin Catalog

Calculate the SHA256 sum of the compiled plugin binary, and use that to register the plugin into Vault's plugin catalog:

$ shasum -a 256 /etc/vault/vault_plugins/my-mock-plugin
2c071aafa1b30897e60b79643e77592cb9d1e8f803025d44a7f9bbfa4779d615  /etc/vault/vault_plugins/my-mock-plugin

$ vault write sys/plugins/catalog/secret/my-mock-plugin \
    sha256=2c071aafa1b30897e60b79643e77592cb9d1e8f803025d44a7f9bbfa4779d615 \
    command=my-mock-plugin
Success! Data written to: sys/plugins/catalog/secret/my-mock-plugin

Enable Plugin

Enabling the plugin varies depending on if it's a secrets engine or auth method:

$ vault secrets enable -path=my-secrets-plugin my-mock-plugin
Success! Enabled the my-mock-plugin plugin at: my-secrets-plugin/

If you try to mount this particular plugin as an auth method instead of a secrets engine, you will get an error:

$ vault auth enable -path=my-auth-plugin my-mock-plugin
# ...
* cannot mount 'my-mock-plugin' of type 'secret' as an auth method

Perform Operations

Each plugin responds to read, write, list, and delete as its own behavior.

$ vault write my-secrets-plugin/kv/foo value=bar
Key      Value
---      -----
value    bar

Disable Plugin

When you are done using the plugin, disable it.

$ vault secrets disable my-secrets-plugin
Success! Disabled the secrets engine (if it existed) at: my-secrets-plugin/