luxolus/open-vault
2
0
Fork 0
Code Issues 1 Pull requests Releases Activity

Update docs for the database backend and it's plugins

Browse source
This commit is contained in:
Brian Kassouf 2017-05-02 22:24:31 -07:00
parent 7ae8f02f4b
commit 50ac77be51
5 changed files with 291 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

53
website/source/docs/secrets/databases/cassandra.html.md
View file

@ -7,3 +7,56 @@ description: |-
--- ---
# Cassandra Database Plugin # Cassandra Database Plugin
Name: `cassandra-database-plugin`
The Cassandra Database Plugin is one of the supported plugins for the Database
backend. This plugin generates database credentials dynamically based on
configured roles for the Cassandra database.
See the [Database Backend](/docs/secret/database/index.html) docs for more
information about setting up the Database Backend.
## Quick Start
After the Database Backend is mounted you can configure a cassandra connection
by specifying this plugin as the `"plugin_name"` argument. Here is an example
cassandra configuration:
```
$ vault write database/config/cassandra \
plugin_name=cassandra-database-plugin \
allowed_roles="readonly" \
hosts=localhost \
username=cassandra \
password=cassandra
The following warnings were returned from the Vault server:
* Read access to this endpoint should be controlled via ACLs as it will return the connection details as is, including passwords, if any.
```
Once the cassandra connection is configured we can add a role:
```
$ vault write database/roles/readonly \
db_name=cassandra \
creation_statements="CREATE USER '{{username}}' WITH PASSWORD '{{password}}' NOSUPERUSER; \
GRANT SELECT ON ALL KEYSPACES TO {{username}};" \
default_ttl="1h" \
max_ttl="24h"
Success! Data written to: database/roles/readonly
```
This role can be used to retrieve a new set of credentials by querying the
"database/creds/readonly" endpoint.
## API
The full list of configurable options can be seen in the [Cassandra database
plugin API](/api/secret/database/cassandra.html) page.
Or for more information on the Database secret backend's HTTP API please see the [Database secret
backend API](/api/secret/database/index.html).

88
website/source/docs/secrets/databases/index.html.md
View file

@ -8,4 +8,90 @@ description: |-
# Databases # Databases
Something Name: `Database`
The Database secret backend for Vault 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 builtin 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.
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 in using the Database backend is mounting it.
```text
$ vault mount database
Successfully mounted 'database' at 'database'!
```
Next, we must configure this backend to connect to a database. In this example
we will connect to a MySQL database, but the configuration details needed for
other plugin types can be found in their docs pages. This backend can configure
multiple database connections, therefore a name for the connection must be
provide; we'll call this one simply "mysql".
```
$ vault write database/config/mysql \
plugin_name=mysql-database-plugin \
connection_url="root:mysql@tcp(127.0.0.1:3306)/" \
allowed_roles="readonly"
The following warnings were returned from the Vault server:
* Read access to this endpoint should be controlled via ACLs as it will return the connection details as is, including passwords, if any.
```
The next step is to configure a role. A role is a logical name that maps to a
policy used to generate those credentials. A role needs to be configured with
the database name we created above, and the default/max TTLs. For example, lets
create a "readonly" role:
```
$ vault write database/roles/readonly \
db_name=mysql \
creation_statements="CREATE USER '{{name}}'@'%' IDENTIFIED BY '{{password}}';GRANT SELECT ON *.* TO '{{name}}'@'%';" \
default_ttl="1h" \
max_ttl="24h"
Success! Data written to: database/roles/readonly
```
By writing to the roles/readonly path we are defining the readonly role. This
role will be created by evaluating the given creation statements. By default,
the {{name}} and {{password}} fields will be populated by the plugin with
dynamically generated values. In other plugins the {{expiration}} field could
also be supported. 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.
Custom revocation statements could be passed too, but this plugin has a default
statement we can use.
To generate a new set of credentials, we simply read from that role:
```
$ vault read database/creds/readonly
Key Value
--- -----
lease_id database/creds/readonly/2f6a614c-4aa2-7b19-24b9-ad944a8d4de6
lease_duration 1h0m0s
lease_renewable true
password 8cab931c-d62e-a73d-60d3-5ee85139cd66
username v-root-e2978cd0-
```
## API
The Database secret backend has a full HTTP API. Please see the [Database secret
backend API](/api/secret/database/index.html) for more details.

51
website/source/docs/secrets/databases/mssql.html.md
View file

