Oracle plugin docs (#3131)
* Add oracle database docs * Add oracle database docs * Fix commas in json output * Update oracle.html.md
This commit is contained in:
Brian Kassouf
GitHub
parent
c1e6e0bdf2
commit
89b81bcb4c
83
website/source/api/secret/databases/oracle.html.md
Normal file
83
website/source/api/secret/databases/oracle.html.md
Normal file
|
|
@ -0,0 +1,83 @@
|
|||
---
|
||||
layout: "api"
|
||||
page_title: "Oracle Database Plugin - HTTP API"
|
||||
sidebar_current: "docs-http-secret-databases-oracle-maria"
|
||||
description: |-
|
||||
The Oracle plugin for Vault's Database backend generates database credentials to access Oracle servers.
|
||||
---
|
||||
|
||||
# Oracle Database Plugin HTTP API
|
||||
|
||||
The Oracle Database Plugin is one of the supported plugins for the Database
|
||||
backend. This plugin generates database credentials dynamically based on
|
||||
configured roles for the Oracle 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 Oracle DSN.
|
||||
|
||||
- `max_open_connections` `(int: 2)` - Specifies the maximum number of open
|
||||
connections to the database.
|
||||
|
||||
- `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": "oracle-database-plugin",
|
||||
"allowed_roles": "readonly",
|
||||
"connection_url": "system/Oracle@localhost:1521/OraDoc.localhost",
|
||||
"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/oracle
|
||||
```
|
||||
|
||||
## Statements
|
||||
|
||||
Statements are configured during role creation and are used by the plugin to
|
||||
determine what is sent to the datatabse on user creation, renewing, and
|
||||
revocation. For more information on configuring roles see the [Role
|
||||
API](/api/secret/databases/index.html#create-role) in the Database Backend docs.
|
||||
|
||||
### Parameters
|
||||
|
||||
The following are the statements used by this plugin. If not mentioned in this
|
||||
list the plugin does not support that statement type.
|
||||
|
||||
- `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}}' and '{{password}}' 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. If not provided defaults to a generic drop user statement.
|
||||
73
website/source/docs/secrets/databases/oracle.html.md
Normal file
73
website/source/docs/secrets/databases/oracle.html.md
Normal file
|
|
@ -0,0 +1,73 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Oracle Database Plugin"
|
||||
sidebar_current: "docs-secrets-databases-oracle"
|
||||
description: |-
|
||||
The Oracle Database plugin for Vault's Database backend generates database credentials to access Oracle Database severs.
|
||||
---
|
||||
|
||||
# Oracle Database Plugin
|
||||
|
||||
Name: `oracle-database-plugin`
|
||||
|
||||
The Oracle Database Plugin is an external plugin for the Database
|
||||
backend. This plugin generates database credentials dynamically based on
|
||||
configured roles for the Oracle database.
|
||||
|
||||
The Oracle Database Plugin does not live in the core Vault code tree and can be found
|
||||
at its own git repository here: [hashicorp/vault-plugin-database-oracle](https://github.com/hashicorp/vault-plugin-database-oracle)
|
||||
|
||||
See the [Database Backend](/docs/secrets/databases/index.html) docs for more
|
||||
information about setting up the Database Backend.
|
||||
|
||||
## Quick Start
|
||||
|
||||
After the Database Backend is mounted you can run the plugin and configure a
|
||||
connection to the Oracle Database.
|
||||
|
||||
First the plugin must be built and registered to Vault's plugin catalog. To
|
||||
build the plugin see the plugin's code repository. Once the plugin is built and
|
||||
the binary is placed in Vault's plugin directory the catalog should be updated:
|
||||
|
||||
```
|
||||
$ vault write sys/plugins/catalog/oracle-database-plugin \
|
||||
sha_256=<expected SHA256 value> \
|
||||
command=oracle-database-plugin
|
||||
```
|
||||
|
||||
Once the plugin exists in the plugin catalog the Database backend can configure
|
||||
a connection for the Oracle Database:
|
||||
|
||||
```
|
||||
$ vault write database/config/oracle \
|
||||
plugin_name=oracle-database-plugin \
|
||||
connection_url="system/Oracle@localhost:1521/OraDoc.localhost" \
|
||||
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 Oracle connection is configured we can add a role:
|
||||
|
||||
```
|
||||
$ vault write database/roles/readonly \
|
||||
db_name=oracle \
|
||||
creation_statements="CREATE USER {{name}} IDENTIFIED BY {{password}}; GRANT CONNECT TO {{name}}; GRANT CREATE SESSION 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 [Oracle database
|
||||
plugin API](/api/secret/databases/oracle.html) page.
|
||||
|
||||
For more information on the Database secret backend's HTTP API please see the [Database secret
|
||||
backend API](/api/secret/databases/index.html) page.
|
||||
|
||||
|
|
@ -44,6 +44,9 @@
|
|||
<li<%= sidebar_current("docs-http-secret-databases-postgresql") %>>
|
||||
<a href="/api/secret/databases/postgresql.html">PostgreSQL</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-http-secret-databases-oracle") %>>
|
||||
<a href="/api/secret/databases/oracle.html">Oracle</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
|
||||
|
|
|
|||
|
|
@ -204,6 +204,9 @@
|
|||
<li<%= sidebar_current("docs-secrets-databases-postgresql") %>>
|
||||
<a href="/docs/secrets/databases/postgresql.html">PostgreSQL</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-secrets-databases-oracle") %>>
|
||||
<a href="/docs/secrets/databases/oracle.html">Oracle</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-secrets-databases-custom") %>>
|
||||
<a href="/docs/secrets/databases/custom.html">Custom</a>
|
||||
</li>
|
||||
|
|
|
|||
Loading…
Reference in a new issue