vault-database-plugin-oracle

A Vault plugin for Oracle.

For more information on this plugin, see the Oracle Database Secrets Engine page.

This project uses the database plugin interface introduced in Vault version 0.7.1.

This plugin is not compatible with Alpine Linux out of the box. Oracle's libraries are glibc dependant, and Alpine has musl as its default C library.

Releases

For linux/amd64, pre-built binaries can be found at the releases page. See the following table to determine what version of the Oracle Instant Client SDK the plugin was built with:

Plugin Release	Instant Client Version
v0.10.2	19.23
v0.10.1	19.23
v0.10.0	19.23
v0.9.0	19.22
v0.8.3	19.20
v0.8.2	19.18
v0.8.1	19.18
v0.8.0	19.18
v0.7.0	19.6
v0.6.1	19.6
v0.6.0	19.6
v0.5.0	19.6
v0.4.0	19.6
v0.3.0	19.6
v0.2.0	19.3

Build

For platforms other than linux/amd64, there are not currently pre-built binaries available.

Before building, you will need to download the Oracle Instant Client library, which is available from Oracle. Download the SDK package to get the headers and download the Basic package to get the libraries for your platform. Inside the SDK package's subfolder: instantclient_<version>/sdk/include/ are a number of header files. Similarly, inside the Basic package's subfolder: instantclient_<version>/ are a number of library files. These will need to be placed into the standard locations for your platform.

For instance, if you are using MacOS, place the header files from the SDK package into either /usr/local/include/ or ~/include/. Similarly, place the library files from the Basic package into either /usr/local/lib/ or ~/lib/

Next, ensure that you have pkg-config installed on your system. For MacOS, you can install it using brew install pkg-config.

Create a pkg-config file to point to the library. Create the file oci8.pc on your PKG_CONFIG_PATH.

An example oci8.pc for macOS is:

prefix=/usr/local

version=11.2
build=client64

libdir=${prefix}/lib
includedir=${prefix}/include

Name: oci8
Description: Oracle database engine
Version: ${version}
Libs: -L${libdir} -lclntsh
Libs.private:
Cflags: -I${includedir}

Then, git clone this repository into your $GOPATH and go build -o vault-plugin-database-oracle ./plugin from the project directory.

Tests

make test will run a basic test suite against a Docker version of Oracle.

Additionally, there are some Bats tests in the tests directory.

Prerequisites

• Install Bats Core
• Docker
• A vault binary in the tests directory.

Setup

• Oracle plugin is built and saved in PLUGIN_DIR
  • Export PLUGIN_DIR containing the path to the oracle plugin binary.
• Oracle db docker image has been built
• Oracle db data path is set in DOCKER_VOLUME_MNT. i.e. ~/dev/oracle/data
  • If you do not use a persistent store for Oracle data, the amount of time the container will need to start up will be dramatically longer. Using the volume mount skips a lot of first-time setup steps.
• Export VAULT_LICENSE. This test will only work for enterprise images.

Logs

Vault logs will be written to VAULT_OUTFILE. Bats test logs will be written to SETUP_TEARDOWN_OUTFILE.

Run Bats tests

# export env vars
export VAULT_LICENSE="12345"
export PLUGIN_DIR="~/dev/plugins"
export DOCKER_VOLUME_MNT="~/dev/plugins/oracle/data"

# run tests
cd tests/
./test.bats

Installation

See Case Sensitivity for important information about custom creation & rotation statements.

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, you will need to enable ipc_lock capabilities for the plugin binary.

The Vault plugin system is documented on the Vault documentation site.

You will need to define a plugin directory using the plugin_directory configuration directive, then place the vault-plugin-database-oracle executable generated above in the directory.

Please note: Versions v0.3.0 onwards of this plugin are incompatible with Vault versions before 1.6.0 due to an update of the database plugin interface.

Sample commands for plugin registration in current versions of Vault and starting to use the plugin:

$ vault plugin register -sha256=<SHA256 Hex value of the plugin binary> \
    database \                  # type
    vault-plugin-database-oracle
Success! Registered plugin: vault-plugin-database-oracle

Vault versions prior to v0.10.4 lacked the vault plugin operator and the registration step for them is:

