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
OCI Vault Config Provider: Provides connection properties managed by the Vault service
Common Parameters for Centralized Config Providers: Common parameters supported by the config providers
Caching configuration: Caching mechanism adopted by Centralized Config Providers

Resource Providers

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
TCPS Wallet Provider: Provides TCPS/TLS wallets for secure connections to an Autonomous Database
SEPS Wallet Provider: Provides SEPS (Secure External Password Store) wallets for secure username and password retrieval
Vault Connection String Provider: Provides connection strings for secure database connectivity based on aliases, retrieved from the tnsnames.ora file stored in OCI Vault.
Common Parameters for Resource Providers: Common parameters supported by the resource 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 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.1</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 ...

Provider can now support Database Tools Connections with Proxy Authentication, only if username is provided in Proxy Authentication Info, without the password and roles.

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://mytenancy.objectstorage.us-phoenix-1.oci.customer-oci.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": "ocivault",
    "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://mytenancy.objectstorage.us-phoenix-1.oci.customer-oci.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
  - ocivault
  - azurevault
  - base64
value
- Mandatory
- Possible values
  - OCID of the secret (if ocivault)
  - Azure Key Vault URI (if azurevault)
  - 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).

OCI Vault Config Provider

Apart from OCI Object Storage, users can also store JSON Payload in the content of OCI Vault Secret. Users need to indicate the OCID of the Secret with the following syntax:

jdbc:oracle:thin:@config-ocivault://{secret-ocid}

The JSON Payload retrieved by OCI Vault Config Provider follows the same format in OCI Object Storage Config Provider.

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

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.

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.

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

Parameter Name	Description	Accepted Values	Default Value
ocid	Identifies the database that a connection string is provided for.	The OCID of an Autonomous Database	No default value. A value must be configured for this parameter.
consumerGroup	Configures a share of CPU and IO resources allocated for the database session. Predefined groups are specified in the ADB product documentation	"HIGH", "MEDIUM", "LOW", "TP", or "TPURGENT". A database provisioned with the Data Warehouse workload type will not recognize TP or TPURGENT	MEDIUM

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

Database TLS Provider

The Database TLS Provider provides Oracle JDBC with keys and certificates for mutual TLS authentication (mTLS) with an Autonomous Database. This is a Resource Provider identified by the name ojdbc-provider-oci-database-tls.

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

Parameter Name	Description	Accepted Values	Default Value
ocid	Identifies the database that TLS keys and certificates are provided for.	The OCID of an Autonomous Database	No default value. A value must be configured for this parameter.

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

Vault Password Provider

The Vault Password Provider provides Oracle JDBC with a password that is managed by the OCI Vault service. This is a Resource Provider identified by the name ojdbc-provider-oci-vault-password.

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

Parameter Name	Description	Accepted Values	Default Value
ocid	Identifies the secret that is provided.	The OCID of an OCI Vault secret	No default value. A value must be configured for this parameter.

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

Vault Username Provider

The Vault Username Provider provides Oracle JDBC with a username that is managed by the OCI Vault service. This is a Resource Provider identified by the name ojdbc-provider-oci-vault-username.

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

Parameter Name	Description	Accepted Values	Default Value
ocid	Identifies the secret that is provided.	The OCID of an OCI Vault secret	No default value. A value must be configured for this parameter.

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

TCPS Wallet Provider

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

For example, when connecting to 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 (e.g., cwallet.sso, ewallet.p12, ewallet.pem), you may store it in a vault secret in OCI for additional security. You can then use this provider that will retrieve the wallet content using the OCI SDK and pass it to the JDBC thin driver.

