| --- |
| layout: api |
| page_title: Oracle - Database - Secrets Engines - HTTP API |
| description: >- |
| The Oracle plugin for Vault's database secrets engine 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 |
| secrets engine. 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](/vault/api-docs/secret/databases#configure-connection), this plugin |
| has a number of parameters to further configure a connection. |
| |
| | Method | Path | |
| | :----- | :----------------------- | |
| | `POST` | `/database/config/:name` | |
| |
| ### Parameters |
| |
| - `connection_url` `(string: <required>)` - Specifies the Oracle DSN. |
| |
| - `max_open_connections` `(int: 4)` - 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. |
| |
| - `username` `(string: "")` - The root credential username used in the connection URL. |
| |
| - `password` `(string: "")` - The root credential password used in the connection URL. |
| |
| - `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how |
| dynamic usernames are generated. |
| |
| - `disable_escaping` `(boolean: false)` - Turns off the escaping of special characters inside of the username |
| and password fields. See the [databases secrets engine docs](/vault/docs/secrets/databases#disable-character-escaping) |
| for more information. Defaults to `false`. |
| |
| <details> |
| <summary><b>Default Username Template</b></summary> |
| |
| ``` |
| {{ printf "V_%s_%s_%s_%s" (.DisplayName | truncate 8) (.RoleName | truncate 8) (random 20) (unix_time) | truncate 30 | uppercase | replace "-" "_" | replace "." "_" }} |
| ``` |
| |
| <details> |
| <summary><b>Example Usernames:</b></summary> |
| |
| | Example | | |
| | ------------- | -------------------------------- | |
| | `DisplayName` | `token` | |
| | `RoleName` | `myrolename` | |
| | Username | `V_TOKEN_MYROLENA_JNFRLKSZZMXJE` | |
| |
| | Example | | |
| | ------------- | -------------------------------- | |
| | `DisplayName` | `amuchlonger_dispname` | |
| | `RoleName` | `role-name-with-dashes` | |
| | Username | `V_AMUCHLON_ROLE_NAM_LUHU9XQM6Y` | |
| |
| </details> |
| </details> |
| |
| ### Sample payload |
| |
| ```json |
| { |
| "plugin_name": "oracle-database-plugin", |
| "allowed_roles": "readonly", |
| "connection_url": "{{username}}/{{password}}@localhost:1521/OraDoc.localhost", |
| "max_open_connections": 5, |
| "max_connection_lifetime": "5s", |
| "username": "system", |
| "password": "Oracle" |
| } |
| ``` |
| |
| ### Sample request |
| |
| ```shell-session |
| $ curl \ |
| --header "X-Vault-Token: ..." \ |
| --request POST \ |
| --data @payload.json \ |
| http://127.0.0.1:8200/v1/database/config/oracle |
| ``` |
| |
| ## Statements |
| |
| Statements are configured during role creation and are used by the plugin to |
| determine what is sent to the database on user creation, renewing, and |
| revocation. For more information on configuring roles see the [Role |
| API](/vault/api-docs/secret/databases#create-role) in the database secrets engine 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. |