Adding support for Oracle Wallet (Secure External Password Store)

Author: jgebal

README.md

@@ -70,7 +70,7 @@ Please refer to the following usage example for the parameters descriptions:
         <!-- -DdbUser="user" -->
         <dbUser>user</dbUser>
         <!-- Database connection password. -->
-        <!-- -DdbPassword="password" -->
+        <!-- -DdbPass="password" -->
         <dbPass>password</dbPass>
     </properties>
 
@@ -253,6 +253,40 @@ directory:
 * **type-mapping-project:** Example how to use regex and custom type parameters together.
 * **owner-param-project:** Demonstrates how to use sourcesOwner and testsOwner parameters.
 
+### Oracle Wallet (Secure External Password Store)
+
+To keep the database password out of the `pom.xml` and the command line, store the credentials in an Oracle Wallet,
+leave `dbUser` and `dbPass` unset and point `dbUrl` to the TNS alias of the stored credential:
+
+```xml
+<properties>
+    <dbUrl>jdbc:oracle:thin:@MYDATABASE</dbUrl>
+</properties>
+```
+
+Setup example:
+
+```
+# create an auto-login wallet with credentials for TNS alias MYDATABASE
+orapki wallet create -wallet $HOME/oracle/wallet -auto_login_local
+mkstore -wrl $HOME/oracle/wallet -createCredential MYDATABASE someusername
+
+# point the JDBC driver to the wallet
+echo "oracle.net.wallet_location=(SOURCE=(METHOD=FILE)(METHOD_DATA=(DIRECTORY=$HOME/oracle/wallet)))" \
+  > $HOME/oracle/network/admin/ojdbc.properties
+
+# tnsnames.ora with the MYDATABASE entry must be in the same directory
+export TNS_ADMIN=$HOME/oracle/network/admin
+```
+
+The JDBC driver looks for `tnsnames.ora` and `ojdbc.properties` in the directory given by (in order of precedence):
+
+1. `TNS_ADMIN` parameter in the URL, e.g. `jdbc:oracle:thin:@MYDATABASE?TNS_ADMIN=/path/to/network/admin`
+2. Java system property `oracle.net.tns_admin`, e.g. `export MAVEN_OPTS="-Doracle.net.tns_admin=/path/to/network/admin"`
+3. `TNS_ADMIN` environment variable
+
+The TNS alias used in `dbUrl` must match the alias of the credential stored in the wallet.
+
 ## Comparison with utPLSQL CLI
 
 | CLI short parameter  | CLI long parameter         | Maven XML path                                   |

pom.xml

@@ -16,7 +16,7 @@
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
         <maven.compiler.release>17</maven.compiler.release>
 
-        <utplsql-java-api.version>3.2.4</utplsql-java-api.version>
+        <utplsql-java-api.version>3.2.5-SNAPSHOT</utplsql-java-api.version>
 
         <!-- Minimum Maven API version required to run this plugin -->
         <maven.version>3.9.9</maven.version>

src/test/java/org/utplsql/maven/plugin/UtPlsqlMojoTest.java

@@ -1,15 +1,19 @@
 package org.utplsql.maven.plugin;
 
+import oracle.security.pki.OracleSecretStore;
+import oracle.security.pki.OracleWallet;
 import org.apache.maven.plugin.MojoExecutionException;
 import org.apache.maven.plugin.testing.MojoRule;
 import org.junit.Rule;
 import org.junit.Test;
+import org.junit.rules.TemporaryFolder;
 import org.utplsql.api.FileMapperOptions;
 import org.utplsql.maven.plugin.model.ReporterParameter;
 
 import java.io.ByteArrayOutputStream;
 import java.io.File;
 import java.io.PrintStream;
+import java.nio.file.Files;
 import java.util.List;
 
 import static org.junit.Assert.assertEquals;
