8.3 KiB
| layout | page_title | sidebar_current | description |
|---|---|---|---|
| docs | Secret Backend: MySQL | docs-secrets-mysql | The MySQL secret backend for Vault generates database credentials to access MySQL. |
MySQL Secret Backend
Name: mysql
The MySQL secret backend for Vault generates database credentials dynamically based on configured roles. This means that services that need to access a database no longer need to hardcode credentials: they can request them from Vault, and use Vault's leasing mechanism to more easily roll keys.
Additionally, it introduces a new ability: with every service accessing the database with unique credentials, it makes auditing much easier when questionable data access is discovered: you can track it down to the specific instance of a service based on the SQL username.
Vault makes use of its own internal revocation system to ensure that users become invalid within a reasonable time of the lease expiring.
This page will show a quick start for this backend. For detailed documentation
on every path, use vault path-help after mounting the backend.
Quick Start
The first step to using the mysql backend is to mount it.
Unlike the generic backend, the mysql backend is not mounted by default.
$ vault mount mysql
Successfully mounted 'mysql' at 'mysql'!
Next, we must configure Vault to know how to connect to the MySQL instance. This is done by providing a DSN (Data Source Name):
$ vault write mysql/config/connection \
connection_url="root:root@tcp(192.168.33.10:3306)/"
Success! Data written to: mysql/config/connection
In this case, we've configured Vault with the user "root" and password "root,
connecting to an instance at "192.168.33.10" on port 3306. It is not necessary
that Vault has the root user, but the user must have privileges to create
other users, namely the GRANT OPTION privilege.
Optionally, we can configure the lease settings for credentials generated
by Vault. This is done by writing to the config/lease key:
$ vault write mysql/config/lease \
lease=1h \
lease_max=24h
Success! Data written to: mysql/config/lease
This restricts each credential to being valid or leased for 1 hour at a time, with a maximum use period of 24 hours. This forces an application to renew their credentials at least hourly, and to recycle them once per day.
The next step is to configure a role. A role is a logical name that maps to a policy used to generate those credentials. For example, lets create a "readonly" role:
$ vault write mysql/roles/readonly \
sql="CREATE USER '{{name}}'@'%' IDENTIFIED BY '{{password}}';GRANT SELECT ON *.* TO '{{name}}'@'%';"
Success! Data written to: mysql/roles/readonly
By writing to the roles/readonly path we are defining the readonly role.
This role will be created by evaluating the given sql statements. By
default, the {{name}} and {{password}} fields will be populated by
Vault with dynamically generated values. This SQL statement is creating
the named user, and then granting it SELECT or read-only privileges
to tables in the database. More complex GRANT queries can be used to
customize the privileges of the role. See the MySQL manual
for more information.
To generate a new set of credentials, we simply read from that role:
$ vault read mysql/creds/readonly
Key Value
lease_id mysql/creds/readonly/bd404e98-0f35-b378-269a-b7770ef01897
lease_duration 3600
password 132ae3ef-5a64-7499-351e-bfe59f3a2a21
username root-aefa635a-18
By reading from the creds/readonly path, Vault has generated a new
set of credentials using the readonly role configuration. Here we
see the dynamically generated username and password, along with a one
hour lease.
Using ACLs, it is possible to restrict using the mysql backend such that trusted operators can manage the role definitions, and both users and applications are restricted in the credentials they are allowed to read.
API
/mysql/config/connection
POST
- Description
- Configures the connection DSN used to communicate with MySQL. This is a root protected endpoint.
- Method
- POST
- URL
- `/mysql/config/connection`
- Parameters
-
- connection_url required The MySQL DSN
-
- value optional
-
- max_open_connections optional Maximum number of open connections to the database. Defaults to 2.
-
- verify-connection optional If set, connection_url is verified by actually connecting to the database. Defaults to true.
- Returns
- A `204` response code.
/mysql/config/lease
POST
- Description
- Configures the lease settings for generated credentials. If not configured, leases default to 1 hour. This is a root protected endpoint.
- Method
- POST
- URL
- `/mysql/config/lease`
- Parameters
-
- lease required The lease value provided as a string duration with time suffix. Hour is the largest suffix.
- lease_max required The maximum lease value provided as a string duration with time suffix. Hour is the largest suffix.
- Returns
- A `204` response code.
/mysql/roles/
POST
- Description
- Creates or updates the role definition.
- Method
- POST
- URL
- `/mysql/roles/`
- Parameters
-
- sql required The SQL statements executed to create and configure the role. Must be semi-colon separated. The '{{name}}' and '{{password}}' values will be substituted.
- Returns
- A `204` response code.
GET
- Description
- Queries the role definition.
- Method
- GET
- URL
- `/mysql/roles/`
- Parameters
- None
- Returns
-
```javascript { "data": { "sql": "CREATE USER..." } } ```
LIST
- Description
- Returns a list of available roles. Only the role names are returned, not any values.
- Method
- GET
- URL
- `/roles/?list=true`
- Parameters
- None
- Returns
-
{ "auth": null, "data": { "keys": ["dev", "prod"] }, "lease_duration": 2592000, "lease_id": "", "renewable": false }
DELETE
- Description
- Deletes the role definition.
- Method
- DELETE
- URL
- `/mysql/roles/`
- Parameters
- None
- Returns
- A `204` response code.
/mysql/creds/
GET
- Description
- Generates a new set of dynamic credentials based on the named role.
- Method
- GET
- URL
- `/mysql/creds/`
- Parameters
- None
- Returns
-
```javascript { "data": { "username": "root-aefa635a-18", "password": "132ae3ef-5a64-7499-351e-bfe59f3a2a21" } } ```