Skip to content

Latest commit

 

History

History
543 lines (443 loc) · 19 KB

README.md

File metadata and controls

543 lines (443 loc) · 19 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 Vault Secrets service
HashiCorp Vault Secret Config Provider
Provides connection properties managed by the Dedicated Vault service
Caching configuration
Caching mechanism adopted by Centralized Config Providers

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.4</version>
</dependency>

Authentication

Providers use the HashiCorp Vault API to retrieve secrets and configurations. The HashiCorp Vault Providers support two types of Vaults: HCP Vault Dedicated and HCP Vault Secrets. Each type supports 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.

HCP Vault Secrets

Authentication for HCP Vault Secrets supports multiple methods:

Below is an overview of the supported authentication methods:

  1. OAuth 2.0 Client Credentials Flow

    • Uses HCP_CLIENT_ID and HCP_CLIENT_SECRET to obtain a Bearer token for authentication.
    • The token is then used to retrieve secrets from HCP Vault Secrets API.

  2. Credentials File Authentication

    • Uses a JSON file (creds-cache.json) containing authentication credentials (access_token, refresh_token, and access_token_expiry).
    • If the access token is expired, it is automatically refreshed using the stored refresh token.
    • If the access token is expired, it is automatically refreshed using the stored refresh token.

The generated token is cached and reused until it expires, minimizing API calls to HCP Vault Secrets.

Secrets are retrieved from the following API endpoint:
https://api.cloud.hashicorp.com/secrets/2023-11-28/organizations/$HCP_ORG_ID/projects/$HCP_PROJECT_ID/apps/$APP_NAME/secrets

For more information, visit the official HashiCorp Vault documentation: HCP Vault Secrets.

OAuth 2.0 Client Credentials Flow

This method uses OAuth 2.0 client credentials to obtain a Bearer token, which is required for authentication. The provider searches for the following parameters:

Parameter Name Description Required
HCP_CLIENT_ID The client ID for OAuth 2.0 authentication Yes
HCP_CLIENT_SECRET The client secret for OAuth 2.0 authentication Yes

In addition to the above parameters, the Common parameters are also required.

CLI CREDENTIALS FILE

This method retrieves authentication details from a JSON file (creds-cache.json) that contains access tokens.

  • If HCP CLI is installed, a creds-cache.json file is automatically created in: ~/.config/hcp/creds-cache.json
  • This file contains access_token, refresh_token, and access_token_expiry.
  • If the token is expired, it is automatically refreshed using the refresh_token.
  • The credentials file should be a JSON file containing the following structure:
{
  "login": {
    "access_token": "YOUR_ACCESS_TOKEN",
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "access_token_expiry": "2025-01-01T12:34:56.789Z"
  }
}
  • access_token: The current access token for API authentication.
  • refresh_token: The refresh token used to obtain a new access token when expired.
  • access_token_expiry: The expiration timestamp of the access_token.

When using this method, the provider will:

  • Read the file and validate the access_token.
  • Refresh the token if it's expired, using the refresh_token.
  • Update the file with the new token details.

The provider searches for the following parameters:

Parameter Name Description Required
HCP_CREDENTIALS_FILE The path of the credentials file ( by default ~/.config/hcp/creds-cache.json No

In addition to the above parameters, the Common parameters are also required.

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. CLI_CREDENTIALS_FILE → If HCP_CREDENTIALS_FILE is provided or the default credentials file (~/.config/hcp/creds-cache.json) exists, it is used.
  2. CLIENT_CREDENTIALS → If HCP_CLIENT_ID and HCP_CLIENT_SECRET are available, Client Credentials authentication is used as a fallback.

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.

Common Parameters for HCP Vault Secrets authentication methods

Parameter Name Description Required
HCP_ORG_ID The organization ID associated with the Vault Yes
HCP_PROJECT_ID The project ID associated with the Vault Yes
HCP_APP_NAME The application name in HCP Vault Secrets Yes

Config Providers

HCP Vault Dedicated Config Provider

The Oracle DataSource uses a new prefix jdbc:oracle:thin:@config-hcpdedicatedvault:// 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

HCP Vault Secrets Config Provider

The Oracle DataSource uses a new prefix jdbc:oracle:thin:@config-hcpvaultsecret:// to identify that the configuration parameters should be loaded using HCP Vault Secrets. Users need to indicate the secret name (SECRET_NAME) with the following syntax:

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

The secret-name refers to the name of the secret to retrieve from HCP Vault Secrets

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

  • Specify authentication parameters (e.g., HCP_CLIENT_ID, HCP_ORG_ID)
  • Pass additional context information required by the provider

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-hcpvaultsecret://secret-name?HCP_APP_NAME=app-name&key=sales_app1

JSON Payload format

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

  • connect_descriptor (required)
  • user (optional)
  • password (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"
  },
  "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));

For HCP Vault Secrets For example, let's suppose a URL like:

 jdbc:oracle:thin:@config-hcpvaultsecret://secret-name

And the JSON Payload for a secret stored within the application app_name in the HCP Vault Secrets 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": "hcpvaultsecret",
    "value": "secret-name"
  },
  "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-hcpvaultsecret://secret-name");
    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, HCP Vault Secrets, HTTP/HTTPS, File), the password is an object itself with the following spec:

  • type
    • Mandatory
    • Possible values
      • ocivault
      • azurevault
      • base64
      • hcpvaultdedicated
      • hcpvaultsecret
  • value
    • Mandatory
    • Possible values
      • OCID of the secret (if ocivault)
      • Azure Key Vault URI (if azurevault)
      • Base64 Encoded password (if base64)
      • Secret path (if hcpvaultdedicated)
      • Secret name (if hcpvaultsecret)
      • Text
  • field_name (HCP Vault Dedicated only)
    • 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).

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.