161 lines
6.5 KiB
Plaintext
161 lines
6.5 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Oracle - Database - Secrets Engines
|
|
description: |-
|
|
Oracle 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.
|
|
---
|
|
|
|
# Oracle Database Secrets Engine
|
|
|
|
This secrets engine is a part of the Database Secrets Engine. If you have not read the
|
|
[Database Backend](/docs/secrets/databases) page, please do so now as it explains how to set up the database backend and
|
|
gives an overview of how the engine functions.
|
|
|
|
Oracle is one of the supported plugins for the database secrets engine. It is capable of dynamically generating
|
|
credentials based on configured roles for Oracle databases. It also supports [Static Roles](/docs/secrets/databases#static-roles).
|
|
|
|
~> The Oracle database plugin is not bundled 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)
|
|
|
|
## Capabilities
|
|
|
|
| Plugin Name | Root Credential Rotation | Dynamic Roles | Static Roles |
|
|
| -------------------------------------------------------------------- | ------------------------ | ------------- | ------------ |
|
|
| Customizable (see: [Custom Plugins](/docs/secrets/databases/custom)) | Yes | Yes | Yes |
|
|
|
|
## Setup
|
|
|
|
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)
|
|
|
|
For linux/amd64, pre-built binaries can be found at [the releases page](https://releases.hashicorp.com/vault-plugin-database-oracle)
|
|
|
|
Before running the plugin you will need to have the the Oracle Instant Client
|
|
library installed. These can be downloaded from Oracle. The libraries will need to
|
|
be placed in the default library search path or defined in the ld.so.conf configuration files.
|
|
|
|
If you are running Vault with [mlock enabled](/docs/configuration#disable_mlock),
|
|
you will need to enable ipc_lock capabilities for the plugin binary.
|
|
|
|
1. Enable the database secrets engine if it is not already enabled:
|
|
|
|
```shell
|
|
$ vault secrets enable database
|
|
Success! Enabled the database secrets engine at: database/
|
|
```
|
|
|
|
By default, the secrets engine will enable at the name of the engine. To
|
|
enable the secrets engine at a different path, use the `-path` argument.
|
|
|
|
1. Download and register the plugin:
|
|
|
|
```shell
|
|
$ vault write sys/plugins/catalog/database/oracle-database-plugin \
|
|
sha256="..." \
|
|
command=vault-plugin-database-oracle
|
|
```
|
|
|
|
1. Configure Vault with the proper plugin and connection information:
|
|
|
|
```shell
|
|
$ vault write database/config/my-oracle-database \
|
|
plugin_name=oracle-database-plugin \
|
|
connection_url="{{username}}/{{password}}@localhost:1521/OraDoc.localhost" \
|
|
allowed_roles="my-role" \
|
|
username="VAULT_SUPER_USER" \
|
|
password="myreallysecurepassword"
|
|
```
|
|
|
|
If Oracle uses SSL, see the [connecting using SSL](/docs/secrets/databases/oracle#connect-using-ssl) example.
|
|
|
|
If the version of Oracle you are using has a container database, you will need to connect to one of the
|
|
pluggable databases rather than the container database in the `connection_url` field.
|
|
|
|
1. It is highly recommended that you immediately rotate the "root" user's password, see
|
|
[Rotate Root Credentials](/api-docs/secret/databases#rotate-root-credentials) for more details.
|
|
This will ensure that only Vault is able to access the "root" user that Vault uses to
|
|
manipulate dynamic & static credentials.
|
|
|
|
!> **Use caution:** the root user's password will not be accessible once rotated so it is highly
|
|
recommended that you create a user for Vault to utilize rather than using the actual root user.
|
|
|
|
1. Configure a role that maps a name in Vault to an SQL statement to execute to
|
|
create the database credential:
|
|
|
|
```shell
|
|
$ vault write database/roles/my-role \
|
|
db_name=my-oracle-database \
|
|
creation_statements='CREATE USER {{username}} IDENTIFIED BY "{{password}}"; GRANT CONNECT TO {{username}}; GRANT CREATE SESSION TO {{username}};' \
|
|
default_ttl="1h" \
|
|
max_ttl="24h"
|
|
Success! Data written to: database/roles/my-role
|
|
```
|
|
|
|
Note: The `creation_statements` may be specified in a file and interpreted by the Vault CLI using the `@` symbol:
|
|
|
|
```shell
|
|
$ vault write database/roles/my-role \
|
|
creation_statements=@creation_statements.sql \
|
|
...
|
|
```
|
|
|
|
See the [Commands](/docs/commands#files) docs for more details.
|
|
|
|
### Connect Using SSL
|
|
|
|
If the Oracle server Vault is trying to connect to uses an SSL listener, the database
|
|
plugin will require additional configuration using the `connection_url` parameter:
|
|
|
|
```shell
|
|
vault write database/config/oracle \
|
|
plugin_name=vault-plugin-database-oracle \
|
|
connection_url='{{ username }}/{{ password }}@tcps://<host>:port/<service_name>?param1=...¶m2=...&...'\
|
|
allowed_roles="my-role" \
|
|
username="admin" \
|
|
password="password"
|
|
```
|
|
|
|
For example, the SSL server certificate distinguished name and path to the Oracle Wallet
|
|
to use for connection and verification could be configured using:
|
|
|
|
```shell
|
|
vault write database/config/oracle \
|
|
plugin_name=vault-plugin-database-oracle \
|
|
connection_url='{{ username }}/{{ password }}@tcps://<host>:port/<service_name>?ssl_server_cert_dn="CN=hashicorp.com,OU=TestCA,O=HashiCorp=com"&wallet_location="/etc/oracle/wallets"' \
|
|
allowed_roles="my-role" \
|
|
username="admin" \
|
|
password="password"
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Dynamic Credentials
|
|
|
|
After the secrets engine is configured and a user/machine has a Vault token with
|
|
the proper permission, it can generate credentials.
|
|
|
|
1. Generate a new credential by reading from the `/creds` endpoint with the name
|
|
of the role:
|
|
|
|
```text
|
|
$ vault read database/creds/my-role
|
|
Key Value
|
|
--- -----
|
|
lease_id database/creds/my-role/2f6a614c-4aa2-7b19-24b9-ad944a8d4de6
|
|
lease_duration 1h
|
|
lease_renewable true
|
|
password yRUSyd-vPYDg5NkU9kDg
|
|
username V_VAULTUSE_MY_ROLE_SJJUK3Q8W3BKAYAN8S62_1602543009
|
|
```
|
|
|
|
## API
|
|
|
|
The full list of configurable options can be seen in the [Oracle database plugin
|
|
API](/api/secret/databases/oracle) page.
|
|
|
|
For more information on the database secrets engine's HTTP API please see the
|
|
[Database secrets engine API](/api/secret/databases) page.
|