@@ -20,9 +24,14 @@
 
 public class UtPlsqlMojoTest {
 
+    private static final String WALLET_TNS_ALIAS = "UTPLSQL_MAVEN_WALLET";
+
     @Rule
     public final MojoRule rule = new MojoRule();
 
+    @Rule
+    public final TemporaryFolder temporaryFolder = new TemporaryFolder();
+
     /**
      * Invalid Sources Directory
      * <p>
@@ -322,6 +331,78 @@ public void db_config_using_system_properties() throws Exception {
         System.clearProperty("dbPass");
     }
 
+    /**
+     * Connection using Oracle Wallet (Secure External Password Store)
+     * <p>
+     * Given : a pom.xml without dbUser and dbPass and a dbUrl pointing to a TNS alias stored in an Oracle Wallet
+     * When : tests are run
+     * Then : credentials are taken from the wallet
+     */
+    @Test
+    public void wallet_connection_without_credentials() throws Exception {
+        System.setProperty("dbUrl", walletDbUrl());
+        try {
+            UtPlsqlMojo utPlsqlMojo = createUtPlsqlMojo("wallet_connection");
+            assertNotNull(utPlsqlMojo);
+
+            utPlsqlMojo.execute();
+        } finally {
+            System.clearProperty("dbUrl");
+        }
+    }
+
+    /**
+     * Connection using Oracle Wallet with empty credentials
+     * <p>
+     * Given : a dbUrl pointing to a TNS alias stored in an Oracle Wallet and empty dbUser and dbPass (e.g. -DdbUser= -DdbPass=)
+     * When : tests are run
+     * Then : empty credentials are ignored and credentials are taken from the wallet
+     */
+    @Test
+    public void wallet_connection_with_empty_credentials() throws Exception {
+        System.setProperty("dbUrl", walletDbUrl());
+        System.setProperty("dbUser", "");
+        System.setProperty("dbPass", "");
+        try {
+            UtPlsqlMojo utPlsqlMojo = createUtPlsqlMojo("wallet_connection");
+            assertNotNull(utPlsqlMojo);
+
+            utPlsqlMojo.execute();
+        } finally {
+            System.clearProperty("dbUrl");
+            System.clearProperty("dbUser");
+            System.clearProperty("dbPass");
+        }
+    }
+
+    /**
+     * Creates an auto-login Oracle Wallet holding the UT3 credentials for {@link #WALLET_TNS_ALIAS},
+     * with tnsnames.ora and ojdbc.properties next to it, so no Oracle client tooling (mkstore/orapki) is needed.
+     *
+     * @return JDBC URL of the TNS alias, with the generated directory as TNS_ADMIN
+     */
+    private String walletDbUrl() throws Exception {
+        File tnsAdmin = temporaryFolder.newFolder("tns_admin");
+
+        OracleWallet wallet = new OracleWallet();
+        wallet.create("Wallet_Pwd_123".toCharArray());
+        OracleSecretStore secretStore = wallet.getSecretStore();
+        secretStore.createCredential(WALLET_TNS_ALIAS.toCharArray(), "UT3".toCharArray(), "ut3".toCharArray());
+        wallet.setSecretStore(secretStore);
+        wallet.saveAs(tnsAdmin.getPath());
+        wallet.createSSO();
+        wallet.saveSSO();
+
+        Files.writeString(tnsAdmin.toPath().resolve("tnsnames.ora"),
+                WALLET_TNS_ALIAS + " = (DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(HOST = localhost)(PORT = 1521))"
+                        + "(CONNECT_DATA = (SERVICE_NAME = FREEPDB1)))\n");
+        // ${TNS_ADMIN} is resolved by the JDBC driver, the same way as in wallets downloaded for Oracle Autonomous Database
+        Files.writeString(tnsAdmin.toPath().resolve("ojdbc.properties"),
+                "oracle.net.wallet_location=(SOURCE=(METHOD=FILE)(METHOD_DATA=(DIRECTORY=${TNS_ADMIN})))\n");
+
+        return "jdbc:oracle:thin:@" + WALLET_TNS_ALIAS + "?TNS_ADMIN=" + tnsAdmin.getAbsolutePath().replace('\\', '/');
+    }
+
     /**
      * Exclude a list of objects
      * <p>

src/test/resources/unit-tests/wallet_connection/pom.xml

@@ -0,0 +1,33 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <groupId>org.utplsql</groupId>
+    <artifactId>utplsql-maven-plugin-test</artifactId>
+    <version>3.1.0-SNAPSHOT</version>
+    <packaging>pom</packaging>
+
+    <!-- dbUrl pointing to a TNS alias stored in an Oracle Wallet is set by the test; dbUser and dbPass are not given -->
+
+    <build>
+        <directory>../../../target</directory>
+        <plugins>
+            <plugin>
+                <groupId>org.utplsql</groupId>
+                <artifactId>utplsql-maven-plugin</artifactId>
+                <version>@project.version@</version>
+                <goals>
+                    <goal>test</goal>
+                </goals>
+                <configuration>
+                    <!-- only the connection is verified here, not the test results -->
+                    <ignoreFailure>true</ignoreFailure>
+                    <paths>
+                        <path>app</path>
+                    </paths>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+</project>