Enabling Oracle Database Secrets Engine – HashiCorp Help Center

This is a comprehensive general guide to enabling the Oracle Database Secrets Engine Vault plugin.

Prerequisites

Vault version 0.8.1 or higher
- The Oracle Database Secrets Engine is currently only available for Linux based Vault servers
Oracle Database server
- This guide tested with Enterprise Edition version 12.2.0.1
Oracle Instant Client
- This guide tested with InstantClient version 12.2.0.1
Define a plugin_directory in your Vault server configuration

Oracle Instant Client Installation

Follow the InstantClient installation instructions for your version to properly install it, making sure that it has been added to the system library cache and that the libaio/libaio1 dependency package has also been installed.

Vault Plugin Installation

Download the latest version of vault-plugin-database-oracle and unzip it into the plugin_directory path you previously defined in the Prerequisites items.

Record the SHA256 summary of the vault-plugin-database-oracle binary for use in configuration:

$ sha256sum vault-plugin-database-oracle
7f7653bb546ad7df9b21204517597234a0b3151aeb9ce3bb8a9103c12f9627e6  vault-plugin-database-oracle

If you are using mlock() with Vault, set the capability on the plugin binary also:

$ sudo setcap cap_ipc_lock=+ep vault-plugin-database-oracle

Enable database Secrets Engine plugins if necessary:

$ vault secrets enable database
Success! Enabled the database secrets engine at: database/

NOTE: In versions of Vault prior to 1.1.0 the API is different and uses a plural form of plugin: sys/plugins/catalog/oracle-database-plugin so you might need to update the following command accordingly.

$ vault write sys/plugin/catalog/oracle-database-plugin \
  sha_256="7f7653bb546ad7df9b21204517597234a0b3151aeb9ce3bb8a9103c12f9627e6" \
  command=vault-plugin-database-oracle
Success! Data written to: sys/plugins/catalog/oracle-database-plugin

Write the connection configuration:

$ vault write database/config/my-oracle-database \
  plugin_name=oracle-database-plugin \
  connection_url="system/vaultron123456@172.17.0.3:1521/orclpdb1" \
  allowed_roles="my-role"

The plugin is now registered for use and successfully connected to the Oracle database. You can proceed to creating roles from allowed_roles and issuing credentials.

Troubleshooting

If your Vault process requires mlock() and you have not added that capability to the plugin binary with setcap, you could encounter an error like this from the CLI client when attempting to write the connection configuration:

Error writing data to database/config/my-oracle-database: Error making API request.

URL: PUT http://localhost:8200/v1/database/config/my-oracle-database
Code: 400. Errors:

* error creating database object: Unrecognized remote plugin message: cannot allocate memory

This could means that the plugin binary is either invalid or needs to be recompiled to support the latest plugin protocol.

If the Oracle Client libraries are not installed, you could encounter an error like this in the Vault operational logs (so long as Vault is logging at trace level) when attempting to write the connection configuration:

...
Oct 02 19:43:14 vault-nano-bionic vault[14643]: 2018-10-02T19:43:14.334Z [DEBUG] secrets.database.database_a2520397.oracle-database-plugin.vault-plugin-database-oracle: /home/vagrant/vault_nano/plugins/vault-plugin-database-oracle: error while loading shared libraries: libclntsh.so.12.1: cannot open shared object file: No such file or directory
...

If your Oracle server cannot be reached on the network by the Vault server, you could encounter an error like this from the CLI client when attempting to write the connection configuration:

Error writing data to database/config/my-oracle-database: Error making API request.

URL: PUT http://localhost:8200/v1/database/config/my-oracle-database
Code: 400. Errors:

* error creating database object: rpc error: code = Unknown desc = error verifying connection: ping failed

If your plugin version is out of date in relation to your Vault server, you could encounter an error like this from the CLI client when attempting to write the connection configuration:

Error writing data to database/config/my-oracle-database: Error making API request.

URL: PUT http://localhost:8200/v1/database/config/my-oracle-database
Code: 400. Errors:

* error creating database object: Unrecognized remote plugin message: cannot allocate memory

This usually means that the plugin is either invalid or simply needs to be recompiled to support the latest protocol.

Building from Source

The vault-database-plugin-oracle GitHub is open source and for certain use cases it can be desirable to build the plugin from source code.

Please review the Build instructions in the repository for further details on building the plugin.

Resources