This module contains providers for integration between Oracle JDBC and Azure.
- Config Provider for Azure
- Provides connection properties managed by the App Configuration service
- 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
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.0</version>
</dependency>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));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 |
The Azure SDK DefaultAzureCredential class tries the following flow in order to try to Authenticate an application:
- EnvironmentCredential
- ManagedIdentityCredential
- SharedTokenCacheCredential
- VisualStudioCredential
- VisualStudioCodeCredential
- AzureCliCredential
- AzurePowerShellCredential
- InteractiveBrowserCredential
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.
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.
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
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.
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.
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.
| No default value. If interactive authentication is used, a value must be configured for this parameter. |
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.pemIn 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.pemConnection 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.
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".