Skip to content

README.md

Latest commit

 

History

History
899 lines (775 loc) · 33.5 KB

README.md

File metadata and controls

899 lines (775 loc) · 33.5 KB

Oracle JDBC Providers for HashiCorp Vault

This module contains providers for integration between Oracle JDBC and HashiCorp Vault (HCP).

Centralized Config Providers

HashiCorp Vault Dedicated Config Provider
Provides connection properties managed by the Dedicated Vault service
Caching configuration
Caching mechanism adopted by Centralized Config Providers

Resource Providers

Dedicated Vault Username Provider
Provides a username stored in a HashiCorp Vault Dedicated.
Dedicated Vault Password Provider
Provides a password stored in a HashiCorp Vault Dedicated.
Dedicated Vault TCPS Wallet Provider
Provides TLS wallets from HashiCorp Vault Dedicated for secure connections.
Dedicated Vault SEPS Wallet Provider
Provides SEPS (Secure External Password Store) wallets for secure username and password retrieval from HashiCorp Vault Dedicated.
Dedicated Vault Connection String Provider
Provides connection strings based on aliases stored in a `tnsnames.ora` file within HashiCorp Vault Dedicated.
Common Parameters for HCP Vault Dedicated Resource Providers
Defines common configuration parameters for providers using HCP Vault Dedicated.
Configuring Authentication for Resource Providers
Details supported authentication methods and usage instructions.

Visit any of the links above to find information and usage examples for a particular provider.

Installation

All providers in this module are distributed as a single jar on the Maven Central Repository. The jar is compiled for JDK 8, and is forward compatible with later JDK versions. The coordinates for the latest release are:

<dependency>
  <groupId>com.oracle.database.jdbc</groupId>
  <artifactId>ojdbc-provider-hashicorp</artifactId>
  <version>1.0.6</version>
</dependency>

Authentication

Providers use the HashiCorp Vault API to retrieve secrets and configurations. The HashiCorp Vault Providers support HCP Vault Dedicated with multiple authentication methods, each requiring specific parameters.

The provider searches for these parameters in the following locations in a predefined sequence:

  1. Explicitly provided in the URL
  2. System properties
  3. Environment variables

HCP Vault Dedicated

Authentication for the HCP Vault Dedicated offers various methods to suit different use cases, including token-based, userpass, AppRole, and GitHub authentication. Below is an overview of these methods:

Token-based Authentication

Token-based authentication is the simplest way to authenticate with HashiCorp Vault. It uses a static token provided by the Vault administrator, offering direct and straightforward access to the Vault's API.

The provider searches for the following parameters:

