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 adds a download (BETA) parameter to the plugin register API that lets Vault fetch the plugin binary directly from the HashiCorp releases page. The steps below cover the standard binary and .zip installation paths. For the download parameter, refer to the /sys/plugins/catalog API reference.

Before you start

To register official enterprise plugins, you must have Vault v1.16.21+, 1.17.17+, 1.18.10+, 1.19.4+, or 1.20.x+.
To register official community plugins with an extracted .zip file, you must have Vault v1.16.21+, 1.17.17+, 1.18.10+, 1.19.5+, or 1.20.x+.
In HA or multi-node clusters, the plugin binary or .zip artifact must exist in plugin_directory on every Vault node before you register or reload the plugin. The catalog entry replicates across the cluster, but the on-disk artifact does not — each node must have the file locally.
Plugin artifacts are not included in Raft snapshots. If you restore a Vault snapshot, you must manually copy the correct artifact to plugin_directory on every target node before starting Vault. See Restore a Vault snapshot for details.

You must have admin permissions for Vault. Specifically, you must be able to run plugin register and the appropriate enable command. At minimum, your token policy needs the following capabilities:

# Register and list plugins in the catalog
path "sys/plugins/catalog/*" {
  capabilities = ["create", "update", "list", "sudo"]
}

# Enable secrets engines
path "sys/mounts/*" {
  capabilities = ["create", "update"]
}

# Enable auth methods
path "sys/auth/*" {
  capabilities = ["create", "update", "sudo"]
}

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

You must register plugins with a version and we strongly recommend registering official plugins with a .zip file.

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
Official	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"
}

Troubleshooting

If registration or enabling fails, refer to the Troubleshooting section of the Plugin management page. Common issues include the Unrecognized remote plugin message error caused by missing mlock capabilities on the plugin binary.

Deregister a plugin — remove a plugin from the catalog when it is no longer needed.