open-vault/website/source/docs/secrets/databases/custom.html.md

layout	page_title	sidebar_title	sidebar_current	description
docs	Custom - Database - Secrets Engines	Custom	docs-secrets-databases-custom	The database secrets engine allows new functionality to be added through a plugin interface without needing to modify vault's core code. This allows you write your own code to generate credentials in any database you wish. It also allows databases that require dynamically linked libraries to be used as plugins while keeping Vault itself statically linked.

Custom Database Secrets Engines

The database secrets engine allows new functionality to be added through a plugin interface without needing to modify vault's core code. This allows you write your own code to generate credentials in any database you wish. It also allows databases that require dynamically linked libraries to be used as plugins while keeping Vault itself statically linked.

~> Advanced topic! Plugin development is a highly advanced topic in Vault, and is not required knowledge for day-to-day usage. If you don't plan on writing any plugins, we recommend not reading this section of the documentation.

Please read the Plugins internals docs for more information about the plugin system before getting started building your Database plugin.

Plugin Interface

All plugins for the database secrets engine must implement the same simple interface.

type Database interface {
	Type() (string, error)
	CreateUser(ctx context.Context, statements Statements, usernameConfig UsernameConfig, expiration time.Time) (username string, password string, err error)
	RenewUser(ctx context.Context, statements Statements, username string, expiration time.Time) error
	RevokeUser(ctx context.Context, statements Statements, username string) error
	RotateRootCredentials(ctx context.Context, statements []string) (config map[string]interface{}, err error)
	Init(ctx context.Context, config map[string]interface{}, verifyConnection bool) (saveConfig map[string]interface{}, err error)
	Close() error
}

You'll notice the first parameter to a number of those functions is a Statements struct. This struct is used to pass the Role's configured statements to the plugin on function call. The struct is defined as:

type Statements struct {
	Creation   []string
	Revocation []string
	Rollback   []string
	Renewal    []string
}

It is up to your plugin to replace the {{name}}, {{password}}, and {{expiration}} in these statements with the proper values.

The Initialize function is passed a map of keys to values, this data is what the user specified as the configuration for the plugin. Your plugin should use this data to make connections to the database. It is also passed a boolean value specifying whether or not your plugin should return an error if it is unable to connect to the database.

Serving your plugin

Once your plugin is built you should pass it to vault's plugins package by calling the Serve method:

package main

import (
    "github.com/hashicorp/vault/plugins"
)

func main() {
    plugins.Serve(new(MyPlugin), nil)
}

Replacing MyPlugin with the actual implementation of your plugin.

The second parameter to Serve takes in an optional vault api.TLSConfig for configuring the plugin to communicate with vault for the initial unwrap call. This is useful if your vault setup requires client certificate checks. This config wont be used once the plugin unwraps its own TLS cert and key.

Running your plugin

The above main package, once built, will supply you with a binary of your plugin. We also recommend if you are planning on distributing your plugin to build with gox for cross platform builds.

To use your plugin with the database secrets engine you need to place the binary in the plugin directory as specified in the plugin internals docs.

You should now be able to register your plugin into the vault catalog. To do this your token will need sudo permissions.

$ vault write sys/plugins/catalog/myplugin-database-plugin \
    sha256="..." \
    command="myplugin"
Success! Data written to: sys/plugins/catalog/myplugin-database-plugin

Now you should be able to configure your plugin like any other:

$ vault write database/config/myplugin \
    plugin_name=myplugin-database-plugin \
    allowed_roles="readonly" \
    myplugins_connection_details="..."