Parameter Name Description Required
VAULT_ADDR The URL of the HashiCorp Vault instance (e.g., https://vault-dedicated.example.com:8200) Yes
VAULT_TOKEN Token provided by the Vault administrator Yes

Userpass Authentication

Userpass authentication is a method that uses a combination of a username and a password to authenticate against the Vault. It relies on the userpass authentication backend and can optionally include additional configuration parameters such as namespaces or custom authentication paths.

The provider searches for the following parameters:

Parameter Name Description Required
VAULT_ADDR The URL of the HashiCorp Vault instance (e.g., https://vault-dedicated.example.com:8200) Yes
USERPASS_AUTH_PATH The authentication path in the Vault (default: userpass) No
VAULT_NAMESPACE The namespace in the Vault (default: admin) No
VAULT_USERNAME The username for the Userpass method Yes
VAULT_PASSWORD The password for the Userpass method Yes

Once authenticated, the client_token generated from the Userpass method is cached and reused until it expires. This minimizes API calls to the Vault and enhances performance.

For more information, visit the official documentation: Userpass Authentication.

AppRole Authentication

AppRole authentication is a method that relies on a role_id and a secret_id for secure authentication. It is based on the AppRole authentication backend in HashiCorp Vault, which allows entities to authenticate and obtain a client_token by providing these identifiers.

The provider searches for the following parameters:

Parameter Name Description Required
VAULT_ADDR The URL of the HashiCorp Vault instance (e.g., https://vault-dedicated.example.com:8200) Yes
APPROLE_AUTH_PATH The authentication path in the Vault for AppRole (default: approle) No
VAULT_NAMESPACE The namespace in the Vault (default: admin) No
ROLE_ID The role ID for the AppRole method Yes
SECRET_ID The secret ID for the AppRole method Yes

Once authenticated, the client_token generated from the AppRole method is cached and reused until it expires. This minimizes API calls to the Vault and enhances performance.

For more information, visit the official documentation: AppRole Authentication.

GitHub Authentication

GitHub authentication is a method that uses a personal access token to authenticate against the Vault. It relies on the github authentication backend and supports configuring a custom authentication path.

The provider searches for the following parameters:

Parameter Name Description Required
VAULT_ADDR The URL of the HashiCorp Vault instance (e.g., https://vault-dedicated.example.com:8200) Yes
GITHUB_TOKEN The GitHub personal access token for authentication Yes
GITHUB_AUTH_PATH The authentication path for GitHub in the Vault (default: github) No
VAULT_NAMESPACE The namespace in the Vault (default: admin) No

The GITHUB method allows authentication using a GitHub personal access token and supports configuration of a custom path for GitHub authentication.

For more information, visit the official documentation: Github Authentication.

AUTO_DETECT Authentication

The AUTO_DETECT authentication method dynamically selects the most suitable authentication mechanism based on the provided parameters. This eliminates the need for users to manually specify an authentication method, ensuring a seamless and efficient authentication process.

Selection Order:

  1. VAULT_TOKEN → If a pre-existing Vault token is available, it is used.
  2. USERPASS → If VAULT_USERNAME and VAULT_PASSWORD are provided, Userpass authentication is used.
  3. APPROLE → If ROLE_ID and SECRET_ID are available, AppRole authentication is used as a fallback.
  4. GITHUB → If no other method is available, GitHub authentication is attempted using GITHUB_TOKEN.

The provider automatically detects the available parameters and chooses the best authentication method accordingly.

Note: If no authentication method is explicitly specified, AUTO_DETECT is used by default.

Config Providers

HCP Vault Dedicated Config Provider

The Oracle DataSource uses a new prefix jdbc:oracle:thin:@config-hcpvaultdedicated:// to be able to identify that the configuration parameters should be loaded using HCP Vault Dedicated. Users need to indicate the secret path with the following syntax:

jdbc:oracle:thin:@config-hcpvaultdedicated://{secret-path}[?option1=value1&option2=value2...]

The secret-path refers to the exact location of the secret within the HCP Vault Dedicated.

The query parameters (option1=value1, option2=value2, etc.) are optional key-value pairs that can be used to:

  • Specify authentication parameters (e.g., VAULT_ADDR, VAULT_TOKEN, VAULT_USERNAME)
  • Pass additional context to the provider (e.g., KEY for specifying which set of credentials to use)

All parameters that can be specified as environment variables or system properties can also be provided directly in the URL. For example:

jdbc:oracle:thin:@config-hcpvaultdedicated:///v1/namespace/secret/data/secret_name?KEY=sales_app1&authentication=approle

JSON Payload format

There are 4 fixed values that are looked at the root level:

  • connect_descriptor (required)
  • user (optional)
  • password (optional)
  • wallet_location (optional)

The rest are dependent on the driver, in our case /jdbc. The key-value pairs that are under the /jdbc prefix will be applied to a DataSource. These keys correspond to the properties defined in the OracleConnection interface.

For example, let's suppose a URL like:

jdbc:oracle:thin:@config-hcpvaultdedicated:///v1/namespace/secret/data/secret_name?KEY=sales_app1

And the JSON Payload for the secret test_config stored in the HCP Vault Dedicated would look like the following:

{
  "connect_descriptor": "(description=(retry_count=20)(retry_delay=3)(address=(protocol=tcps)(port=1521)(host=adb.us-phoenix-1.oraclecloud.com))(connect_data=(service_name=xsxsxs_dbtest_medium.adb.oraclecloud.com))(security=(ssl_server_dn_match=yes)))",
  "user": "scott",
  "password": {
    "type": "hcpvaultdedicated",
    "value": "/v1/namespace/secret/data/password",
    "field_name": "db-password" // Optional: Only needed when the secret is structured and contains multiple key-value pairs.
  },
  "wallet_location": {
    "type": "hcpvaultdedicated",
    "value": "/v1/namespace/secret/data/wallet",
    "field_name": "wallet_field" // Optional: Only needed when the secret is structured and contains multiple key-value pairs.
  },
  "jdbc": {
    "oracle.jdbc.ReadTimeout": 1000,
    "defaultRowPrefetch": 20,
    "autoCommit": "false"
  }
}

The sample code below executes as expected with the previous configuration.

    OracleDataSource ds = new OracleDataSource();
    ds.setURL("jdbc:oracle:thin:@config-hcpvaultdedicated:///v1/namespace/secret/data/test_config");
    Connection cn = ds.getConnection();
    Statement st = cn.createStatement();
    ResultSet rs = st.executeQuery("select sysdate from dual");
    if (rs.next())
      System.out.println("select sysdate from dual: " + rs.getString(1));

Password JSON Object

For the JSON type of provider (HCP Vault Dedicated, HTTP/HTTPS, File), the password is an object itself with the following spec:

  • type
    • Mandatory
    • Possible values
      • hcpvaultdedicated (HCP Vault Dedicated)
      • ocivault (OCI Vault)
      • azurevault (Azure Key Vault)
      • base64 (Base64)
      • awssecretsmanager (AWS Secrets Manager)
      • gcpsecretmanager (GCP Secret Manager)
  • value
    • Mandatory
    • Possible values
      • Secret path (if hcpvaultdedicated)
      • OCID of the secret (if ocivault)
      • Azure Key Vault URI (if azurevault)
      • Base64 Encoded password (if base64)
      • AWS Secret name (if awssecretsmanager)
      • Secret name (if gcpsecretmanager)
  • field_name (HCP Vault Dedicated)
    • Optional
    • Description: Specifies the key within the secret JSON object to retrieve the password value. For example, if the secret contains { "db-password": "mypassword" }, setting field_name: "db-password" will extract "mypassword".
    • Logic behind the field_name attribute:
      • If field_name is specified, its corresponding value is extracted.
      • If the secret contains only one key-value pair, that value is automatically used.
      • If field_name is missing and multiple keys exist, an error is thrown.
  • authentication
    • Optional
    • Possible Values
      • method
      • optional parameters (depends on the cloud provider).

Wallet_location JSON Object

The oracle.net.wallet_location connection property is not allowed in the jdbc object due to security reasons. Instead, users should use the wallet_location object to specify the wallet in the configuration.

For the JSON type of provider (HCP Vault Dedicated, HTTPS, File) the wallet_location is an object itself with the same spec as the password JSON object mentioned above.

The value stored in the secret should be the Base64 representation of a supported wallet file. This is equivalent to setting the oracle.net.wallet_location connection property in a regular JDBC application using the following format:

data:;base64,<Base64 representation of the wallet file>

Supported formats

  • cwallet.sso (SSO wallet)
  • ewallet.pem (PEM wallet)

If the PEM wallet is encrypted, you must also set the wallet password using the oracle.net.wallet_password property. This property should be included inside the jdbc object of the JSON payload:

"jdbc": {
  "oracle.net.wallet_password": "<your-password>"
}

*Note: When storing a wallet in HCP Vault Dedicated, store the raw Base64-encoded wallet bytes directly. The provider will automatically detect and handle the encoding correctly.

Resource Providers

Dedicated Vault Username Provider

The Dedicated Vault Username Provider provides Oracle JDBC with a database username that is managed by HashiCorp Vault Dedicated. This is a Resource Provider identified by the name ojdbc-provider-hcpvault-dedicated-username.

In addition to the set of common parameters, this provider also supports the parameters listed below.

Parameter Name Description Accepted Values Default Value
vaultAddr The URL of the HashiCorp Vault Dedicated instance. The URL will typically have the following form: 
https://{vault-name}.hashicorp.cloud:8200/
 No default value. A value must be configured for this parameter.
secretPath The path to the secret containing the username. Any valid secret path. No default value. A value must be configured for this parameter.
fieldName (Optional) The field inside the JSON secret that contains the required value. If the secret contains multiple keys, this parameter specifies which key to extract. If the secret contains only one key and this parameter is not provided, the value is automatically used. if fieldName is provided but not found, an error is thrown. If omitted and multiple keys exist, an error is thrown. Any valid field name. No default value. If not specified, the provider selects the only key if a single key exists.

An example of a connection properties file that configures this provider can be found in example-vault-dedicated.properties.

Dedicated Vault Password Provider

The Dedicated Vault Password Provider provides Oracle JDBC with a database password that is managed by HashiCorp Vault Dedicated.
This is a Resource Provider identified by the name ojdbc-provider-hcpvault-dedicated-password.

In addition to the set of common parameters, this provider also supports the parameters listed below.

Parameter Name Description Accepted Values Default Value
vaultAddr The URL of the HashiCorp Vault Dedicated instance. The URL will typically have the following form: 
https://{vault-name}.hashicorp.cloud:8200/
 No default value. A value must be configured for this parameter.
secretPath The path to the secret containing the password. Any valid secret path. No default value. A value must be configured for this parameter.
fieldName (Optional) The field inside the JSON secret that contains the required value. If the secret contains multiple keys, this parameter specifies which key to extract. If the secret contains only one key and this parameter is not provided, the value is automatically used. if fieldName is provided but not found, an error is thrown. If omitted and multiple keys exist, an error is thrown. Any valid field name. No default value. If not specified, the provider selects the only key if a single key exists.

An example of a connection properties file that configures this provider can be found in example-vault-dedicated.properties.

Dedicated Vault TCPS Wallet Provider

The Dedicated Vault TCPS Wallet Provider provides Oracle JDBC with keys and certificates managed by HashiCorp Vault Dedicated to establish secure TLS connections with an Autonomous Database.
This is a Resource Provider identified by the name ojdbc-provider-hcpvault-dedicated-tls.

For example, when connecting to an Autonomous Database Serverless with mutual TLS (mTLS),
you need to configure the JDBC-thin driver with its client certificate.
If this certificate is stored in a wallet file (cwallet.sso, ewallet.p12, ewallet.pem),
you may store it in HCP Vault Dedicated for additional security.
This provider retrieves the wallet content from HCP Vault Dedicated and passes it to the JDBC thin driver.

  • The type parameter must be specified to indicate the wallet format: SSO, PKCS12, or PEM.
  • The walletPassword must be provided for wallets that require a password (PKCS12 or password-protected PEM files).

In addition to the set of common parameters, this provider also supports the parameters listed below.

Parameter Name Description Accepted Values Default Value
vaultAddr The URL of the HashiCorp Vault Dedicated instance. 
https://{vault-name}.hashicorp.cloud:8200/
 No default value. A value must be configured for this parameter.
secretPath The path to the wallet file. Any valid secret path. No default value. A value must be configured for this parameter.
type The wallet format. SSO, PKCS12, PEM No default value. The file type must be specified.
walletPassword Optional password for **PKCS12** or protected **PEM** files. If omitted, the file is assumed to be **SSO** or an **unprotected PEM** file. Any valid password. No default value. PKCS12 and password-protected PEM files require a password.
fieldName (Optional) The field inside the JSON secret that contains the base64-encoded TCPS wallet.
HashiCorp Vault Dedicated stores secrets as JSON objects. For TCPS wallets, this means a secret may contain multiple base64-encoded entries (e.g., sso, pkcs12, pem, etc.).
If the secret contains multiple keys, this parameter specifies which key to extract. If the secret contains only one key and this parameter is not provided, the value is automatically used. if fieldName is provided but not found, an error is thrown. If omitted and multiple keys exist, an error is thrown. 		Any valid field name. No default value. If not specified, the provider selects the only key if a single key exists.

An example of a connection properties file that configures this provider can be found in example-vault-dedicated-wallet.properties.

Dedicated Vault SEPS Wallet Provider

The Dedicated Vault SEPS Wallet Provider provides Oracle JDBC with username and password credentials stored in a Secure External Password Store (SEPS) wallet within HCP Vault Dedicated.

This is a Resource Provider identified by the name ojdbc-provider-hcpvault-dedicated-seps.

  • The SEPS wallet securely stores encrypted database credentials, including the username, password, and connection strings. These credentials can be stored as default values, such as:

    • oracle.security.client.default_username
    • oracle.security.client.default_password

    or as indexed credentials, for example:

    • oracle.security.client.username1
    • oracle.security.client.password1
    • oracle.security.client.connect_string1.

  • The provider retrieves credentials using the following logic:

    1. If connectionStringIndex is not specified, the provider attempts to retrieve the default credentials (oracle.security.client.default_username and oracle.security.client.default_password).
    2. If default credentials are missing, the provider checks for a single set of credentials associated with a connection string.
    3. If exactly one connection string is found, the associated credentials are used.
    4. If multiple connection strings exist, an error is thrown, prompting you to specify a connectionStringIndex.
    5. If connectionStringIndex is specified, the provider attempts to retrieve the credentials associated with the specified connection string index (e.g., oracle.security.client.username{idx}, oracle.security.client.password{idx}, oracle.security.client.connect_string{idx}).
    6. If credentials for the specified index are not found, an error is thrown, indicating that no connection string exists with that index.

In addition to the set of common parameters, this provider also supports the parameters listed below.

Parameter Name Description Accepted Values Default Value
vaultAddr The URL of the HashiCorp Vault Dedicated instance. The URL will typically have the following form: 
https://{vault-name}.hashicorp.cloud:8200/
 No default value. A value must be configured for this parameter.
secretPath The path to the SEPS wallet file in HashiCorp Vault Dedicated. Any valid secret path. No default value. A value must be configured for this parameter.
walletPassword Optional password for **PKCS12 SEPS wallets**. If omitted, the wallet is assumed to be **SSO**. Any valid password for the SEPS wallet. No default value. PKCS12 wallets require a password.
connectionStringIndex (Optional) Specifies the **index** of the connection string to use when retrieving credentials from the wallet. A positive integer representing the index of the desired credential set (e.g., 1, 2, 3, etc.). No default value. If not specified, the provider follows the default behavior as described above.
fieldName (Optional) The field inside the JSON secret that contains the base64-encoded SEPS wallet.
HashiCorp Vault Dedicated stores secrets as JSON objects. For SEPS wallets, this means a secret may contain multiple base64-encoded entries (e.g., sso, pkcs12, etc.).
If the secret contains multiple keys, this parameter specifies which key to extract. If the secret contains only one key and this parameter is not provided, the value is automatically used. if fieldName is provided but not found, an error is thrown. If omitted and multiple keys exist, an error is thrown. 		Any valid field name. No default value. If not specified, the provider selects the only key if a single key exists.

An example of a connection properties file that configures this provider can be found in example-vault-dedicated-wallet.properties.

Dedicated Vault Connection String Provider

The Dedicated Vault Connection String Provider provides Oracle JDBC with a connection string
retrieved from a tnsnames.ora file stored in HCP Vault Dedicated.

This is a Resource Provider identified by the name ojdbc-provider-hcpvault-dedicated-tnsnames.

This provider retrieves and decodes a tnsnames.ora file stored as a base64-encoded secret or plain text in HCP Vault Dedicated, allowing selection of connection strings based on specified aliases.

This enables flexible configuration for secure database connections using the alias names defined in your tnsnames.ora file.

In addition to the set of common parameters, this provider also requires the parameters listed below.

Parameter Name Description Accepted Values Default Value
vaultAddr The URL of the HashiCorp Vault Dedicated instance. 
https://{vault-name}.hashicorp.cloud:8200/
 No default value. A value must be configured for this parameter.
secretPath The path to the `tnsnames.ora` file. Any valid secret path. No default value. A value must be configured for this parameter.
tnsAlias The alias to retrieve the connection string. Any valid alias present in the `tnsnames.ora` file. No default value. A value must be configured for this parameter.
fieldName (Optional) The field inside the JSON secret that contains the tnsnames.ora content, either as plain text or base64-encoded. If the secret contains multiple keys, this parameter specifies which key to extract. If the secret contains only one key and this parameter is not provided, the value is automatically used. if fieldName is provided but not found, an error is thrown. If omitted and multiple keys exist, an error is thrown. Any valid field name. No default value. If not specified, the provider selects the only key if a single key exists.

An example of a connection properties file that configures this provider can be found in example-vault-dedicated.properties.

Common Parameters for HCP Vault Dedicated Resource Providers

Providers classified as Resource Providers in this module all support a common set of parameters.

Parameter Name Description Accepted Values System Property / Environment Variable Default Value
authenticationMethod Configures a method of authentication for HCP Vault Dedicated. Accepted values are defined in: Configuring Authentication for HCP Vault Dedicated. Not supported auto-detect
vaultAddr The URL of the HashiCorp Vault Dedicated instance. A valid Vault endpoint, typically in the form: 
https://vault.example.com:8200
 VAULT_ADDR No default value.
vaultNamespace The namespace in the Vault (only required if using namespaces). Any valid Vault namespace. VAULT_NAMESPACE admin (if not explicitly set)
vaultToken Configures authentication using a Vault token. A valid Vault authentication token. VAULT_TOKEN No default value.
vaultUsername Configures authentication using the Userpass method. A valid Vault username. VAULT_USERNAME No default value.
vaultPassword The password for Userpass authentication. A valid Vault password. VAULT_PASSWORD No default value.
roleId Configures authentication using the AppRole method. A valid Role ID for the AppRole authentication method. ROLE_ID No default value.
secretId The secret ID for AppRole authentication. A valid Secret ID for the AppRole authentication method. SECRET_ID No default value.
githubToken Configures authentication using a GitHub token. A valid GitHub personal access token. GITHUB_TOKEN No default value.
userPassAuthPath The authentication path in the Vault for Userpass authentication. Any valid Vault authentication path. USERPASS_AUTH_PATH userpass (if not explicitly set)
appRoleAuthPath The authentication path in the Vault for AppRole authentication. Any valid Vault authentication path. APPROLE_AUTH_PATH approle (if not explicitly set)
githubAuthPath The authentication path in the Vault for GitHub authentication. Any valid Vault authentication path. GITHUB_AUTH_PATH github (if not explicitly set)

Configuring Authentication for Resource Providers

HCP Vault Dedicated

Resource Providers in this module must authenticate with HashiCorp Vault Dedicated. By default, the provider will automatically detect any available credentials. A specific authentication method may be configured using the "authenticationMethod" parameter.

Supported values for authenticationMethod:

  • vault-token
    Authenticate using a pre-existing Vault token.

  • userpass
    Authenticate using a username and password.

  • approle
    Authenticate using AppRole credentials (requires roleId and secretId).

  • github
    Authenticate using a GitHub personal access token.

  • auto-detect (default)
    Automatically selects the method based on the following priority:

    1. vault-token
    2. userpass
    3. approle
    4. github

Caching configuration

Config providers in this module store the configuration in caches to minimize the number of RPC requests to remote location. See Caching configuration for more details of the caching mechanism.