Skip to content

Commit cc8f9b4

Browse files
fmeheustfmeheust
committed
First upload
1 parent a7dc26c commit cc8f9b4

21 files changed

+1443
-0
lines changed

‎ojdbc-provider-gcp/README.md

+203
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
# Oracle JDBC Providers for GCP
2+
3+
This module contains providers for integration between Oracle JDBC and
4+
Google Cloud Platform (GCP).
5+
6+
## Centralized Config Providers
7+
8+
<dl>
9+
<dt><a href="#gcp-object-storage-config-provider">GCP Object Storage Config
10+
Provider</a></dt>
11+
<dd>Provides connection properties managed by the Object Storage service</dd>
12+
<dt><a href="#gcp-vault-secret-config-provider">GCP Vault Secret Config Provider</a></dt>
13+
<dd>Provides connection properties managed by the Secret Manager service</dd>
14+
<dt><a href="#common-parameters-for-centralized-config-providers">Common Parameters for Centralized Config Providers</a></dt>
15+
<dd>Common parameters supported by the config providers</dd>
16+
<dt><a href="#caching-configuration">Caching configuration</a></dt>
17+
<dd>Caching mechanism adopted by Centralized Config Providers</dd>
18+
</dl>
19+
20+
## Resource Providers
21+
22+
<dl>
23+
<dt><a href="#vault-password-provider">Vault Password Provider</a></dt>
24+
<dd>Provides passwords managed by the Vault service</dd>
25+
<dt><a href="#vault-username-provider">Vault Username Provider</a></dt>
26+
<dd>Provides usernames managed by the Vault service</dd>
27+
<dt><a href="#common-parameters-for-resource-providers">Common Parameters for Resource Providers</a></dt>
28+
<dd>Common parameters supported by the resource providers</dd>
29+
</dl>
30+
31+
Visit any of the links above to find information and usage examples for a
32+
particular provider.
33+
34+
## Installation
35+
36+
All providers in this module are distributed as single jar on the Maven Central
37+
Repository. The jar is compiled for JDK 8, and is forward compatible with later
38+
JDK versions. The coordinates for the latest release are:
39+
```xml
40+
<dependency>
41+
<groupId>com.oracle.database.jdbc</groupId>
42+
<artifactId>ojdbc-provider-gcp</artifactId>
43+
<version>1.0.1</version>
44+
</dependency>
45+
```
46+
47+
## GCP Object Storage Config Provider
48+
The Oracle DataSource uses a new prefix `jdbc:oracle:thin:@config-gcp-object:` to be able to identify that the configuration parameters should be loaded using GCP Object Storage. Users only need to indicate the project, bucket and object containing the JSON payload, with the following syntax:
49+
50+
<pre>
51+
jdbc:oracle:thin:@config-gcp-object://project={project};bucket={bucket};object={object}]
52+
</pre>
53+
54+
### JSON Payload format
55+
56+
There are 3 fixed values that are looked at the root level.
57+
58+
- connect_descriptor (required)
59+
- user (optional)
60+
- password (optional)
61+
62+
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](https://docs.oracle.com/en/database/oracle/oracle-database/23/jajdb/oracle/jdbc/OracleConnection.html) interface.
63+
64+
For example, let's suppose an url like:
65+
66+
<pre>
67+
jdbc:oracle:thin:@config-gcpobject://project=myproject;bucket=mybucket;object=payload_ojdbc_objectstorage.json
68+
</pre>
69+
70+
And the JSON Payload for the file **payload_ojdbc_objectstorage.json** in the **mybucket** which belongs to the project **myproject** is as following:
71+
72+
```json
73+
{
74+
"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)))",
75+
"user": "scott",
76+
"password": {
77+
"type": "gcpsecret",
78+
"value": "projects/138028249883/secrets/test-secret/versions/1"
79+
},
80+
"jdbc": {
81+
"oracle.jdbc.ReadTimeout": 1000,
82+
"defaultRowPrefetch": 20,
83+
"autoCommit": "false"
84+
}
85+
}
86+
```
87+
88+
The sample code below executes as expected with the previous configuration.
89+
90+
```java
91+
OracleDataSource ds = new OracleDataSource();
92+
ds.setURL("jdbc:oracle:thin:@config-gcpobject://project=myproject;bucket=mybucket;object=payload_ojdbc_objectstorage.json");
93+
Connection cn = ds.getConnection();
94+
Statement st = cn.createStatement();
95+
ResultSet rs = st.executeQuery("select sysdate from dual");
96+
if (rs.next())
97+
System.out.println("select sysdate from dual: " + rs.getString(1));
98+
```
99+
100+
### Password JSON Object
101+
102+
For the JSON type of provider (GCP Object Storage, HTTP/HTTPS, File) the password is an object itself with the following spec:
103+
104+
- type
105+
- Mandatory
106+
- Possible values
107+
- ocivault
108+
- azurevault
109+
- base64
110+
- gcpsecret
111+
- value
112+
- Mandatory
113+
- Possible values
114+
- OCID of the secret (if ocivault)
115+
- Azure Key Vault URI (if azurevault)
116+
- Base64 Encoded password (if base64)
117+
- GCP resource name (if gcpsecret)
118+
- Text
119+
- authentication
120+
- Optional
121+
- Possible Values
122+
- method
123+
- optional parameters (depends on the cloud provider).
124+
125+
## GCP Vault Secret Config Provider
126+
Apart from GCP Object Storage, users can also store JSON Payload in the content of GCP Secret Manager secret. Users need to indicate the resource name:
127+
128+
<pre>
129+
jdbc:oracle:thin:@config-gcpvault:{resource-name}
130+
</pre>
131+
132+
The JSON Payload retrieved by GCP Vault Config Provider follows the same format in [GCP Object Storage Config Provider](#json-payload-format).
133+
134+
## Caching configuration
135+
136+
Config providers in this module store the configuration in caches to minimize
137+
the number of RPC requests to remote location. See
138+
[Caching configuration](../ojdbc-provider-azure/README.md#caching-configuration) for more
139+
details of the caching mechanism.
140+
141+
## Vault Password Provider
142+
The Vault Password Provider provides Oracle JDBC with a password that is managed
143+
by the GCP Secret Manager service. This is a Resource Provider identified by the
144+
name `ojdbc-provider-gcp-secret-password`.
145+
146+
This provider requires the parameters listed below.
147+
<table>
148+
<thead><tr>
149+
<th>Parameter Name</th>
150+
<th>Description</th>
151+
<th>Accepted Values</th>
152+
<th>Default Value</th>
153+
</tr></thead>
154+
<tbody><tr>
155+
<td>secretVersionName</td>
156+
<td>Identifies the secret that is provided.</td>
157+
<td>The resource name of the secret.</td>
158+
<td><i>No default value. A value must be configured for this parameter.</i></td>
159+
</tr></tbody>
160+
</table>
161+
162+
An example of a
163+
[connection properties file](https://docs.oracle.com/en/database/oracle/oracle-database/23/jajdb/oracle/jdbc/OracleConnection.html#CONNECTION_PROPERTY_CONFIG_FILE)
164+
that configures this provider can be found in
165+
[example-vault.properties](example-vault.properties).
166+
167+
## Vault Username Provider
168+
The Vault Username Provider provides Oracle JDBC with a username that is managed by the
169+
GCP Secret Manager service. This is a Resource Provider identified by the name
170+
`ojdbc-provider-gcp-secret-username`.
171+
172+
In addition to the set of [common parameters](#common-parameters-for-resource-providers), this provider
173+
also supports the parameters listed below.
174+
<table>
175+
<thead><tr>
176+
<th>Parameter Name</th>
177+
<th>Description</th>
178+
<th>Accepted Values</th>
179+
<th>Default Value</th>
180+
</tr></thead>
181+
<tbody><tr>
182+
<td>secretVersionName</td>
183+
<td>Identifies the secret that is provided.</td>
184+
<td>The resource name of the secret.</td>
185+
<td><i>No default value. A value must be configured for this parameter.</i></td>
186+
</tr></tbody>
187+
</table>
188+
189+
An example of a
190+
[connection properties file](https://docs.oracle.com/en/database/oracle/oracle-database/23/jajdb/oracle/jdbc/OracleConnection.html#CONNECTION_PROPERTY_CONFIG_FILE)
191+
that configures this provider can be found in
192+
[example-vault.properties](example-vault.properties).
193+
194+
## Configuring Authentication
195+
196+
Providers use Google Cloud APIs which support
197+
[Application Default Credentials](https://cloud.google.com/docs/authentication/application-default-credentials);
198+
the libraries look for credentials in a set of defined locations and use those
199+
credentials to authenticate requests to the API.
200+
201+
202+
203+

‎ojdbc-provider-gcp/example-vault.properties

+56
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
################################################################################
2+
# Copyright (c) 2024 Oracle and/or its affiliates.
3+
#
4+
# The Universal Permissive License (UPL), Version 1.0
5+
#
6+
# Subject to the condition set forth below, permission is hereby granted to any
7+
# person obtaining a copy of this software, associated documentation and/or data
8+
# (collectively the "Software"), free of charge and under any and all copyright
9+
# rights in the Software, and any and all patent rights owned or freely
10+
# licensable by each licensor hereunder covering either (i) the unmodified
11+
# Software as contributed to or provided by such licensor, or (ii) the Larger
12+
# Works (as defined below), to deal in both
13+
#
14+
# (a) the Software, and
15+
# (b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
16+
# one is included with the Software (each a "Larger Work" to which the Software
17+
# is contributed by such licensors),
18+
#
19+
# without restriction, including without limitation the rights to copy, create
20+
# derivative works of, display, perform, and distribute the Software and make,
21+
# use, sell, offer for sale, import, export, have made, and have sold the
22+
# Software and the Larger Work(s), and to sublicense the foregoing rights on
23+
# either these or other terms.
24+
#
25+
# This license is subject to the following condition:
26+
# The above copyright notice and either this complete permission notice or at
27+
# a minimum a reference to the UPL must be included in all copies or
28+
# substantial portions of the Software.
29+
#
30+
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
31+
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
32+
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
33+
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
34+
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
35+
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
36+
# SOFTWARE.
37+
################################################################################
38+
39+
# An example of a connection properties file that configures Oracle JDBC to
40+
# obtain a username and password from OCI's Vault Service.
41+
#
42+
# This file can be located by Oracle JDBC using the "oracle.jdbc.config.file"
43+
# connection property. For details, see:
44+
# https://docs.oracle.com/en/database/oracle/oracle-database/23/jajdb/oracle/jdbc/OracleConnection.html#CONNECTION_PROPERTY_CONFIG_FILE
45+
46+
# Configures the GCP Vault Secret Username Provider. The resurce name of the
47+
# username secret is configured as an environment variable or JVM system
48+
# property named "USERNAME_SECRET_VERSION_NAME":
49+
oracle.jdbc.provider.username=ojdbc-provider-gcp-secret-username
50+
oracle.jdbc.provider.username.secretVersionName=${USERNAME_SECRET_VERSION_NAME}
51+
52+
# Configures the OCI Vault Secret Password Provider. The resource name of the
53+
# password secret is configured as an environment variable or JVM system
54+
# property named "PASSWORD_SECRET_VERSION_NAME":
55+
oracle.jdbc.provider.password=ojdbc-provider-gcp-secret-password
56+
oracle.jdbc.provider.password.secretVersionName=${PASSWORD_SECRET_VERSION_NAME}

‎ojdbc-provider-gcp/pom.xml

+76
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<project xmlns="http://maven.apache.org/POM/4.0.0"
3+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
5+
<modelVersion>4.0.0</modelVersion>
6+
7+
<name>Oracle JDBC GCP Providers</name>
8+
9+
<artifactId>ojdbc-provider-gcp</artifactId>
10+
<version>1.0.1</version>
11+
<packaging>jar</packaging>
12+
13+
<parent>
14+
<groupId>com.oracle.database.jdbc</groupId>
15+
<artifactId>ojdbc-extensions</artifactId>
16+
<version>1.0.1</version>
17+
</parent>
18+
19+
<properties>
20+
<gcp-api-version>26.40.0</gcp-api-version>
21+
</properties>
22+
23+
<dependencyManagement>
24+
<dependencies>
25+
<dependency>
26+
<groupId>com.google.cloud</groupId>
27+
<artifactId>libraries-bom</artifactId>
28+
<version>${gcp-api-version}</version>
29+
<type>pom</type>
30+
<scope>import</scope>
31+
</dependency>
32+
</dependencies>
33+
</dependencyManagement>
34+
35+
<dependencies>
36+
<dependency>
37+
<groupId>com.oracle.database.jdbc</groupId>
38+
<artifactId>ojdbc-provider-common</artifactId>
39+
</dependency>
40+
<dependency>
41+
<groupId>com.oracle.database.jdbc</groupId>
42+
<artifactId>ojdbc8</artifactId>
43+
</dependency>
44+
<dependency>
45+
<groupId>com.google.cloud</groupId>
46+
<artifactId>google-cloud-secretmanager</artifactId>
47+
</dependency>
48+
<dependency>
49+
<groupId>com.google.cloud</groupId>
50+
<artifactId>google-cloud-storage</artifactId>
51+
</dependency>
52+
<!-- TEST DEPENDENCIES -->
53+
54+
<dependency>
55+
<groupId>com.oracle.database.jdbc</groupId>
56+
<artifactId>ojdbc-provider-common</artifactId>
57+
<classifier>tests</classifier>
58+
<type>test-jar</type>
59+
</dependency>
60+
<dependency>
61+
<groupId>com.oracle.database.jdbc</groupId>
62+
<artifactId>ojdbc-provider-common</artifactId>
63+
<classifier>tests</classifier>
64+
<type>test-jar</type>
65+
</dependency>
66+
<dependency>
67+
<groupId>org.junit.jupiter</groupId>
68+
<artifactId>junit-jupiter-api</artifactId>
69+
</dependency>
70+
<dependency>
71+
<groupId>org.junit.jupiter</groupId>
72+
<artifactId>junit-jupiter-engine</artifactId>
73+
</dependency>
74+
</dependencies>
75+
76+
</project>

0 commit comments

Comments
 (0)