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

Add API docs

This commit is contained in:
Brian Kassouf 2017-05-03 02:13:07 -07:00
parent 63de72c10f
commit dbb5b38e0d
7 changed files with 644 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

96
website/source/api/secret/databases/cassandra.html.md Normal file
View File

@ -0,0 +1,96 @@
---
layout: "api"
page_title: "Cassandra Database Plugin - HTTP API"
sidebar_current: "docs-http-secret-databases-cassandra-maria"
description: |-
The Cassandra plugin for Vault's Database backend generates database credentials to access Cassandra servers.
---
# Cassandra Database Plugin HTTP API
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.
## Configure Connection
In addition to the parameters defined by the [Database
Backend](/api/secret/databases/index.html#configure-connection), this plugin
has a number of parameters to further configure a connection.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/database/config/:name` | `204 (empty body)` |
### Parameters
- `hosts` `(string: <required>)` – Specifies a set of comma-delineated Cassandra
hosts to connect to.
- `username` `(string: <required>)` – Specifies the username to use for
superuser access.
- `password` `(string: <required>)` – Specifies the password corresponding to
the given username.
- `tls` `(bool: true)` – Specifies whether to use TLS when connecting to
Cassandra.
- `insecure_tls` `(bool: false)` – Specifies whether to skip verification of the
server certificate when using TLS.
- `pem_bundle` `(string: "")` – Specifies concatenated PEM blocks containing a
certificate and private key; a certificate, private key, and issuing CA
certificate; or just a CA certificate.
- `pem_json` `(string: "")` – Specifies JSON containing a certificate and
private key; a certificate, private key, and issuing CA certificate; or just a
CA certificate. For convenience format is the same as the output of the
`issue` command from the `pki` backend; see
[the pki documentation](/docs/secrets/pki/index.html).
- `protocol_version` `(int: 2)` – Specifies the CQL protocol version to use.
- `connect_timeout` `(string: "5s")` – Specifies the connection timeout to use.
TLS works as follows:
- If `tls` is set to true, the connection will use TLS; this happens
automatically if `pem_bundle`, `pem_json`, or `insecure_tls` is set
- If `insecure_tls` is set to true, the connection will not perform verification
of the server certificate; this also sets `tls` to true
- If only `issuing_ca` is set in `pem_json`, or the only certificate in
`pem_bundle` is a CA certificate, the given CA certificate will be used for
server certificate verification; otherwise the system CA certificates will be
used
- If `certificate` and `private_key` are set in `pem_bundle` or `pem_json`,
client auth will be turned on for the connection
`pem_bundle` should be a PEM-concatenated bundle of a private key + client
certificate, an issuing CA certificate, or both. `pem_json` should contain the
same information; for convenience, the JSON format is the same as that output by
the issue command from the PKI backend.
### Sample Payload
```json
{
"plugin_name": "cassandra-database-plugin",
"allowed_roles": "readonly",
"hosts": "cassandra1.local",
"username": "user",
"password": "pass"
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://vault.rocks/v1/cassandra/config/connection
```

342
website/source/api/secret/databases/index.html.md Normal file
View File

@ -0,0 +1,342 @@
---
layout: "api"
page_title: "Databases - HTTP API"
sidebar_current: "docs-http-secret-databases"
description: |-
Top page for database secret backend information
---
# Database Secret Backend HTTP API
This is the API documentation for the Vault Database secret backend. For
general information about the usage and operation of the Database backend,
please see the
[Vault Database backend documentation](/docs/secrets/database/index.html).
This documentation assumes the Database backend is mounted at the
`/database` path in Vault. Since it is possible to mount secret backends at
any location, please update your API calls accordingly.
## Configure Connection
This endpoint configures the connection string used to communicate with the
desired database. In addition to the parameters listed here, each Database
plugin has additional, database plugin specifig, parameters for this endpoint.
Please read the HTTP API for the plugin you'd wish to configure to see the full
list of additional parameters.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/database/config/:name` | `204 (empty body)` |
### Parameters
- `name` `(string: <required>)` – Specifies the name for this database
connection. This is specified as part of the URL.
- `plugin_name` `(string: <required>)` - Specifies the name of the plugin to use
for this connection.
- `verify_connection` `(bool: true)` – Specifies if the connection is verified
during initial configuration. Defaults to true.
- `allowed_roles` `(slice: [])` - Array or comma separated string of the roles
allowed to use this connection. Defaults to empty (no roles), if contains a
"*" any role can use this connection.
### Sample Payload
```json
{
"plugin_name": "mysql-database-plugin",
"allowed_roles": "readonly",
"connection_url": "root:mysql@tcp(127.0.0.1:3306)/"
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://vault.rocks/v1/database/config/mysql
```
## Read Connection
This endpoint returns the configuration settings for a connection.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `GET` | `/database/config/:name` | `200 application/json` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the connection to read.
This is specified as part of the URL.
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
https://vault.rocks/v1/database/config/mysql
```
### Sample Response
```json
{
"data": {
"allowed_roles": [
"readonly"
],
"connection_details": {
"connection_url": "root:mysql@tcp(127.0.0.1:3306)/",
},
"plugin_name": "mysql-database-plugin"
},
}
```
## Delete Connection
This endpoint deletes a connection.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `DELETE` | `/database/config/:name` | `204 (empty body)` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the connection to delete.
This is specified as part of the URL.
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
https://vault.rocks/v1/database/config/mysql
```
## Reset Connection
This endpoint closes a connection and it's underlying plugin and restarts it
with the configuration stored in the barrier.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/database/reset/:name` | `204 (empty body)` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the connection to delete.
This is specified as part of the URL.
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
https://vault.rocks/v1/database/reset/mysql
```
## Create Role
This endpoint creates or updates a role definition.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/database/roles/:name` | `204 (empty body)` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to create. This
is specified as part of the URL.
- `db_name` `(string: <required>)` - The name of the database connection to use
for this role.
- `default_ttl` `(string: <required>)` - Specifies the TTL for the lease
associated with this role.
- `max_ttl` `(string: <required>)` - Specifies the maximum TTL for the lease
associated with this role.
- `creation_statements` `(string: <required>)` – Specifies the database
statements executed to create and configure a user. Must be a
semicolon-separated string, a base64-encoded semicolon-separated string, a
serialized JSON string array, or a base64-encoded serialized JSON string
array. The '{{name}}', '{{password}}' and '{{expiration}}' values will be
substituted.
- `revocation_statements` `(string: "")` – Specifies the database statements to
be executed to revoke a user. Must be a semicolon-separated string, a
base64-encoded semicolon-separated string, a serialized JSON string array, or
a base64-encoded serialized JSON string array. The '{{name}}' value will be
substituted.
- `rollback_statements` `(string: "")` – Specifies the database statements to be
executed rollback a create operation in the event of an error. Not every
plugin type will support this functionality. Must be a semicolon-separated
string, a base64-encoded semicolon-separated string, a serialized JSON string
array, or a base64-encoded serialized JSON string array. The '{{name}}' value
will be substituted.
- `renew_statements` `(string: "")` – Specifies the database statements to be
executed to renew a user. Not every plugin type will support this
functionality. Must be a semicolon-separated string, a base64-encoded
semicolon-separated string, a serialized JSON string array, or a
base64-encoded serialized JSON string array. The '{{name}}' and
'{{expiration}}` values will be substituted.
### Sample Payload
```json
{
"db_name": "mysql",
"creation_statements": "CREATE USER '{{name}}'@'%' IDENTIFIED BY '{{password}}';GRANT SELECT ON *.* TO '{{name}}'@'%';",
"default_ttl": "1h",
"max_ttl": "24h"
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://vault.rocks/v1/database/roles/my-role
```
## Read Role
This endpoint queries the role definition.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `GET` | `/database/roles/:name` | `200 application/json` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to read. This
is specified as part of the URL.
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
https://vault.rocks/v1/database/roles/my-role
```
### Sample Response
```json
{
"data": {
"creation_statements": "CREATE ROLE \"{{name}}\" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}'; GRANT SELECT ON ALL TABLES IN SCHEMA public TO \"{{name}}\";",
"db_name": "mysql",
"default_ttl": 3600,
"max_ttl": 86400,
"renew_statements": "",
"revocation_statements": "",
"rollback_statements": ""
},
}
```
## List Roles
This endpoint returns a list of available roles. Only the role names are
returned, not any values.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `LIST` | `/database/roles` | `200 application/json` |
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
https://vault.rocks/v1/database/roles
```
### Sample Response
```json
{
"auth": null,
"data": {
"keys": ["dev", "prod"]
},
"lease_duration": 2764800,
"lease_id": "",
"renewable": false
}
```
## Delete Role
This endpoint deletes the role definition.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `DELETE` | `/database/roles/:name` | `204 (empty body)` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to delete. This
is specified as part of the URL.
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
https://vault.rocks/v1/database/roles/my-role
```
## Generate Credentials
This endpoint generates a new set of dynamic credentials based on the named
role.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `GET` | `/database/creds/:name` | `200 application/json` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to create
credentials against. This is specified as part of the URL.
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
https://vault.rocks/v1/database/creds/my-role
```
### Sample Response
```json
{
"data": {
"username": "root-1430158508-126",
"password": "132ae3ef-5a64-7499-351e-bfe59f3a2a21"
}
}
```

60
website/source/api/secret/databases/mssql.html.md Normal file
View File

@ -0,0 +1,60 @@
---
layout: "api"
page_title: "MSSQL Database Plugin - HTTP API"
sidebar_current: "docs-http-secret-databases-mssql-maria"
description: |-
The MSSQL plugin for Vault's Database backend generates database credentials to access MSSQL servers.
---
# MSSQL Database Plugin HTTP API
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.
## Configure Connection
In addition to the parameters defined by the [Database
Backend](/api/secret/databases/index.html#configure-connection), this plugin
has a number of parameters to further configure a connection.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/database/config/:name` | `204 (empty body)` |
### Parameters
- `connection_url` `(string: <required>)` - Specifies the MSSQL DSN.
- `max_open_connections` `(int: 2)` - Speficies the name of the plugin to use
for this connection.
- `max_idle_connections` `(int: 0)` - Specifies the maximum number of idle
connections to the database. A zero uses the value of `max_open_connections`
and a negative value disables idle connections. If larger than
`max_open_connections` it will be reduced to be equal.
- `max_connection_lifetime` `(string: "0s")` - Specifies the maximum amount of
time a connection may be reused. If <= 0s connections are reused forever.
### Sample Payload
```json
{
"plugin_name": "mssql-database-plugin",
"allowed_roles": "readonly",
"connection_url": "sqlserver://sa:yourStrong(!)Password@localhost:1433",
"max_open_connections": 5,
"max_connection_lifetime": "5s",
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://vault.rocks/v1/database/config/mssql
```

60
website/source/api/secret/databases/mysql-maria.html.md Normal file
View File

@ -0,0 +1,60 @@
---
layout: "api"
page_title: "MySQL/MariaDB Database Plugin - HTTP API"
sidebar_current: "docs-http-secret-databases-mysql-maria"
description: |-
The MySQL/MariaDB plugin for Vault's Database backend generates database credentials to access MySQL and MariaDB servers.
---
# MySQL/MariaDB Database Plugin HTTP API
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.
## Configure Connection
In addition to the parameters defined by the [Database
Backend](/api/secret/databases/index.html#configure-connection), this plugin
has a number of parameters to further configure a connection.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/database/config/:name` | `204 (empty body)` |
### Parameters
- `connection_url` `(string: <required>)` - Specifies the MySQL DSN.
- `max_open_connections` `(int: 2)` - Speficies the name of the plugin to use
for this connection.
- `max_idle_connections` `(int: 0)` - Specifies the maximum number of idle
connections to the database. A zero uses the value of `max_open_connections`
and a negative value disables idle connections. If larger than
`max_open_connections` it will be reduced to be equal.
- `max_connection_lifetime` `(string: "0s")` - Specifies the maximum amount of
time a connection may be reused. If <= 0s connections are reused forever.
### Sample Payload
```json
{
"plugin_name": "mysql-database-plugin",
"allowed_roles": "readonly",
"connection_url": "root:mysql@tcp(127.0.0.1:3306)/"
"max_open_connections": 5,
"max_connection_lifetime": "5s",
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://vault.rocks/v1/database/config/mysql
```

60
website/source/api/secret/databases/postgresql.html.md Normal file
View File

@ -0,0 +1,60 @@
---
layout: "api"
page_title: "PostgreSQL Database Plugin - HTTP API"
sidebar_current: "docs-http-secret-databases-postgresql-maria"
description: |-
The PostgreSQL plugin for Vault's Database backend generates database credentials to access PostgreSQL servers.
---
# PostgreSQL Database Plugin HTTP API
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.
## Configure Connection
In addition to the parameters defined by the [Database
Backend](/api/secret/databases/index.html#configure-connection), this plugin
has a number of parameters to further configure a connection.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/database/config/:name` | `204 (empty body)` |
### Parameters
- `connection_url` `(string: <required>)` - Specifies the PostgreSQL DSN.
- `max_open_connections` `(int: 2)` - Speficies the name of the plugin to use
for this connection.
- `max_idle_connections` `(int: 0)` - Specifies the maximum number of idle
connections to the database. A zero uses the value of `max_open_connections`
and a negative value disables idle connections. If larger than
`max_open_connections` it will be reduced to be equal.
- `max_connection_lifetime` `(string: "0s")` - Specifies the maximum amount of
time a connection may be reused. If <= 0s connections are reused forever.
### Sample Payload
```json
{
"plugin_name": "postgresql-database-plugin",
"allowed_roles": "readonly",
"connection_url": "postgresql://root:root@localhost:5432/postgres",
"max_open_connections": 5,
"max_connection_lifetime": "5s",
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
https://vault.rocks/v1/database/config/postgresql
```

5
website/source/docs/secrets/databases/custom.html.md
View File

@ -11,7 +11,8 @@ description: |-
The Database backend allows new functionality to be added through a plugin
interface without needing to modify vault's core code. This allows you write
your own code to generate credentials in any database you wish. It also allows
databases that require dynamically linked libraries to be used with vault.
databases that require dynamically linked libraries to be used as plugins while
keeping Vault itself statically linked.
~> **Advanced topic!** Plugin development is a highly advanced
topic in Vault, and is not required knowledge for day-to-day usage.
@ -81,7 +82,7 @@ Replacing `MyPlugin` with the actual implementation of your plugin.
The second parameter to `Serve` takes in an optional vault `api.TLSConfig` for
configuring the plugin to communicate with vault for the initial unwrap call.
This if useful if your vault setup requires client certificate checks. This
This is useful if your vault setup requires client certificate checks. This
config wont be used once the plugin unwraps its own TLS cert and key.
## Running your plugin

27
website/source/layouts/api.erb
View File

@ -21,7 +21,7 @@
<a href="/api/secret/aws/index.html">AWS</a>
</li>
<li<%= sidebar_current("docs-http-secret-cassandra") %>>
<a href="/api/secret/cassandra/index.html">Cassandra</a>
<a href="/api/secret/cassandra/index.html">Cassandra (Deprecated)</a>
</li>
<li<%= sidebar_current("docs-http-secret-consul") %>>
<a href="/api/secret/consul/index.html">Consul</a>
@ -29,6 +29,25 @@
<li<%= sidebar_current("docs-http-secret-cubbyhole") %>>
<a href="/api/secret/cubbyhole/index.html">Cubbyhole</a>
</li>
<li<%= sidebar_current("docs-http-secret-databases") %>>
<a href="/api/secret/databases/index.html">Databases (Beta)</a>
<ul class="nav">
<li<%= sidebar_current("docs-http-secret-databases-cassandra") %>>
<a href="/api/secret/databases/cassandra.html">Cassandra</a>
</li>
<li<%= sidebar_current("docs-http-secret-databases-mssql") %>>
<a href="/api/secret/databases/mssql.html">MSSQL</a>
</li>
<li<%= sidebar_current("docs-http-secret-databases-mysql-maria") %>>
<a href="/api/secret/databases/mysql-maria.html">MySQL/MariaDB</a>
</li>
<li<%= sidebar_current("docs-http-secret-databases-postgresql") %>>
<a href="/api/secret/databases/postgresql.html">PostgreSQL</a>
</li>
</ul>
</li>
<li<%= sidebar_current("docs-http-secret-generic") %>>
<a href="/api/secret/generic/index.html">Generic</a>
</li>
@ -36,16 +55,16 @@
<a href="/api/secret/mongodb/index.html">MongoDB</a>
</li>
<li<%= sidebar_current("docs-http-secret-mssql") %>>
<a href="/api/secret/mssql/index.html">MSSQL</a>
<a href="/api/secret/mssql/index.html">MSSQL (Deprecated)</a>
</li>
<li<%= sidebar_current("docs-http-secret-mysql") %>>
<a href="/api/secret/mysql/index.html">MySQL</a>
<a href="/api/secret/mysql/index.html">MySQL (Deprecated)</a>
</li>
<li<%= sidebar_current("docs-http-secret-pki") %>>
<a href="/api/secret/pki/index.html">PKI</a>
</li>
<li<%= sidebar_current("docs-http-secret-postgresql") %>>
<a href="/api/secret/postgresql/index.html">PostgreSQL</a>
<a href="/api/secret/postgresql/index.html">PostgreSQL (Deprecated)</a>
</li>
<li<%= sidebar_current("docs-http-secret-rabbitmq") %>>
<a href="/api/secret/rabbitmq/index.html">RabbitMQ</a>