227 lines
10 KiB
Plaintext
227 lines
10 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Database - Secrets Engines
|
|
description: |-
|
|
The database secrets engine generates database credentials dynamically based
|
|
on configured roles. It works with a number of different databases through a
|
|
plugin interface. There are a number of built-in database types and an exposed
|
|
framework for running custom database types for extendability.
|
|
---
|
|
|
|
# Databases
|
|
|
|
The database secrets engine generates database credentials dynamically based on
|
|
configured roles. It works with a number of different databases through a plugin
|
|
interface. There are a number of built-in database types, and an exposed framework
|
|
for running custom database types for extendability. 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. These are referred to as "dynamic roles" or "dynamic secrets".
|
|
|
|
Since every service is 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.
|
|
|
|
### Static Roles
|
|
|
|
The database secrets engine supports the concept of "static roles", which are
|
|
a 1-to-1 mapping of Vault Roles to usernames in a database. The current password
|
|
for the database user is stored and automatically rotated by Vault on a
|
|
configurable period of time. This is in contrast to dynamic secrets, where a
|
|
unique username and password pair are generated with each credential request.
|
|
When credentials are requested for the Role, Vault returns the current
|
|
password for the configured database user, allowing anyone with the proper
|
|
Vault policies to have access to the user account in the database.
|
|
|
|
~> Not all database types support static roles at this time. Please consult the
|
|
specific database documentation on the left navigation or the table below under
|
|
[Database Capabilities](#database-capabilities) to see if a given database
|
|
backend supports static roles.
|
|
|
|
## Setup
|
|
|
|
Most secrets engines must be configured in advance before they can perform their
|
|
functions. These steps are usually completed by an operator or configuration
|
|
management tool.
|
|
|
|
1. Enable the database secrets engine:
|
|
|
|
```shell-session
|
|
$ vault secrets enable database
|
|
Success! Enabled the database secrets engine at: database/
|
|
```
|
|
|
|
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.
|
|
|
|
1. Configure Vault with the proper plugin and connection information:
|
|
|
|
```shell-session
|
|
$ vault write database/config/my-database \
|
|
plugin_name="..." \
|
|
connection_url="..." \
|
|
allowed_roles="..." \
|
|
username="..." \
|
|
password="..." \
|
|
```
|
|
|
|
~> It is highly recommended a user within the database is created
|
|
specifically for Vault to use. This user will be used to manipulate
|
|
dynamic and static users within the database. This user is called the
|
|
"root" user within the documentation.
|
|
|
|
Vault will use the user specified here to create/update/revoke database
|
|
credentials. That user must have the appropriate permissions to perform
|
|
actions upon other database users (create, update credentials, delete, etc.).
|
|
|
|
This secrets engine can configure multiple database connections. For details
|
|
on the specific configuration options, please see the database-specific
|
|
documentation.
|
|
|
|
1. After configuring the root user, it is highly recommended you rotate that user's
|
|
password such that the vault user is not accessible by any users other than
|
|
Vault itself:
|
|
|
|
```shell-session
|
|
$ vault write -force database/rotate-root/my-database
|
|
```
|
|
|
|
!> When this is done, the password for the user specified in the previous step
|
|
is no longer accessible. Because of this, it is highly recommended that a
|
|
user is created specifically for Vault to use to manage database
|
|
users.
|
|
|
|
1. Configure a role that maps a name in Vault to a set of creation statements to
|
|
create the database credential:
|
|
|
|
```shell-session
|
|
$ vault write database/roles/my-role \
|
|
db_name=my-database \
|
|
creation_statements="..." \
|
|
default_ttl="1h" \
|
|
max_ttl="24h"
|
|
Success! Data written to: database/roles/my-role
|
|
```
|
|
|
|
The `{{username}}` and `{{password}}` fields will be populated by the plugin
|
|
with dynamically generated values. In some plugins the `{{expiration}}` field is also supported.
|
|
|
|
## Usage
|
|
|
|
After the secrets engine is configured and a user/machine has a Vault token with
|
|
the proper permission, it can generate credentials.
|
|
|
|
1. Generate a new credential by reading from the `/creds` endpoint with the name
|
|
of the role:
|
|
|
|
```shell-session
|
|
$ vault read database/creds/my-role
|
|
Key Value
|
|
--- -----
|
|
lease_id database/creds/my-role/2f6a614c-4aa2-7b19-24b9-ad944a8d4de6
|
|
lease_duration 1h
|
|
lease_renewable true
|
|
password FSREZ1S0kFsZtLat-y94
|
|
username v-vaultuser-e2978cd0-ugp7iqI2hdlff5hfjylJ-1602537260
|
|
```
|
|
|
|
## Database Capabilities
|
|
|
|
As of Vault 1.6, all databases support dynamic roles and static roles. All plugins except MongoDB Atlas support rotating
|
|
the root user's credentials. MongoDB Atlas cannot support rotating the root user's credentials because it uses a public
|
|
and private key pair to authenticate.
|
|
|
|
| Database | Root Credential Rotation | Dynamic Roles | Static Roles | Username Customization |
|
|
| ----------------------------------------------------- | ------------------------ | ------------- | ------------ | ---------------------- |
|
|
| [Cassandra](/docs/secrets/databases/cassandra) | Yes | Yes | Yes (1.6+) | Yes (1.7+) |
|
|
| [Couchbase](/docs/secrets/databases/couchbase) | Yes | Yes | Yes | Yes (1.7+) |
|
|
| [Elasticsearch](/docs/secrets/databases/elasticdb) | Yes | Yes | Yes (1.6+) | Yes (1.8+) |
|
|
| [HanaDB](/docs/secrets/databases/hanadb) | Yes (1.6+) | Yes | Yes (1.6+) | No |
|
|
| [InfluxDB](/docs/secrets/databases/influxdb) | Yes | Yes | Yes (1.6+) | Yes (1.8+) |
|
|
| [MongoDB](/docs/secrets/databases/mongodb) | Yes | Yes | Yes | Yes (1.7+) |
|
|
| [MongoDB Atlas](/docs/secrets/databases/mongodbatlas) | No | Yes | Yes | Yes (1.8+) |
|
|
| [MSSQL](/docs/secrets/databases/mssql) | Yes | Yes | Yes | Yes (1.7+) |
|
|
| [MySQL/MariaDB](/docs/secrets/databases/mysql-maria) | Yes | Yes | Yes | Yes (1.7+) |
|
|
| [Oracle](/docs/secrets/databases/oracle) | Yes | Yes | Yes | Yes (1.7+) |
|
|
| [PostgreSQL](/docs/secrets/databases/postgresql) | Yes | Yes | Yes | Yes (1.7+) |
|
|
| [Redshift](/docs/secrets/databases/redshift) | Yes | Yes | Yes | Yes (1.8+) |
|
|
| [Snowflake](/docs/secrets/databases/snowflake) | Yes | Yes | Yes | Yes (1.8+) |
|
|
|
|
## Custom Plugins
|
|
|
|
This secrets engine allows custom database types to be run through the exposed
|
|
plugin interface. Please see the [custom database plugin](/docs/secrets/databases/custom)
|
|
for more information.
|
|
|
|
## Password Generation
|
|
|
|
Passwords are generated via [Password Policies](/docs/concepts/password-policies).
|
|
Databases can optionally set a password policy for use across all roles for that database.
|
|
In other words, each time you call `vault write database/config/my-database` you can specify
|
|
a password policy for all roles using `my-database`. Each database has a default password
|
|
policy defined as: 20 characters with at least 1 uppercase character, at least 1 lowercase
|
|
character, at least 1 number, and at least 1 dash character.
|
|
|
|
You cannot specify a password policy on a specific role as the purpose of password policies is
|
|
to adhere to password requirements of systems (such as a database), not making passwords
|
|
for specific users.
|
|
|
|
The default password generation can be represented as the following password policy:
|
|
|
|
```hcl
|
|
length = 20
|
|
|
|
rule "charset" {
|
|
charset = "abcdefghijklmnopqrstuvwxyz"
|
|
min-chars = 1
|
|
}
|
|
rule "charset" {
|
|
charset = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
|
|
min-chars = 1
|
|
}
|
|
rule "charset" {
|
|
charset = "0123456789"
|
|
min-chars = 1
|
|
}
|
|
rule "charset" {
|
|
charset = "-"
|
|
min-chars = 1
|
|
}
|
|
```
|
|
|
|
## Disable Character Escaping
|
|
|
|
As of Vault 1.10, you can now specify the option `disable_escaping` with a value of `true ` in
|
|
some secrets engines to prevent Vault from escaping special characters in the username and password
|
|
fields. This is necessary for some alternate connection string formats, such as ADO with MSSQL or Azure
|
|
SQL. See the [databases secrets engine API docs](/api-docs/secret/databases#common-fields) and reference
|
|
individual plugin documentation to determine support for this parameter.
|
|
|
|
For example, when the password contains URL-escaped characters like `%` or `#` they will
|
|
remain as so instead of becoming `%23` and `%25` respectively.
|
|
|
|
```shell-session
|
|
$ vault write database/config/my-mssql-database \
|
|
plugin_name="mssql-database-plugin" \
|
|
connection_url='server=localhost;port=1433;user id={{username}};password={{password}};database=mydb;' \
|
|
username="root" \
|
|
password='your#Strong(!)Password%' \
|
|
disable_escaping="true"
|
|
```
|
|
|
|
## Learn
|
|
|
|
Refer to the following step-by-step tutorials for more information:
|
|
|
|
- [Secrets as a Service: Dynamic Secrets](https://learn.hashicorp.com/vault/secrets-management/sm-dynamic-secrets)
|
|
- [Database Root Credential Rotation](https://learn.hashicorp.com/vault/secrets-management/db-root-rotation)
|
|
- [Database Static Roles and Credential Rotation](https://learn.hashicorp.com/vault/secrets-management/db-creds-rotation)
|
|
|
|
## API
|
|
|
|
The database secrets engine has a full HTTP API. Please see the [Database secret
|
|
secrets engine API](/api-docs/secret/databases) for more details.
|