Skip to content

Latest commit

 

History

History
792 lines (716 loc) · 34.3 KB

README.md

File metadata and controls

792 lines (716 loc) · 34.3 KB
Raw

Oracle JDBC Providers for Azure

This module contains providers for integration between Oracle JDBC and Azure.

Centralized Config Providers

Azure App Configuration Provider
Provides connection properties managed by the App Configuration service
Azure Vault Config Provider
Provides connection properties managed by the Key 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

Access Token Provider
Provides access tokens issued by the Active Directory service
Key Vault Username Provider
Provides a username from the Key Vault service
Key Vault Password Provider
Provides a password from the Key Vault service
Key Vault TCPS Wallet Provider
Provides TCPS/TLS wallet for secure connections to an Autonomous Database from the Key Vault service
Key Vault SEPS Wallet Provider
Provides SEPS (Secure External Password Store) wallets for secure username and password retrieval from the Key Vault service
Key Vault Connection String Provider
Provides connection strings for secure database connectivity based on aliases, retrieved from the tnsnames.ora file stored in Azure Key Vault.
Common Parameters for Resource Providers
Common parameters supported by the resource providers

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-azure</artifactId>
  <version>1.0.1</version>
</dependency>

Azure App Configuration Provider

The Config Provider for Azure is a Centralized Config Provider that provides Oracle JDBC with connection properties from the App Configuration service and the Key Vault service.

A new prefix of the JDBC URL jdbc:oracle:thin:@config-azure:// is used by the Oracle DataSource to be able to identify that the configuration parameters should be loaded using Azure App Configuration. Users only need to indicate the App Config's name, a prefix for the key-names and a label (both optional) with the following syntax:

jdbc:oracle:thin:@config-azure://{appconfig-name}[?key=prefix&label=value&option1=value1&option2=value2...]

If prefix and label are not informed, the provider will retrieve all the values that are not labeled or prefixed.

There are 3 fixed values that are looked at by the provider in the retrieved configuration:

  • 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-azure://myappconfig?key=/sales_app1/&label=dev

And the configuration in App Configuration 'myappconfig' as follows (note that some values such as password can be a reference to a Key Vault secret):

Key Value Label
/sales_app1/user scott dev
/sales_app1/connect_descriptor (description=(address=(protocol=tcps)(port=1521)(host=adb.us-phoenix-1.oraclecloud.com))(connect_data=(service_name=gebqqvpozhjbqbs_dbtest_medium.adb.oraclecloud.com))) dev
/sales_app1/password {"uri":"myvault.vault.azure.net/secrets/mysecret"} dev
/sales_app1/jdbc/autoCommit false dev
/sales_app1/jdbc/oracle.jdbc.fanEnabled true dev
/sales_app1/jdbc/oracle.jdbc.loginTimeout 20 dev

In this case the OracleDataSource that gets generated uses the above values as its properties.

The sample code below executes as expected with the previous configuration (and the Azure Credentials set as explained below).

    OracleDataSource ds = new OracleDataSource();
    ds.setURL("jdbc:oracle:thin:@config-azure://myappconfig?key=/sales_app1/&label=dev");
    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));

Azure Vault Config Provider

Similar to OCI Vault Config Provider, JSON Payload can also be stored in the content of Azure Key Vault Secret. The Oracle DataSource uses a new prefix jdbc:oracle:thin:@config-azurevault://. Users only need to indicate the Vault Secret’s secret identifier, with the following syntax:

jdbc:oracle:thin:@config-azurevault://{secret-identifier}

To view an example format of JSON Payload, please refer to JSON Payload format.

Common Parameters for Centralized Config Providers

Provider that are classified as Centralized Config Providers in this module share the same sets of parameters for authentication configuration.

Configuring Authentication

This provider relies upon the Azure SDK Credential Classes to provide authorization and authentication to the App Configuration and Key Vault services. The parameters that the SDK retrieves through environment variables are retrieved the same way and the attributes that are exposed through the API are exposed in the DataSource URL as option parameters.

The user can provide an optional parameter AUTHENTICATION (case-ignored) which is mapped with the following Credential Class.

