This is a comprehensive general guide to enabling the Oracle Database Secrets Engine Vault plugin.
Prerequisites
- Vault version v1.8.x or higher
- The Oracle Database Secrets Engine is currently only available for Linux based Vault servers
- Oracle Database server
- This guide tested with Oracle Database 21c Express Edition
- Oracle Instant Client
- This guide tested with InstantClient version
19.17.0.0.0.
- This guide tested with InstantClient version
- 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. Ensure that the following packages are installed on the OS, which are required by the InstantClient.libaio(redhat/centos)/libaio1(ubuntu)libaiolibnslglibc
Note: If you are using mlock() with Vault, it is recommended to set the instant client shared library directory in the following manner.
sudo sh -c "echo $INSTANT_CLIENT_DIR > /etc/ld.so.conf.d/oracle-instantclient.conf"
sudo ldconfigReplace $INSTANT_CLIENT_DIRwith the instant client directory location.
Note: The instant client version 19.1X.0.0.0 is recommended for plugin versions 0.1.6 and above as the vault plugin specifically references the libclntsh.so.19.1shared library within the instant client directory. Other versions of the instant client use symbolic links for backwards compatibility, which may not always work.
Running ldd vault-plugin-database-oracle can help identify if the shared libraries are being linked to the plugin.
Example shared library references for the vault-plugin-database-oracle plugin
$ ldd vault-plugin-database-oracle
linux-vdso.so.1 (0x00007fff50bce000)
libclntsh.so.19.1 => /opt/oracle/instantclient_19_17/libclntsh.so.19.1 (0x00007f904f69d000)
libpthread.so.0 => /lib64/libpthread.so.0 (0x00007f904f47d000)
libc.so.6 => /lib64/libc.so.6 (0x00007f904f0b8000)
libnnz19.so => /opt/oracle/instantclient_19_17/libnnz19.so (0x00007f904ea43000)
libdl.so.2 => /lib64/libdl.so.2 (0x00007f904e83f000)
libm.so.6 => /lib64/libm.so.6 (0x00007f904e4bd000)
libnsl.so.1 => /lib64/libnsl.so.1 (0x00007f904e2a4000)
librt.so.1 => /lib64/librt.so.1 (0x00007f904e09c000)
libaio.so.1 => /lib64/libaio.so.1 (0x00007f904de99000)
libresolv.so.2 => /lib64/libresolv.so.2 (0x00007f904dc82000)
/lib64/ld-linux-x86-64.so.2 (0x00007f90537df000)
libclntshcore.so.19.1 => /opt/oracle/instantclient_19_17/libclntshcore.so.19.1 (0x00007f904d6de000)
Vault Plugin Installation
Download the latest version of vault-plugin-database-oracle and unzip it into the plugin_directory path that was 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
b17856c5465dd687f2b1805ec3b7b18facaffd82073ba05bb12120b965a3285d vault-plugin-database-oracleIf you are using mlock() with Vault, set the capability on the plugin binary:
$ sudo setcap cap_ipc_lock=+ep vault-plugin-database-oracleEnable database Secrets Engine plugins if necessary:
$ vault secrets enable database
Success! Enabled the database secrets engine at: database/Register the plugin in Vault’s data plugin catalog:
$ vault plugin register \
-sha256="b17856c5465dd687f2b1805ec3b7b18facaffd82073ba05bb12120b965a3285d" \
database vault-plugin-database-oracle
Success! Registered plugin: vault-plugin-database-oracle
Note: In versions v1.12.x or higher, a version number can be added apart of the registration process.
$ vault plugin register \
-sha256="b17856c5465dd687f2b1805ec3b7b18facaffd82073ba05bb12120b965a3285d" \
-version=v0.7.0 database vault-plugin-database-oracle
Success! Registered plugin: vault-plugin-database-oracle
Check the plugin is registered in the database plugin catalog:
$ vault plugin info database vault-plugin-database-oracle
Key Value
--- -----
args []
builtin false
command vault-plugin-database-oracle
name vault-plugin-database-oracle
sha256 b17856c5465dd687f2b1805ec3b7b18facaffd82073ba05bb12120b965a3285d
Create a role:
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/config/my-oracle-database
Write the connection configuration:
$ vault write database/config/my-oracle-database \
plugin_name=vault-plugin-database-oracle \
connection_url="{{username}}/{{password}}@127.0.0.1:1521/XEPDB1" \
username="vault" \
password="vaultpasswd" \
allowed_roles=my-role \
max_connection_lifetime=60s
Success! Data written to: database/config/my-oracle-database
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
For connections which have already been configured and want to validate if it can connect to the database, a good test is to issue a reset. This closes the connection and stops the plugin, then restarts it with the stored configuration.
$ vault write -f database/reset/my-oracle-database
Success! Data written to: database/reset/my-oracle-database
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 the following 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 the following from the Vault operational logs (logging set to DEBUG level) when attempting to write the connection configuration:
2022-11-15T18:15:26.097Z [DEBUG] secrets.database.database_bd925962.oracle-database-plugin.vault-plugin-database-oracle:
/etc/vault.d/plugins/vault-plugin-database-oracle: error while loading shared libraries: libclntsh.so.19.1: cannot open shared object file: No such file or directory
If your Oracle database cannot be reached on the network by the Vault server, you could encounter an error like the following 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 failedIf your Oracle database is able to connect, but unable to reach the specified database (due to port not open or other factors), you could encounter an error like the following 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://127.0.0.1:8200/v1/database/config/my-oracle-database
Code: 500. Errors:
* 1 error occurred:
* unable to initialize: rpc error: code = Internal desc = failed to initialize: error verifying connection: ORA-12541: TNS:no listener
If your plugin version is out of date in relation to your Vault server, you could encounter an error like the following 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 memoryThis usually means that the plugin is either invalid or simply needs to be recompiled to support the latest protocol.
If you see a message like the following, this can occur for several reasons.
* error creating database object: invalid database version: 2 errors occurred:
* Unrecognized remote plugin message:
This usually means that the plugin is either invalid or simply
needs to be recompiled to support the latest protocol.
* Unrecognized remote plugin message:
This usually means that the plugin is either invalid or simply
needs to be recompiled to support the latest protocol.
1. The Oracle instant client is missing.
2. The plugin does not have the correct permissions (If plugin is owned by vault then owner read/execute is needed).
3. The plugin cannot be found. Check the name of the plugin or the checksum registered.
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.