From 50ac77be5171ac7153fa7c08d0ab9aace5a56cdd Mon Sep 17 00:00:00 2001 From: Brian Kassouf Date: Tue, 2 May 2017 22:24:31 -0700 Subject: [PATCH] Update docs for the database backend and it's plugins --- .../docs/secrets/databases/cassandra.html.md | 53 +++++++++++ .../docs/secrets/databases/index.html.md | 88 ++++++++++++++++++- .../docs/secrets/databases/mssql.html.md | 51 +++++++++++ .../secrets/databases/mysql-maria.html.md | 49 +++++++++++ .../docs/secrets/databases/postgresql.html.md | 51 +++++++++++ 5 files changed, 291 insertions(+), 1 deletion(-) diff --git a/website/source/docs/secrets/databases/cassandra.html.md b/website/source/docs/secrets/databases/cassandra.html.md index 012e7db5b..99d3d3bf9 100644 --- a/website/source/docs/secrets/databases/cassandra.html.md +++ b/website/source/docs/secrets/databases/cassandra.html.md @@ -7,3 +7,56 @@ description: |- --- # 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). + diff --git a/website/source/docs/secrets/databases/index.html.md b/website/source/docs/secrets/databases/index.html.md index 20f7bbed2..cf366d9c9 100644 --- a/website/source/docs/secrets/databases/index.html.md +++ b/website/source/docs/secrets/databases/index.html.md @@ -8,4 +8,90 @@ description: |- # 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. + diff --git a/website/source/docs/secrets/databases/mssql.html.md b/website/source/docs/secrets/databases/mssql.html.md index 32ecf7775..2d220ddb8 100644 --- a/website/source/docs/secrets/databases/mssql.html.md +++ b/website/source/docs/secrets/databases/mssql.html.md @@ -7,3 +7,54 @@ description: |- --- # 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). + diff --git a/website/source/docs/secrets/databases/mysql-maria.html.md b/website/source/docs/secrets/databases/mysql-maria.html.md index 1ee601dbd..bd61cc43b 100644 --- a/website/source/docs/secrets/databases/mysql-maria.html.md +++ b/website/source/docs/secrets/databases/mysql-maria.html.md @@ -7,3 +7,52 @@ description: |- --- # 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). + diff --git a/website/source/docs/secrets/databases/postgresql.html.md b/website/source/docs/secrets/databases/postgresql.html.md index 5de340043..e5fee10ef 100644 --- a/website/source/docs/secrets/databases/postgresql.html.md +++ b/website/source/docs/secrets/databases/postgresql.html.md @@ -7,3 +7,54 @@ description: |- --- # 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). +