Adding support for database connections via Oracle Wallet.

Author: jgebal

README.md

@@ -98,16 +98,42 @@ Accepted formats:
 - `<user>/<password>@//<host>[:<port>]/<service>`
 - `<user>/<password>@<host>:<port>:<SID>` 
 - `<user>/<password>@<TNSName>`
+- `/@<TNSName>` - credentials are taken from an Oracle Wallet (Secure External Password Store), see [Oracle Wallet](#oracle-wallet-secure-external-password-store)
 
-To connect using TNS, you need to have the ORACLE_HOME environment variable set.
-The file tnsnames.ora must exist in path %ORACLE_HOME%/network/admin
+To connect using TNS, you need to have either the TNS_ADMIN or the ORACLE_HOME environment variable set.
+The file tnsnames.ora must exist in the TNS_ADMIN directory or in %ORACLE_HOME%/network/admin
 The file tnsnames.ora must contain valid TNS entries. 
 
 In case you use a username containing `/` or a password containing `@` you should encapsulate it with double quotes `"`:
 ```
 utplsql run "my/Username"/"myP@ssword"@connectstring
 ```
 
+#### Oracle Wallet (Secure External Password Store)
+
+To avoid passing the password on the command line, store the credentials in an Oracle Wallet and connect with `/@<TNSName>`:
+```
+utplsql run /@MYDATABASE
+```
+
+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
+```
+
+Instead of setting `TNS_ADMIN` you can also pass it as part of the connect string: `/@MYDATABASE?TNS_ADMIN=/path/to/network/admin`.
+
+The TNS alias used in the connect string must match the alias of the credential stored in the wallet.
+
 ### run
 `utplsql run <ConnectionURL> [<options>]`
 

pom.xml

@@ -15,6 +15,8 @@
         <maven.compiler.release>17</maven.compiler.release>
 
         <utplsql-java-api.version>3.2.4</utplsql-java-api.version>
+        <!-- Temporarly here - it needs to be moved to java-api. Keep in sync with the ojdbc version used by utplsql-java-api -->
+        <oraclepki.version>23.7.0.25.01</oraclepki.version>
 
         <junit.jupiter.version>5.12.2</junit.jupiter.version>
         <picocli.version>4.7.7</picocli.version>
@@ -73,6 +75,12 @@
             <artifactId>utplsql-java-api</artifactId>
             <version>${utplsql-java-api.version}</version>
         </dependency>
+        <!-- Temporarly here - it needs to be moved to java-api. Required by ojdbc to read Oracle Wallets (Secure External Password Store) -->
+        <dependency>
+            <groupId>com.oracle.database.security</groupId>
+            <artifactId>oraclepki</artifactId>
+            <version>${oraclepki.version}</version>
+        </dependency>
         <dependency>
             <groupId>javax.xml.bind</groupId>
             <artifactId>jaxb-api</artifactId>

src/main/java/org/utplsql/cli/ConnectionConfig.java

@@ -5,15 +5,21 @@
 
 public class ConnectionConfig {
 
+    /**
+     * Either {@code <user>/<password>@<connect>} or {@code /@<connect>}.
+     */
+    private static final Pattern CONNECT_STRING_PATTERN =
+            Pattern.compile("^(?:(\".+\"|[^/]+)/(\".+\"|[^@]+)|/)@(.*)$");
+
     private final String user;
     private final String password;
     private final String connect;
 
     public ConnectionConfig(String connectString) {
-        Matcher m = Pattern.compile("^(\".+\"|[^/]+)/(\".+\"|[^@]+)@(.*)$").matcher(connectString);
+        Matcher m = CONNECT_STRING_PATTERN.matcher(connectString);
         if (m.find()) {
-            user = stripEnclosingQuotes(m.group(1));
-            password = stripEnclosingQuotes(m.group(2));
+            user = m.group(1) == null ? null : stripEnclosingQuotes(m.group(1));
+            password = m.group(2) == null ? null : stripEnclosingQuotes(m.group(2));
             connect = m.group(3);
         } else {
             throw new IllegalArgumentException("Not a valid connectString: '" + connectString + "'");
@@ -42,7 +48,18 @@ public String getPassword() {
         return password;
     }
 
+    /**
+     * @return true when no user/password was given (connect string {@code /@<connect>}),
+     * meaning credentials are provided externally, e.g. by an Oracle Wallet
+     */
+    public boolean isExternalAuthentication() {
+        return user == null;
+    }
+
     public String getConnectString() {
+        if (isExternalAuthentication()) {
+            return "/@" + connect;
+        }
         return user + "/" + password + "@" + connect;
     }
 

src/main/java/org/utplsql/cli/DataSourceProvider.java

@@ -14,10 +14,15 @@
 public class DataSourceProvider {
 
     static {
-        String oracleHome = System.getenv("ORACLE_HOME");
-        if (oracleHome != null && System.getProperty("oracle.net.tns_admin") == null) {
-            System.setProperty("oracle.net.tns_admin",
-                    String.join(File.separator, oracleHome, "NETWORK", "ADMIN"));
+        if (System.getProperty("oracle.net.tns_admin") == null) {
+            String tnsAdmin = System.getenv("TNS_ADMIN");
+            String oracleHome = System.getenv("ORACLE_HOME");
+            if (tnsAdmin != null && !tnsAdmin.isEmpty()) {
+                System.setProperty("oracle.net.tns_admin", tnsAdmin);
+            } else if (oracleHome != null) {
+                System.setProperty("oracle.net.tns_admin",
+                        String.join(File.separator, oracleHome, "NETWORK", "ADMIN"));
+            }
         }
     }
 

src/main/java/org/utplsql/cli/datasource/TestedDataSourceProvider.java

@@ -49,8 +49,11 @@ private void setThickOrThinJdbcUrl(InitializableOracleDataSource ds) throws SQLE
         List<String> errors = new ArrayList<>();
         Throwable lastException = null;
 
-        ds.setUser(config.getUser());
-        ds.setPassword(config.getPassword());
+        // With external authentication (Oracle Wallet) the driver looks up the credentials itself
+        if (!config.isExternalAuthentication()) {
+            ds.setUser(config.getUser());
+            ds.setPassword(config.getPassword());
+        }
 
         for (ConnectStringPossibility possibility : possibilities) {
             logger.debug("Try connecting {}", possibility.getMaskedConnectString(config));
@@ -107,7 +110,7 @@ public String getConnectString(ConnectionConfig config) {
 
         @Override
         public String getMaskedConnectString(ConnectionConfig config) {
-            return "jdbc:oracle:oci8:****/****@" + config.getConnect();
+            return "jdbc:oracle:oci8:" + maskedCredentials(config) + "@" + config.getConnect();
         }
     }
 
@@ -119,7 +122,11 @@ public String getConnectString(ConnectionConfig config) {
 
         @Override
         public String getMaskedConnectString(ConnectionConfig config) {
-            return "jdbc:oracle:thin:****/****@" + config.getConnect();
+            return "jdbc:oracle:thin:" + maskedCredentials(config) + "@" + config.getConnect();
         }
     }
+
+    private static String maskedCredentials(ConnectionConfig config) {
+        return config.isExternalAuthentication() ? "/" : "****/****";
+    }
 }

src/test/java/org/utplsql/cli/ConnectionConfigTest.java

@@ -1,6 +1,8 @@
 package org.utplsql.cli;
 
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
 
 import static org.junit.jupiter.api.Assertions.*;
 
@@ -54,4 +56,54 @@ void parseSpecialCharsUser() {
         assertEquals("my.local.host/service", info.getConnect());
         assertFalse(info.isSysDba());
     }
+
+    @Test
+    void parseCredentialsIsNotExternalAuthentication() {
+        ConnectionConfig info = new ConnectionConfig("test/pw@MY_TNS_ALIAS");
+
+        assertFalse(info.isExternalAuthentication());
+        assertEquals("test/pw@MY_TNS_ALIAS", info.getConnectString());
+    }
+
+    @Test
+    void parseExternalAuthentication() {
+        ConnectionConfig info = new ConnectionConfig("/@MY_TNS_ALIAS");
+
+        assertNull(info.getUser());
+        assertNull(info.getPassword());
+        assertEquals("MY_TNS_ALIAS", info.getConnect());
+        assertTrue(info.isExternalAuthentication());
+        assertFalse(info.isSysDba());
+        assertEquals("/@MY_TNS_ALIAS", info.getConnectString());
+    }
+
+    @Test
+    void parseExternalAuthenticationWithTnsAdminInUrl() {
+        ConnectionConfig info = new ConnectionConfig("/@MY_TNS_ALIAS?TNS_ADMIN=/home/me/oracle/network/admin");
+
+        assertNull(info.getUser());
+        assertNull(info.getPassword());
+        assertEquals("MY_TNS_ALIAS?TNS_ADMIN=/home/me/oracle/network/admin", info.getConnect());
+        assertTrue(info.isExternalAuthentication());
+    }
+
+    @Test
+    void parseExternalAuthenticationWithEzConnect() {
+        ConnectionConfig info = new ConnectionConfig("/@//my.local.host:1521/service");
+
+        assertEquals("//my.local.host:1521/service", info.getConnect());
+        assertTrue(info.isExternalAuthentication());
+    }
+
+    @ParameterizedTest
+    @ValueSource(strings = {
+            "/pw@MY_TNS_ALIAS",   // password without user
+            "test/@MY_TNS_ALIAS", // user without password
+            "@MY_TNS_ALIAS",
+            "test@MY_TNS_ALIAS",
+            "MY_TNS_ALIAS"
+    })
+    void rejectInvalidConnectString(String connectString) {
+        assertThrows(IllegalArgumentException.class, () -> new ConnectionConfig(connectString));
+    }
 }

src/test/java/org/utplsql/cli/WalletConnectionIT.java

@@ -0,0 +1,101 @@
+package org.utplsql.cli;
+
+import oracle.security.pki.OracleSecretStore;
+import oracle.security.pki.OracleWallet;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+import org.utplsql.cli.datasource.TestedDataSourceProvider;
+
+import javax.sql.DataSource;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.sql.Connection;
+import java.sql.ResultSet;
+import java.sql.Statement;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.junit.jupiter.api.Assumptions.assumeTrue;
+
+/**
+ * Connecting with {@code /@<TNS alias>} using credentials stored in an Oracle Wallet
+ * (Secure External Password Store), see issue #225.
+ * <p>
+ * The wallet, tnsnames.ora and ojdbc.properties are created on the fly from DB_URL / DB_USER / DB_PASS,
+ * so no Oracle client tooling (mkstore/orapki) is needed.
+ */
+class WalletConnectionIT {
+
+    private static final String TNS_ALIAS = "UTPLSQL_CLI_WALLET";
+    private static final Pattern EZ_CONNECT = Pattern.compile("^//([^:/]+)(?::(\\d+))?/(.+)$");
+
+    @TempDir
+    static Path tnsAdmin;
+
+    private static String walletConnectString;
+
+    @BeforeAll
+    static void createWallet() throws Exception {
+        Matcher m = EZ_CONNECT.matcher(TestHelper.getUrl());
+        assumeTrue(m.matches(), "DB_URL must be in //host[:port]/service format to generate tnsnames.ora");
+        String host = m.group(1);
+        String port = m.group(2) == null ? "1521" : m.group(2);
+        String service = m.group(3);
+
+        Path walletDir = Files.createDirectories(tnsAdmin.resolve("wallet"));
+        char[] walletPassword = "Wallet_Pwd_123".toCharArray();
+
+        OracleWallet wallet = new OracleWallet();
+        wallet.create(walletPassword);
+        OracleSecretStore secretStore = wallet.getSecretStore();
+        secretStore.createCredential(TNS_ALIAS.toCharArray(),
+                TestHelper.getUser().toCharArray(),
+                TestHelper.getPass().toCharArray());
+        wallet.setSecretStore(secretStore);
+        wallet.saveAs(walletDir.toString());
+        wallet.createSSO();
+        wallet.saveSSO();
+
+        assertTrue(Files.exists(walletDir.resolve("cwallet.sso")), "auto-login wallet was not created");
+
+        Files.writeString(tnsAdmin.resolve("tnsnames.ora"),
+                TNS_ALIAS + " = (DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(HOST = " + host + ")(PORT = " + port + "))"
+                        + "(CONNECT_DATA = (SERVICE_NAME = " + service + ")))\n");
+        Files.writeString(tnsAdmin.resolve("ojdbc.properties"),
+                "oracle.net.wallet_location=(SOURCE=(METHOD=FILE)(METHOD_DATA=(DIRECTORY="
+                        + forwardSlashes(walletDir) + ")))\n");
+
+        walletConnectString = "/@" + TNS_ALIAS + "?TNS_ADMIN=" + forwardSlashes(tnsAdmin);
+    }
+
+    private static String forwardSlashes(Path path) {
+        return path.toAbsolutePath().toString().replace('\\', '/');
+    }
+
+    @Test
+    void connectsAsWalletUser() throws Exception {
+        ConnectionConfig config = new ConnectionConfig(walletConnectString);
+        DataSource dataSource = new TestedDataSourceProvider(config, 1).getDataSource();
+
+        try (Connection con = dataSource.getConnection();
+             Statement stmt = con.createStatement();
+             ResultSet rs = stmt.executeQuery("select user from dual")) {
+            assertTrue(rs.next());
+            assertEquals(TestHelper.getUser().toUpperCase(), rs.getString(1));
+        }
+    }
+
+    @Test
+    void runCommandWithWallet() {
+        int result = TestHelper.runApp("run",
+                walletConnectString,
+                "-f=ut_documentation_reporter",
+                "-s",
+                "--failure-exit-code=0");
+
+        assertEquals(0, result);
+    }
+}