Register and enable external plugins

An external plugin is any authentication or secrets plugin build from external code. Vault pre-registers commonly used external plugins (like kv), but you must manually add other external plugins to the Vault plugin catalog before you can use them with your Vault installation.

If you register an external plugin with the same name as a pre-registered plugin, Vault defaults to the manually registered plugin when you enable a new mount with that name.

Vault Enterprise v1.20.0 supports the download (BETA) parameter in the plugin register API. You can set download to true when registering a plugin to have Vault fetch the plugin binary from the HashiCorp release page. Refer to the /sys/plugins/catalog API reference for more details.

Before you start

To register enterprise plugins, you must have Vault v1.16.21+, 1.17.17+, 1.18.10+, 1.19.4+, or 1.20.x+.

You must have admin permissions for Vault. Specifically, you must be able to run plugin register and the appropriate enable command.
You must have plugin_directory set in your Vault configuration file.
You must have api_addr set in your Vault configuration file.
If you plan to use an extracted .zip file, the plugin artifacts must be compatible with the system running Vault. Vault verifies plugin integrity and checks system compatibility during the registration process for extracted artifacts.

Step 1: Prepare the plugin

You must have the plugin set up properly in your configured plugin directory. Vault expects specific path structures based on the integration, license, and file format.

If you plan to register an extracted .zip file, the extracted artifact directory name must match the official file name. For example, to register vault-plugin-database-oracle_0.11.0+ent_linux_amd64.zip, you must extract it to the plugin directory as vault-plugin-database-oracle_0.11.0+ent_linux_amd64/.

Integration	License	Source	Path structure
Official	Enterprise	`.zip`	`<plugin_directory>/<extracted-folder-name>/`
Official	Community	`.zip`	`<plugin_directory>/<extracted-folder-name>/`
Community	N/A	`.zip`	Not supported
Official	Enterprise	binary	Not supported
Offical	Community	binary	`<plugin_directory>/<binary-name>`
Community	N/A	binary	`<plugin_directory>/<binary-name>`

Step 2: Update the plugin catalog

You must register your external plugin with the Vault catalog before enabling it. Registering plugins ensures the plugin invoked by Vault is authentic and maintains integrity.

Save the SHA for your plugin binary:

$ PLUGIN_SHA=$(sha256sum <path_to_plugin_binary> | awk '{print $1;}')

Use vault plugin register to add your plugin to the catalog:

$ vault plugin register                     \
    -command <command_to_run_plugin_binary> \
    -sha256 "${PLUGIN_SHA[0]}"              \
    -version "<semantic_version>"           \
    <plugin_type>                           \
    <plugin_name>                           \

For example, to register a secrets plugin called mykv that runs on the command line as mykvplugin:

$ vault plugin register   \
    -command mykvplugin   \
    -sha256 ${PLUGIN_SHA} \
    -version "v1.0.1"     \
    secret                \
    mykv

Success! Registered plugin: mykv

Save the SHA, version, and run command for your plugin binary to a JSON file:

$ cat <<-EOF > data.json
{
  "sha256": "$(sha256sum <path_to_plugin_binary> | awk '{print $1;}')",
  "command": "<command_to_run_plugin_binary>",
  "version": "<semantic_version>"
}
EOF

For example, to create a data file for a plugin that runs on the command line as mykvplugin:

$ cat <<-EOF > data.json
{
  "sha256": "$(sha256sum mykvplugin | awk '{print $1;}')",
  "command": "mykvplugin",
  "version": "v1.0.1"
}
EOF

Call the RegisterPlugin endpoint to add your plugin to the catalog:

$ curl                                      \
  --request POST                            \
  --header "X-Vault-Token: ${VAULT_TOKEN}"  \
  --data @data.json                         \
  ${VAULT_ADDR}/v1/sys/plugins/catalog/<plugin_type>/<plugin_name>

For example, to register a secrets plugin called mykv:

$ curl                                      \
  --request POST                            \
  --header "X-Vault-Token: ${VAULT_TOKEN}"  \
  --data @data.json                         \
  ${VAULT_ADDR}/v1/sys/plugins/catalog/secret/mykv