$ shasum -a 256 vault-plugin-database-oracle > /tmp/oracle-plugin.sha256

$ vault write sys/plugins/catalog/database/vault-plugin-database-oracle \
    sha256=$(cat /tmp/oracle-plugin.sha256) \
    command="vault-plugin-database-oracle"

$ vault secrets enable database

$ vault write database/config/oracle \
    plugin_name=vault-plugin-database-oracle \
    allowed_roles="*" \
    connection_url='{{username}}/{{password}}@//url.to.oracle.db:1521/oracle_service' \
    username='vaultadmin' \
    password='reallysecurepassword'

# You should consider rotating the admin password. Note that if you do, the new password will never be made available
# through Vault, so you should create a vault-specific database admin user for this.
$ vault write -force database/rotate-root/oracle

If running the plugin on MacOS you may run into an issue where the OS prevents the Oracle libraries from being executed. See How to open an app that hasn't been notarized or is from an unidentified developer on Apple's support website to be able to run this.

Usage

Case Sensitivity

It is important that you do NOT specify double quotes around the username in any of the SQL statements. Otherwise Oracle may create/look up a user with the incorrect name (foo_bar instead of FOO_BAR).

Default statements

The rotation statements are optional and will default to ALTER USER {{username}} IDENTIFIED BY "{{password}}"

The disconnect statements are optional and will default to the sql below. Setting disconnect_statements to false will disable the disconnect functionality, but should be disabled with caution since it may limit the effectiveness of revocation.

ALTER USER {{username}} ACCOUNT LOCK;
begin
  for x in ( select inst_id, sid, serial# from gv$session where username="{{username}}" )
  loop
   execute immediate ( 'alter system kill session '''|| x.Sid || ',' || x.Serial# || '@' || x.inst_id ''' immediate' );
  end loop;
  dbms_lock.sleep(1);
end;
DROP USER {{username}};

Updating the Changelog

All pull requests that introduce a user-facing change must include a changelog entry. We use the changie tool to manage these entries and automate the release process.

---

1. Installing Changie

You only need to do this once. If you don't have changie installed, choose one of the options below.

• Homebrew (macOS):

  brew install changie

• Go Install:

  go install github.com/miniscruff/changie@latest

• Other Methods: See the official changie installation guide for other options, including pre-compiled binaries.

---

2. Creating an Entry

Once your code changes are complete, create the changelog entry:

1. Run the command in your terminal:

   changie new

2. Follow the prompts. An interactive prompt will ask you to select the kind of change (e.g., BREAKING CHANGES, NOTES, FEATURES) and write a concise description of what you changed.

3. Commit the new file. After you're done, changie will create a new YAML file in the .changie/unreleased directory. Commit this file along with your other code changes before submitting your pull request.

Terraform Bootstrap

This repo contains some terraform config in the bootstrap/terraform directory to bootstrap a complete Vault and Oracle test environment in AWS. It will provision and automatically configure all necessary infrastructure and dependencies for testing the Vault Database Secrets Engine for Oracle.

The environment consists of an Oracle RDS instance and an EC2 instance running Vault, pre-configured to communicate with each other.

Prerequisites

• Terraform v1.0+
• AWS CLI configured and authenticated

Usage

1. Configure Variables: Create a terraform.tfvars file in the bootstrap/terraform directory to specify your Vault license:

   # terraform.tfvars
   vault_license = "YOUR_VAULT_ENTERPRISE_LICENSE"
   

   Alternatively, specify the Vault license via the environment:

   export TF_VAR_vault_licent=YOUR_VAULT_ENTERPRISE_LICENSE
   

2. Deploy: Run the following commands in the bootstrap/terraform directory:

   terraform init
   terraform apply
   

   Review the plan and enter yes to approve. The public IP and ssh information of the Vault server will be an output for further testing.

3. Connect via ssh: Run the ssh command output by the terraform run to login to the ec2 instance. Once connected, perform any tests or run the following commands:

   Read dynamic creds:

   vault read database/creds/test
   

   Read static creds:

   vault read database/static-creds/static-role-0
   vault write -f database/rotate-role/static-role-0
   vault read database/static-creds/static-role-0
   

4. Teardown: When you are finished, destroy all resources to avoid ongoing AWS costs.

   terraform destroy