The type parameter must be specified to indicate the wallet format: SSO, PKCS12, or PEM.
The password must be provided for wallets that require a password (e.g., 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
ocid	Identifies the secret containing the TCPS file.	The OCID of an OCI Vault secret	No default value. A value must be configured for this parameter.
walletPassword	Optional password for PKCS12 or protected PEM files. If omitted, the file is assumed to be SSO or an non-protected PEM file.	Any valid password for the wallet	No default value. PKCS12 and password-protected PEM files require a password.
type	Specifies the type of the file being used.	SSO, PKCS12, PEM	No default value. The file type must be specified..

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

SEPS Wallet Provider

The SEPS Wallet Provider provides Oracle JDBC with a username and password managed by the OCI Vault service, stored in a Secure External Password Store (SEPS) wallet. This is a Resource Provider identified by the name ojdbc-provider-oci-vault-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 and oracle.security.client.default_password, or as indexed credentials, for example, oracle.security.client.username1, oracle.security.client.password1, and oracle.security.client.connect_string1.
The provider retrieves credentials based on the following logic: If connectionStringIndex is not specified, it first attempts to retrieve the default credentials (oracle.security.client.default_username and oracle.security.client.default_password). If default credentials are not found, it checks for a single set of credentials associated with a connection string. If exactly one connection string is found, it uses the associated credentials. However, if multiple connection strings are found, an error is thrown, prompting you to specify a connectionStringIndex. 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}). If credentials for the specified index are not found, an error is thrown indicating that no connection string was found 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
ocid	Identifies the secret containing the SEPS wallet.	The OCID of an OCI Vault secret	No default value. A value must be configured for this parameter.
walletPassword	Optional password for wallets stored as PKCS12 keystores. If omitted, the wallet is assumed to be an SSO wallet.	Any valid password for the SEPS wallet	No default value. PKCS12 wallets require a password.
connectionStringIndex	Optional parameter to specify 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

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

Vault Connection String Provider

The OCI Vault Connection String Provider provides Oracle JDBC with a connection string managed by the OCI Vault service. This is a Resource Provider identified by the name ojdbc-provider-oci-vault-tnsnames.

This provider retrieves and decodes a tnsnames.ora file stored as a secret in OCI Vault, allowing selection of connection strings based on specified aliases. It supports both plain text and Base64-encoded tnsnames.ora files.

This enables flexible and secure configuration for 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
`ocid`	The OCID of the OCI Vault secret containing the `tnsnames.ora` file.	The OCID of the secret	No default value. A value must be configured for this parameter.
`tnsAlias`	Specifies the alias to retrieve the appropriate connection string from the `tnsnames.ora` file.	Any valid alias present in your `tnsnames.ora` file.	No default value. A value must be configured for this parameter.

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

Access Token Provider

The Access Token Provider provides Oracle JDBC with an access token that authorizes logins to an Autonomous Database. This is a Resource Provider identified by the name ojdbc-provider-oci-token.

This provider must be configured to authenticate as an IAM user that has been mapped to a database user. The IAM user must also be included in a policy that grants access to the Autonomous Database. Instructions can be found in the ADB product documentation.

Caching Mechanism

The AccessTokenFactory employs a caching mechanism to efficiently manage and reuse access tokens. By utilizing Oracle JDBC's cache for JWTs, access tokens are cached and updated one minute before they expire, ensuring no blocking of threads. This cache reduces latency when creating JDBC connections, as a thread opening a connection does not have to wait for a new token to be requested.You can check this in more detail at Oracle's documentation.

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

Parameter Name	Description	Accepted Values	Default Value
scope	Specifies the scope of databases that may be accessed with the token. See Configuring a Scope for details.	A URN in any of the following forms is accepted: urn:oracle:db::id::compartment-ocid::database-ocid urn:oracle:db::id::compartment-ocid urn:oracle:db::id::*	urn:oracle:db::id::*

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

Configuring a Scope

The "scope" parameter may be configured as a URN that identifies a database and/or compartment.

The least privileged scope is one that authorizes logins to a single database. This scope is expressed as a URN in the form shown below, where database-ocid is the OCID of a database, and compartment-ocid is the OCID of the compartment that contains the database.

urn:oracle:db::id::comparment-ocid::database-ocid

A more privileged scope is one that authorizes logins to all databases within a compartment. This scope is expressed as a URN in the form shown below, where compartment-ocid is the OCID of the compartment that contains the databases.