Call the ListPlugins endpoint to verify registration:

$ curl                                      \
  --request GET                             \
  --header "X-Vault-Token: ${VAULT_TOKEN}"  \
  ${VAULT_ADDR}/v1/sys/plugins/catalog      \
  | jq '.data.detailed | .[] | select(.name =="mykv")'

For example:

$ curl                                      \
  --request GET                             \
  --header "X-Vault-Token: ${VAULT_TOKEN}"  \
  ${VAULT_ADDR}/v1/sys/plugins/catalog      \
  | jq '.data.detailed | .[] | select(.name =="mykv")'

{
  "builtin": false,
  "name": "mykv",
  "sha256": "4b7c6993b7147d84d958f30438f9d0c34f34aa400300693b193e62774e4338d7",
  "type": "secret",
  "version": "v1.0.1"
}

Use vault plugin register to add your plugin to the catalog using -version. Do not provide a SHA value:

$ vault plugin register
    -version "<semantic_version>"
    <plugin_type>
    <plugin_name>

For example, to register the vault-plugin-secrets-keymgmt plugin with the extracted artifact directory vault-plugin-secrets-keymgmt_0.16.0+ent_linux_amd64/:

$ vault plugin register     \
    -version "v0.16.0+ent"  \
    secret                  \
    vault-plugin-secrets-keymgmt

Success! Registered plugin: vault-plugin-secrets-keymgmt

Save the version information for your extracted plugin folder to a JSON file:
```
$ cat <<-EOF > data.json
{
  "version": "<semantic_version>"
}
EOF
```
For example, to create a data file for the vault-plugin-secrets-keymgmt plugin with the extracted artifact directory vault-plugin-secrets-keymgmt_0.16.0+ent_linux_amd64/:
```
$ cat <<-EOF > data.json
{
  "version": "v0.16.0+ent"
}
EOF
```

Call the RegisterPlugin endpoint to add your plugin to the catalog:

$ curl                                      \
  --request POST                            \
  --header "X-Vault-Token: ${VAULT_TOKEN}"  \
  --data @data.json                         \
  ${VAULT_ADDR}/v1/sys/plugins/catalog/<plugin_type>/<plugin_name>

For example, to register the vault-plugin-secrets-keymgmt plugin with the extracted artifact directory vault-plugin-secrets-keymgmt_0.16.0+ent_linux_amd64/:

$ curl                                      \
  --request POST                            \
  --header "X-Vault-Token: ${VAULT_TOKEN}"  \
  --data @data.json                         \
  ${VAULT_ADDR}/v1/sys/plugins/catalog/secret/vault-plugin-secrets-keymgmt

Call the ListPlugins endpoint to verify registration:

$ curl                                      \
  --request GET                             \
  --header "X-Vault-Token: ${VAULT_TOKEN}"  \
  ${VAULT_ADDR}/v1/sys/plugins/catalog      \
  | jq '.data.detailed | .[] | select(.name =="<plugin_name>")'

For example:

$ curl                                      \
  --request GET                             \
  --header "X-Vault-Token: ${VAULT_TOKEN}"  \
  ${VAULT_ADDR}/v1/sys/plugins/catalog      \
  | jq '.data.detailed | .[] | select(.name =="vault-plugin-secrets-keymgmt")'

{
  "builtin": false,
  "name": "vault-plugin-secrets-keymgmt",
  "sha256": "95f051152c4b69c720afef2fef26469f83a2e084842bdfad0f795850047fc84f",
  "type": "secret",
  "version": "v0.16.0+ent"
}

Step 3: Enable the plugin

Enable the plugin to make it available to clients.

Use the appropriate enable command (vault secrets enable or vault auth enable) and the registered name to mount the external plugin:

$ vault <secrets | auth> enable \
  -path <mount_path>            \
  <plugin_name>

For example, to enable the mykv plugin on the path /custom/kv:

$ vault secrets enable \
  -path custom/kv      \
  mykv

