MySQL/MariaDB database secrets engine
Note: This engine can use external X.509 certificates as part of TLS or signature validation. Verifying signatures against X.509 certificates that use SHA-1 is deprecated and is no longer usable without a workaround starting in Vault 1.12. See the deprecation FAQ for more information.
MySQL is one of the supported plugins for the database secrets engine. This plugin generates database credentials dynamically based on configured roles for the MySQL database, and also supports Static Roles.
This plugin has a few different instances built into vault, each instance is for a slightly different MySQL driver. The only difference between these plugins is the length of usernames generated by the plugin as different versions of mysql accept different lengths. The available plugins are:
- mysql-database-plugin
- mysql-aurora-database-plugin
- mysql-rds-database-plugin
- mysql-legacy-database-plugin
See the database secrets engine docs for more information about setting up the database secrets engine.
Capabilities
Plugin Name | Root Credential Rotation | Dynamic Roles | Static Roles | Username Customization |
---|---|---|---|---|
Depends (see: above) | Yes | Yes | Yes | Yes (1.7+) |
Setup
Enable the database secrets engine if it is not already enabled:
By default, the secrets engine will enable at the name of the engine. To enable the secrets engine at a different path, use the
-path
argument.Configure Vault with the proper plugin and connection information:
Configure a role that maps a name in Vault to an SQL statement to execute to create the database credential:
Usage
After the secrets engine is configured and a user/machine has a Vault token with the proper permission, it can generate credentials.
Generate a new credential by reading from the
/creds
endpoint with the name of the role:
Client x509 certificate authentication
This plugin supports using MySQL's x509 Client-side Certificate Authentication
To use this authentication mechanism, configure the plugin:
Note: tls_certificate_key
and tls_ca
map to ssl-cert (combined with ssl-key)
and ssl-ca
configuration options
from MySQL with the exception that the Vault parameters are the contents of those files, not filenames. As such,
the two options are independent of each other. See the MySQL Connection Options
for more information.
Examples
Using wildcards in grant statements
MySQL supports using wildcards in grant statements. These are sometimes needed
by applications which expect access to a large number of databases inside MySQL.
This can be realized by using a wildcard in the grant statement. For example if
you want the user created by Vault to have access to all databases starting with
fooapp_
you could use the following creation statement:
MySQL expects the part in which the wildcards are to be placed inside backticks. If you want to add this creation statement to Vault via the Vault CLI you cannot simply paste the above statement on the CLI because the shell will interpret the text between the backticks as something that must be executed. The easiest way to get around this is to encode the creation statement as Base64 and feed this to Vault. For example:
Rotating root credentials in MySQL 5.6
The default root rotation setup for MySQL uses the ALTER USER
syntax present
in MySQL 5.7 and up. For MySQL 5.6, the root rotation
statements
must be configured to use the old SET PASSWORD
syntax. For example:
For a guide in root credential rotation, see Database Root Credential Rotation.
API
The full list of configurable options can be seen in the MySQL database plugin API page.
For more information on the database secrets engine's HTTP API please see the Database secrets engine API page.