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.
Register the plugin in Vault’s plugin catalog:
$ 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.