urn:oracle:db::id::comparment-ocid

The most privileged scope is one that authorizes logins to all databases within a tenancy. This scope is expressed as the URN shown below, which contains the * symbol.

urn:oracle:db::id::*

Common Parameters for Resource Providers

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

Parameter Name	Description	Accepted Values	Default Value
authenticationMethod	Configures a method of authentication with OCI	Accepted values are defined in: Configuring Authentication	auto-detect
configFile	Configures the path to an OCI configuration file	A file system path	~/.oci/config
profile	Configures the name of a profile in an OCI configuration file	A profile name	DEFAULT

These parameters may be configured as a connection properties recognized by the Oracle JDBC Driver. Parameter names are recognized when appended to the name of a connection property that identifies a provider. For example, when the connection property oracle.jdbc.provider.database identifies a provider, any of the parameter names listed above may be appended to it:

oracle.jdbc.provider.database=ojdbc-provider-oci-database-connection-string
oracle.jdbc.provider.database.authenticationMethod=config-file
oracle.jdbc.provider.database.configFile=/home/app/resources/oci-config
oracle.jdbc.provider.database.profile=APP_PROFILE

In the example above, the parameter names authenticationMethod, configFile, and profile are appended to the name of the connection property oracle.jdbc.provider.database. This has the effect of configuring the Database Connection String Provider, which is identified by that property.

These same parameter names can be appended to the name of any other property that identifies a provider. For instance, a provider identified by the connection property oracle.jdbc.provider.accessToken can be configured with the same parameters seen in the previous example:

oracle.jdbc.provider.accessToken=ojdbc-provider-oci-token
oracle.jdbc.provider.accessToken.authenticationMethod=config-file
oracle.jdbc.provider.accessToken.configFile=/home/app/resources/oci-config
oracle.jdbc.provider.accessToken.profile=APP_PROFILE

Connection properties which identify and configure a provider may appear in a connection properties file or be configured programmatically. Configuration with JVM system properties is not supported.

Configuring Authentication

Providers in this module must authenticate with OCI. By default, a provider will automatically detect any available credentials. A specific credential may be configured using the "authenticationMethod" parameter. The parameter may be set to any of the following values:

config-file: Authenticate with credentials configured by an OCI configuration file .
instance-principal: Authenticate as an instance principal .
resource-principal: Authenticate as a resource principal .
cloud-shell: Authenticate with the session token of a Cloud Shell .
interactive: Authenticate interactively by logging in to a cloud account with your default web browser. The browser window is opened automatically.
auto-detect: This is the default authentication method. The provider will attempt the following authentication methods, in the order listed, until one succeeds: "config-file", "cloud-shell", "resource-principal", and "instance-principal".

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Oracle JDBC Providers for OCI

Centralized Config Providers

Resource Providers

Installation

OCI Database Tools Connections Config Provider

OCI Object Storage Config Provider

JSON Payload format

Password JSON Object

OCI Vault Config Provider

Common Parameters for Centralized Config Providers

Configuring Authentication

Caching configuration

Database Connection String Provider

Database TLS Provider

Vault Password Provider

Vault Username Provider

TCPS Wallet Provider

SEPS Wallet Provider

Vault Connection String Provider

Access Token Provider

Caching Mechanism

Configuring a Scope

Common Parameters for Resource Providers

Configuring Authentication

Files

README.md

Latest commit

History

README.md

File metadata and controls

Oracle JDBC Providers for OCI

Centralized Config Providers

Resource Providers

Installation

OCI Database Tools Connections Config Provider

OCI Object Storage Config Provider

JSON Payload format

Password JSON Object

OCI Vault Config Provider

Common Parameters for Centralized Config Providers

Configuring Authentication

Caching configuration

Database Connection String Provider

Database TLS Provider

Vault Password Provider

Vault Username Provider

TCPS Wallet Provider

SEPS Wallet Provider

Vault Connection String Provider

Access Token Provider

Caching Mechanism

Configuring a Scope

Common Parameters for Resource Providers

Configuring Authentication