Vault Credentials

Drillbridge can retrieve JDBC connection and Essbase server credentials from HashiCorp Vault instead of storing them in the Drillbridge database.

Drillbridge 4.0 support

Drillbridge 4.0 qualifies the following configuration:

  • HashiCorp Vault 1.17.6

  • Token authentication

  • Version 1 and version 2 KV secrets engines

  • TLS-protected Vault connections for production deployments

Other Vault authentication methods are not part of the Drillbridge 4.0 supported configuration until they have been tested with Drillbridge.

Use a narrowly scoped, read-only token for Drillbridge. Never use a Vault root token in production.

Local end-to-end smoke test

This procedure starts an ephemeral Vault development server, runs Drillbridge normally from an IDE, stores test database credentials in Vault, and executes a Drillbridge report with those credentials.

The Vault development server is for local testing only. It uses plain HTTP, runs unsealed, stores data only in memory, and uses a known root token. Stopping the container deletes its contents. Do not reuse this configuration or token outside a disposable development environment.

1. Start Vault

Run the following command in a terminal:

docker run --name drillbridge-vault-dev --rm \
  --cap-add=IPC_LOCK \
  --publish 8200:8200 \
  --env VAULT_DEV_ROOT_TOKEN_ID=drillbridge-dev-root \
  --env VAULT_DEV_LISTEN_ADDRESS=0.0.0.0:8200 \
  hashicorp/vault:1.17.6 server -dev

Leave that terminal running. In a second terminal, verify that Vault is ready:

docker exec \
  --env VAULT_ADDR=http://127.0.0.1:8200 \
  --env VAULT_TOKEN=drillbridge-dev-root \
  drillbridge-vault-dev vault status

The development server creates a version 2 KV engine mounted at secret, matching the Drillbridge settings used below.

2. Identify a test database

Use a database that is reachable from the machine running Drillbridge and a disposable database account with a nonblank username and password. You need its JDBC driver, JDBC URL, username, password, and a simple query that returns rows.

The in-memory H2 sample database created by Drillbridge’s DEV profile uses a blank password. It is therefore not suitable for this Vault smoke test because Drillbridge deliberately rejects incomplete secrets and blank credential values.

If you already have a suitable test database, skip to the next step. For a completely local example, start a disposable MySQL container:

docker run --name drillbridge-mysql-dev --rm --detach \
  --publish 3307:3306 \
  --env MYSQL_DATABASE=drillbridge_demo \
  --env MYSQL_USER=report_user \
  --env MYSQL_PASSWORD=report_password \
  --env MYSQL_ROOT_PASSWORD=local_root_password \
  mysql:8.4

Follow its log until MySQL reports that it is ready for connections:

docker logs --follow drillbridge-mysql-dev

Press Ctrl+C to stop following the log; the MySQL container continues running. Then create sample report data:

docker exec --env MYSQL_PWD=report_password drillbridge-mysql-dev \
  mysql --user=report_user drillbridge_demo \
  --execute="CREATE TABLE transactions (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    description VARCHAR(100) NOT NULL,
    amount DECIMAL(12,2) NOT NULL
  );
  INSERT INTO transactions (description, amount) VALUES
    ('Vault smoke test', 123.45),
    ('Credential rotation candidate', 678.90);"

For this example, the connection values will be:

  • Driver: MySQL

  • JDBC URL: jdbc:mysql://localhost:3307/drillbridge_demo?useSSL=false&allowPublicKeyRetrieval=true

  • Username: report_user

  • Password: report_password

The disabled TLS setting applies only to this local disposable database connection.

3. Put the database credentials in Vault

Store the test database credentials under a logical Drillbridge path:

docker exec \
  --env VAULT_ADDR=http://127.0.0.1:8200 \
  --env VAULT_TOKEN=drillbridge-dev-root \
  drillbridge-vault-dev vault kv put \
  secret/drillbridge/connections/reporting \
  username=report_user password=report_password

Confirm that the secret exists. This command prints the test values, so use it only with disposable credentials:

docker exec \
  --env VAULT_ADDR=http://127.0.0.1:8200 \
  --env VAULT_TOKEN=drillbridge-dev-root \
  drillbridge-vault-dev vault kv get \
  secret/drillbridge/connections/reporting

When using an existing test database, substitute its username and password in the vault kv put command. Keep the path the same for the rest of this walkthrough.

4. Configure the IDE run

Add the following environment variables to the IDE run configuration that starts com.saxifrages.drillbridge.Application:

SPRING_CLOUD_VAULT_ENABLED=true
SPRING_CLOUD_VAULT_URI=http://localhost:8200
SPRING_CLOUD_VAULT_AUTHENTICATION=TOKEN
SPRING_CLOUD_VAULT_TOKEN=drillbridge-dev-root
SPRING_CLOUD_VAULT_KV_BACKEND=secret
SPRING_CLOUD_VAULT_KV_BACKEND_VERSION=2