@ -7,3 +7,54 @@ description: |-
--- ---
# MSSQL Database Plugin # MSSQL Database Plugin
Name: `mssql-database-plugin`
The MSSQL Database Plugin is one of the supported plugins for the Database
backend. This plugin generates database credentials dynamically based on
configured roles for the MSSQL database.
See the [Database Backend](/docs/secret/database/index.html) docs for more
information about setting up the Database Backend.
## Quick Start
After the Database Backend is mounted you can configure a MSSQL connection
by specifying this plugin as the `"plugin_name"` argument. Here is an example
configuration:
```
$ vault write database/config/mssql \
plugin_name=mssql-database-plugin \
connection_url='sqlserver://sa:yourStrong(!)Password@localhost:1433' \
allowed_roles="readonly"
The following warnings were returned from the Vault server:
* Read access to this endpoint should be controlled via ACLs as it will return the connection details as is, including passwords, if any.
```
Once the MSSQL connection is configured we can add a role:
```
$ vault write database/roles/readonly \
db_name=mssql \
creation_statements="CREATE LOGIN [{{name}}] WITH PASSWORD = '{{password}}';\
USE AdventureWorks; CREATE USER [{{name}}] FOR LOGIN [{{name}}]; \
GRANT SELECT ON SCHEMA::dbo TO [{{name}}];" \
default_ttl="1h" \
max_ttl="24h"
Success! Data written to: database/roles/readonly
```
This role can now be used to retrieve a new set of credentials by querying the
"database/creds/readonly" endpoint.
## API
The full list of configurable options can be seen in the [MSSQL database
plugin API](/api/secret/database/mssql.html) page.
Or for more information on the Database secret backend's HTTP API please see the [Database secret
backend API](/api/secret/database/index.html).

49
website/source/docs/secrets/databases/mysql-maria.html.md
View file

@ -7,3 +7,52 @@ description: |-
--- ---
# MySQL/MariaDB Database Plugin # MySQL/MariaDB Database Plugin
Name: `mysql-database-plugin`
The MySQL Database Plugin is one of the supported plugins for the Database
backend. This plugin generates database credentials dynamically based on
configured roles for the MySQL database.
See the [Database Backend](/docs/secret/database/index.html) docs for more
information about setting up the Database Backend.
## Quick Start
After the Database Backend is mounted you can configure a MySQL connection
by specifying this plugin as the `"plugin_name"` argument. Here is an example
configuration:
```
$ vault write database/config/mysql \
plugin_name=mysql-database-plugin \
connection_url="root:mysql@tcp(127.0.0.1:3306)/" \
allowed_roles="readonly"
The following warnings were returned from the Vault server:
* Read access to this endpoint should be controlled via ACLs as it will return the connection details as is, including passwords, if any.
```
Once the MySQL connection is configured we can add a role:
```
$ vault write database/roles/readonly \
db_name=mysql \
creation_statements="CREATE USER '{{name}}'@'%' IDENTIFIED BY '{{password}}';GRANT SELECT ON *.* TO '{{name}}'@'%';" \
default_ttl="1h" \
max_ttl="24h"
Success! Data written to: database/roles/readonly
```
This role can now be used to retrieve a new set of credentials by querying the
"database/creds/readonly" endpoint.
## API
The full list of configurable options can be seen in the [MySQL database
plugin API](/api/secret/database/mysql.html) page.
Or for more information on the Database secret backend's HTTP API please see the [Database secret
backend API](/api/secret/database/index.html).

51
website/source/docs/secrets/databases/postgresql.html.md
View file

@ -7,3 +7,54 @@ description: |-
--- ---
# PostgreSQL Database Plugin # PostgreSQL Database Plugin
Name: `postgresql-database-plugin`
The PostgreSQL Database Plugin is one of the supported plugins for the Database
backend. This plugin generates database credentials dynamically based on
configured roles for the PostgreSQL database.
See the [Database Backend](/docs/secret/database/index.html) docs for more
information about setting up the Database Backend.
## Quick Start
After the Database Backend is mounted you can configure a PostgreSQL connection
by specifying this plugin as the `"plugin_name"` argument. Here is an example
configuration:
```
$ vault write database/config/postgresql \
plugin_name=postgresql-database-plugin \
allowed_roles="readonly" \
connection_url="postgresql://root:root@localhost:5432/postgres"
The following warnings were returned from the Vault server:
* Read access to this endpoint should be controlled via ACLs as it will return the connection details as is, including passwords, if any.
```
Once the PostgreSQL connection is configured we can add a role. The PostgreSQL
plugin replaces `{{expiration}}` in statements with a formated timestamp:
```
$ vault write database/roles/readonly \
db_name=postgresql \
creation_statements="CREATE ROLE \"{{name}}\" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}'; \
GRANT SELECT ON ALL TABLES IN SCHEMA public TO \"{{name}}\";" \
default_ttl="1h" \
max_ttl="24h"
Success! Data written to: database/roles/readonly
```
This role can be used to retrieve a new set of credentials by querying the
"database/creds/readonly" endpoint.
## API
The full list of configurable options can be seen in the [PostgreSQL database
plugin API](/api/secret/database/postgresql.html) page.
Or for more information on the Database secret backend's HTTP API please see the [Database secret
backend API](/api/secret/database/index.html).