'AUTHENTICATION' Param Value Credential Class Required Parameters
(if not already set as an environment variable)		 Optional Parameters
AZURE_DEFAULT or <Empty> DefaultAzureCredential see below DefaultAzureCredential AZURE_TENANT_ID
AZURE_MANAGED_IDENTITY_CLIENT_ID
AZURE_SERVICE_PRINCIPAL (with secret: will be picked if AZURE_CLIENT_SECRET is set).
It has priority over service principal with certificate.		 ClientSecretCredential AZURE_CLIENT_ID  
AZURE_CLIENT_SECRET
AZURE_TENANT_ID
AZURE_SERVICE_PRINCIPAL (with certificate: will be picked if AZURE_CLIENT_CERTIFICATE_PATH is set). ClientCertificateCredential AZURE_CLIENT_ID AZURE_CLIENT_CERTIFICATE_PASSWORD
AZURE_CLIENT_CERTIFICATE_PATH
AZURE_TENANT_ID
AZURE_MANAGED_IDENTITY ManagedIdentityCredential   AZURE_CLIENT_ID (only required for user assigned)
AZURE_INTERACTIVE InteractiveBrowserCredential AZURE_CLIENT_ID AZURE_REDIRECT_URL

DefaultAzureCredential

The Azure SDK DefaultAzureCredential class tries the following flow in order to try to Authenticate an application:

Caching configuration

Config providers in this module store the configuration in caches to minimize the number of RPC requests to remote location. Every stored items has a property that defines the time-to-live (TTL) value. When TTL expires, the configuration becomes "softly expired" and the stored configuration will be refreshed by a background thread. If configuration cannot be refreshed, it can still be used for another 30 minutes until it becomes "hardly expired". In other words, it takes 24 hours and 30 minutes for configuration before it becomes completely expired.

The default value of TTL is 24 hours and it can be configured using the "config_time_to_live" property in the unit of seconds. An example of App Configuration in Azure with TTL of 60 seconds is listed below.

Key Value
user myUsername
password myPassword
connect_descriptor myHost:5521/myService
config_time_to_live 60

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-azure-token.

This provider must be configured to authenticate as an Active Directory application that has been mapped to a database user. 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 URI of the following form is accepted:
application-id-uri/scope-name 		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-token.properties.

Configuring a Scope

The "scope" parameter must be configured as the Application ID URI of a database that has been registered with Active Directory. The path segment of the URI may include the name of a scope that is recognized by the database application. In the example below, a scope named "session:scope:connect" is appended to the path of the Application ID URI "https://example.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/":

https://example.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/session:scope:connect

To use the default scope, append ".default" to path instead:

https://example.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/.default

Key Vault Username Provider

The Key Vault Username Provider provides Oracle JDBC with a database username that is managed by the Key Vault service. This is a Resource Provider identified by the name ojdbc-provider-azure-key-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
vaultUrl The URI of a Key Vault. The URI will typically have the following form: 
https://{vault-name}.vault.azure.net/
No default value. A value must be configured for this parameter.
secretName The name of a Key Vault Secret. Any valid secret name is accepted. 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.

Key Vault Password Provider

The Key Vault Password Provider provides Oracle JDBC with a database password that is managed by the Key Vault service. This is a Resource Provider identified by the name ojdbc-provider-azure-key-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
vaultUrl The URI of a Key Vault. The URI will typically have the following form: 
https://{vault-name}.vault.azure.net/
No default value. A value must be configured for this parameter.
secretName The name of a Key Vault Secret. Any valid secret name is accepted. 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.

Key Vault TCPS Wallet Provider

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

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), ou may store it in an Azure Key Vault secret for additional security. You can then use this provider that will retrieve the wallet content from Azure Key Vault using the Azure 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 walletpassword 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
vaultUrl The URL of the Azure Key Vault containing the TCPS file. The Azure Key Vault URL, typically in the form: 
https://{vault-name}.vault.azure.net/
 No default value. A value must be configured for this parameter.
secretName The name of the secret containing the TCPS wallet file in Azure Key Vault. Any valid secret name 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-key-vault-wallet.properties.