Do not edit the checked-in application.properties to add the token. These environment variables override its safe defaults for this run only.

Start Drillbridge normally from the IDE. The default development URL is http://localhost:9220. If prompted to log in, the default local credentials are admin / drillbridge.

5. Create and test a Vault-backed connection

  1. Open Connections and select New SQL Connection.

  2. Enter a name such as Local Vault MySQL.

  3. Select the database driver and enter its JDBC URL. For the local example, select MySQL and use jdbc:mysql://localhost:3307/drillbridge_demo?useSSL=false&allowPublicKeyRetrieval=true.

  4. Select Vault Secrets as the credential source.

  5. Enter drillbridge/connections/reporting as the Vault path. This is relative to the configured secret mount; do not include secret/data.

  6. Leave the manual username and password empty.

  7. Select Test. A successful test proves that Drillbridge can read the Vault secret and use it to authenticate to the database.

  8. Save the connection, reopen it, and test it again. This also exercises the saved-connection path.

When the connection is saved with Vault selected, Drillbridge clears any manually stored username and password.

6. Create and run a report

  1. Open Reports and select New Report.

  2. Give it a name such as Local Vault Report.

  3. Select the Vault-backed connection created above.

  4. For the local MySQL example, enter this query:

    SELECT id, description, amount
FROM transactions
ORDER BY id

  5. Create the report.

  6. Open its Test tab and select Build it!.

  7. Confirm that the two sample rows appear. The report has now opened a database connection using credentials retrieved from Vault.

For an existing test database, use a harmless query appropriate to that database instead.

7. Optional negative and rotation checks

To prove there is no credential fallback, temporarily change the connection’s Vault path to a nonexistent path and test it. The test must fail without using a previously entered or stored password. Restore the correct path afterward.

To exercise rotation, change the database user’s password first, then write the matching new password to the same Vault path. The next new Drillbridge connection should use the new value without changing the report or connection record. Existing open database sessions may continue using the old credential until recreated.

8. Stop and remove the local services

Stop the containers when testing is complete:

docker stop drillbridge-vault-dev drillbridge-mysql-dev

Both commands used --rm, so Docker removes the containers and their disposable data after they stop. If you used an existing test database instead of the MySQL example, stop only drillbridge-vault-dev.

Configure Drillbridge

Put Vault settings in the external config/application.properties file for the Drillbridge installation. Do not put a real token in the application archive or source repository.

spring.cloud.vault.enabled=true
spring.cloud.vault.uri=https://vault.example.com:8200
spring.cloud.vault.authentication=TOKEN
spring.cloud.vault.token=${VAULT_TOKEN}
spring.cloud.vault.kv.backend=secret
spring.cloud.vault.kv.backend-version=2
spring.cloud.vault.connection-timeout=5000
spring.cloud.vault.read-timeout=15000

Set spring.cloud.vault.kv.backend-version=1 when using a version 1 KV secrets engine. The backend property is the mount name, not a secret path.

Plain HTTP is appropriate only for local development. For production, configure HTTPS and make the Vault server certificate trusted by the JVM running Drillbridge.

The environment-variable expression in the example keeps the token out of the properties file. With token authentication, replace the token in the Drillbridge environment and restart Drillbridge when the token changes.

Create secrets and policies

Each secret must contain string values named username and password.

For a version 2 KV engine mounted at secret, a minimal read policy resembles:

path "secret/data/drillbridge/*" {
  capabilities = ["read"]
}

For a version 1 KV engine, omit the data/ path component.

Select Vault credentials

  1. Edit a JDBC connection or Essbase server in Drillbridge.

  2. Select Vault Secrets as the credential source.

  3. Enter the logical secret path relative to the configured mount, such as drillbridge/connections/reporting.

  4. Save and test the connection or server.

The relative logical path is preferred. Drillbridge also accepts a path prefixed with the configured mount and a version 2 physical path containing data/, then normalizes it before reading the secret.

When Vault is selected, Drillbridge clears any manually stored username and password. Selecting manual credentials clears the stored Vault path.

Runtime and rotation behavior

Drillbridge reads Vault whenever it creates a new JDBC connection or resolves an Essbase server. Credentials are not cached by the Vault integration, so the next new connection observes a rotated secret. A connection or Essbase session that is already open may continue using its previous credentials until it is recreated.

Drillbridge does not retrieve every configured secret during startup. If Vault is unavailable, unauthorized, or a secret is incomplete, the operation that needs the credential fails without falling back to stored credentials. User-facing errors and logs do not include the secret, token, credential values, or Vault response body.

For recovery:

  1. Confirm that Vault is reachable from the Drillbridge host and its certificate is trusted.

  2. Confirm the Drillbridge token is valid and has read access to the configured secret path.

  3. Confirm the mount name and KV version match the Vault deployment.

  4. Confirm the secret contains nonblank username and password values.

  5. Retry the Drillbridge operation after correcting the Vault configuration or secret.