Oracle JDBC Providers for OCI

This module contains providers for integration between Oracle JDBC and Oracle Cloud Infrastructure (OCI).

Centralized Config Providers

OCI Database Tools Connections Config Provider: Provides connection properties managed by the Database Tools Connection service
OCI Object Storage Config Provider: Provides connection properties managed by the Object Storage service

Database Connection String Provider: Provides connection strings for an Autonomous Database
Database TLS Provider: Provides TLS keys and certificates for an Autonomous Database
Vault Password Provider: Provides passwords managed by the Vault service
Vault Username Provider: Provides usernames managed by the Vault service
Access Token Provider: Provides access tokens issued by the Dataplane service

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 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-oci</artifactId>
  <version>1.0.0</version>
</dependency>

OCI Database Tools Connections Config Provider

The OCI Database Tools Connections is a managed service that can be used to configure connections to a database. The created resource stores connection properties, including user, password and wallets (these last two optionally as references to a secret in OCI Vault). Each configuration has an identifier (OCID) that is used to identify which connection is requested by the driver.

JDBC URL Sample that uses the OCI DBTools provider:

jdbc:oracle:thin:@config-ocidbtools:ocid1.databasetoolsconnection.oc1.phx.ama ...

OCI Object Storage Config Provider

The Oracle DataSource uses a new prefix jdbc:oracle:thin:@config-ociobject: to be able to identify that the configuration parameters should be loaded using OCI Object Storage. Users only need to indicate the URL Path of the Object containing the JSON payload, with the following syntax:

jdbc:oracle:thin:@config-ociobject:{url_path}[?option1=value1&option2=value2...]

The insturctions of obtaining a URL Path can be found in Get the URI or Pre-Authenticated Request URL to Access the Object Store.

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 with sub-prefix /jdbc will be applied to a DataSource. The key values are constant keys which are equivalent to the properties defined in the OracleConnection interface.

For example, let's suppose an url like:

jdbc:oracle:thin:@config-ociobject:https://objectstorage.us-phoenix-1.oraclecloud.com/n/mytenancy/b/bucket1/o/payload_ojdbc_objectstorage.json

And the JSON Payload for the file payload_ojdbc_objectstorage.json in the bucket1 which namespace is mytenancy is as 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": "vault-oci",
    "value": "ocid1.vaultsecret.oc1.phx.amaaaaaxxxx"
  },
  "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-ociobject:https://objectstorage.us-phoenix-1.oraclecloud.com/n/mytenancy/b/bucket1/o/payload_ojdbc_objectstorage.json");
    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 (OCI Object Storage, HTTP/HTTPS, File) the password is an object itself with the following spec:

type
- Mandatory
- Possible values
  - vault-oci
  - vault-azure
  - base64
value
- Mandatory
- Possible values
  - OCID of the secret (if vault-oci)
  - Azure Key Vault URI (if vault-azure)
  - Base64 Encoded password (if base64)
  - Text
authentication
- Optional (it will apply defaults in the same way as described in Configuring Authentication).
- Possible Values
  - method
  - optional parameters (depends on the cloud provider, applies the same logic as Config Provider for Azure).

Common Parameters for Centralized Config Providers

OCI Database Tools Connections Config Provider and OCI Object Storage Config Provider share the same sets of parameters for authentication configuration.

Configuring Authentication

The Centralized Config Providers in this module use the OCI SDK Authentication Methods to provide authorization and authentication to the Object Storage, Database Tools Connection and Vault services. The user can provide an optional parameter AUTHENTICATION (case-ignored) which is mapped with the following Credential Class.

'AUTHENTICATION' Param Value	Method	Optional Configuration	Optional Parameters
OCI_DEFAULT or <Empty>	API Key-Based Authentication	(~/.oci/config) or (~/.oraclebmc/config) or environment variable OCI_CONFIG_FILE (this is the same approach that oci-java-sdk has) Either above or all the optional values in Optional Parameters	OCI_PROFILE
			OCI_TENANCY
			OCI_USER
			OCI_FINGERPRINT
			OCI_KEY_FILE
			OCI_PASS_PHRASE
			OCI_REGION (*)
OCI_INSTANCE_PRINCIPAL	Instance Principal Authentication
OCI_RESOURCE_PRINCIPAL	Resource Principal Authentication
OCI_INTERACTIVE	Session Token-Based Authentication	Same as OCI_DEFAULT	Same as OCI_DEFAULT

*Note: this parameter is introduced to align with entries of the config file. The region that is used for calling Object Storage, Database Tools Connection, and Secret services will be extracted from the Object Storage URL, Database Tools Connection OCID or Secret OCID

Database Connection String Provider

The Database Connection String Provider provides Oracle JDBC with the connection string of an Autonomous Database. This is a Resource Provider identified by the name ojdbc-provider-oci-database-connection-string.

For databases that require mutual TLS (mTLS) authentication, it is recommended to use the Database TLS Provider in conjunction with this provider.