Success! Enabled the mykv secrets engine at: custom/kv/

Save the type and any relevant configuration details to a JSON file:

$ cat <<-EOF > data.json
{
  "type": "<registered_plugin_name>",
  "config": {
    "plugin_version": "<semantic_version>"
  }
}
EOF

For example, to create a data file for the mykv plugin:

$ cat <<-EOF > data.json
{
  "type": "mykv",
  "config": {
    "plugin_version": "v1.0.0"
  }
}
EOF

Use the appropriate enable endpoint ( EnableSecretsEngine or EnableAuthMethod) and the registered plugin name to mount the external plugin:

$ curl                                             \
  --request POST                                   \
  --header "X-Vault-Token: ${VAULT_TOKEN}"         \
  --header "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  --data @data                                     \
  ${VAULT_ADDR}/v1/sys/<mounts | auth>/<mount_path>

For example, to enable the mykv secrets plugin on the path /custom/kv:

$ curl                                              \
  --request POST                                    \
  --header "X-Vault-Token: ${VAULT_TOKEN}"          \
  --header "X-Vault-Namespace: ${VAULT_NAMESPACE}"  \
  --data @data                                      \
  ${VAULT_ADDR}/v1/sys/mounts/custom/kv

Step 4: Verify the plugin status

Verify the plugin is ready for use and running the correct version.

Use the appropriate list command (vault secrets list or vault auth list) to verify the version and mounted path for the registered plugin:

$ vault <secrets | auth> list

For example, to verify the mykv plugin:

$ vault secrets list

Path            Type            Accessor                 Description
----            ----            --------                 -----------
cubbyhole/      ns_cubbyhole    ns_cubbyhole_dd6729a7    per-token private secret storage
custom/mykv/    mykv            mykv_7121a3d5            n/a
identity/       ns_identity     ns_identity_f000c24d     identity store
private/        kv              kv_4a4118d8              n/a
shared/         kv              kv_60208c6d              n/a
sys/            ns_system       ns_system_b9a3364f       system endpoints used for control, policy and debugging

The list subcommand does not support filtering for specific fields in the output, to confirm the version or running version, use the -detailed flag, filter for the relevant plugin, and print the desired status column by index:

Index	Detail column
0	Path
1	Plugin
2	Accessor
3	Default TTL
4	Max TTL
5	Force No Cache
6	Replication
7	Seal Wrap
8	External Entropy Access
9	Options
10	Description
11	UUID
12	Version
13	Running Version
14	Running SHA256
15	Deprecation Status

For example, to print the running version for mykv:

$ row=($(vault secrets list -detailed | grep mykv)) ; \
  echo "${row[0]}: ${row[1]} (${row[13]})"

custom/mykv/: mykv (v1.0.1)

Use the appropriate list endpoint (ListSecretsEngines or ListAuthMethods) to verify the mounted path for the registered plugin:

$ curl -s                                          \
  --request GET                                    \
  --header "X-Vault-Token: ${VAULT_TOKEN}"         \
  --header "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  ${VAULT_ADDR}/v1/sys/<mounts | auth> | jq '.data."<mount_path>"'

For example, to verify the mykv secrets plugin on the path /custom/kv:

$ curl -s                                          \
  --request GET                                    \
  --header "X-Vault-Token: ${VAULT_TOKEN}"         \
  --header "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  ${VAULT_ADDR}/v1/sys/mounts | jq '.data."custom/mykv/"'

{
  "accessor": "mykv_7121a3d5",
  "config": {
    "default_lease_ttl": 0,
    "force_no_cache": false,
    "max_lease_ttl": 0
  },
  "description": "",
  "external_entropy_access": false,
  "local": false,
  "options": {},
  "plugin_version": "v1.0.1",
  "running_plugin_version": "v1.0.1",
  "running_sha256": "4b7c6993b7147d84d958f30438f9d0c34f34aa400300693b193e62774e4338d7",
  "seal_wrap": false,
  "type": "mykv",
  "uuid": "61c79aea-5b39-1cbb-b470-96edd9f6bfeb"
}