Key Vault SEPS Wallet Provider

The SEPS Wallet Provider provides Oracle JDBC with a username and password managed by the Azure Key Vault service, stored in a Secure External Password Store (SEPS) wallet. This is a Resource Provider identified by the name ojdbc-provider-azure-key-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
vaultUrl The URL of the Azure Key Vault containing the SEPS wallet. The Azure Key Vault URL, typically in the form: 
https://{vault-name}.vault.azure.net/
 No default value. A value must be configured for this parameter.
secretName The name of the secret containing the SEPS wallet file in Azure Key Vault. Any valid secret name 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-key-vault-wallet.properties.

Key Vault Connection String Provider

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

This provider retrieves and decodes a tnsnames.ora file stored as a base64-encoded secret in Azure Key Vault, 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
vaultUrl The URL of the Azure Key Vault containing the tnsnames.ora file. The Azure Key Vault URL, typically in the form:
https://{vault-name}.vault.azure.net/
 No default value. A value must be configured for this parameter.
secretName The name of the secret containing the tnsnames.ora file in Azure Key Vault. Any valid secret name. 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-key-vault.properties.

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 Azure Accepted values are defined in: Configuring Authentication auto-detect
tenantId Configures the ID of the application's Azure Active Directory tenant. An Active Directory tenant ID No default value. If TENANT_ID is configured as an Azure SDK environment variable , it will be used.
clientId Configures the ID of an Azure Active Directory application. An Active Directory application ID No default value. If CLIENT_ID is configured as an Azure SDK environment variable , it will be used.
clientCertificatePath Configures the file system path to a certificate of an Azure Active Directory application. An Active Directory application certificate . The file may be use PEM or PFX encoding. No default value. If CLIENT_CERTIFICATE_PATH is configured as an Azure SDK environment variable , it will be used.
clientCertificatePassword Configures the password for a PFX certificate of an Azure Active Directory application. An PFX certificate password. No default value. If CLIENT_CERTIFICATE_PASSWORD is configured as an Azure SDK environment variable , it will be used.
clientSecret Configures a secret of an Azure Active Directory application. An Active Directory application secret . No default value. If CLIENT_SECRET is configured as an Azure SDK environment variable , it will be used.
username Configures the username of an Azure account. A username, which is typically an email address. No default value. If AZURE_USERNAME is configured as an Azure SDK environment variable , it will be used.
password Configures the password of an Azure account. The password of an Azure account. No default value. If AZURE_PASSWORD is configured as an Azure SDK environment variable , it will be used.
redirectUrl Redirect URL for authentication-method=interactive A URL of the form http://localhost[:port-number] is accepted. http://localhost (redirects to any available port in the ephemeral range)

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.password identifies a provider, any of the parameter names listed above may be appended to it:

oracle.jdbc.provider.password=ojdbc-provider-azure-key-vault-password
oracle.jdbc.provider.password.authenticationMethod=service-principal
oracle.jdbc.provider.password.tenantId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
oracle.jdbc.provider.password.clientId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
oracle.jdbc.provider.password.clientCertificatePath=/users/app/certificate.pem

In the example above, the parameter names authenticationMethod, tenantId, clientId, and clientCertificatePath are appended to the name of the connection property oracle.jdbc.provider.password. This has the effect of configuring the Key Vault Password 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-azure-token
oracle.jdbc.provider.accessToken.authenticationMethod=service-principal
oracle.jdbc.provider.accessToken.tenantId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
oracle.jdbc.provider.accessToken.clientId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
oracle.jdbc.provider.accessToken.clientCertificatePath=/users/app/certificate.pem

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 for Resource Providers

Resource Providers in this module must authenticate with Azure. 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:

service-principal
Authenticate as an application service principal . A tenant ID and client ID must be configured, along with a certificate or a secret.
managed-identity
Authenticate as a managed identity . A client ID may be configured to authenticate as a user assigned managed identity.
password
Authenticate as an Azure user account. A client ID must be configured, along with a username and password.
device-code
Authenticate interactively by logging in to an Azure account in a web browser. A browser link is output to the standard output stream.
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: "service-principal", "password", and "managed-identity".