Prepare an Oracle wallet for Gluesync

The Oracle agents (LogMiner, XStream and Triggers) can connect through a TNS alias defined in a wallet folder, instead of the host and the port of the form. This page shows how to get the wallet, which files Gluesync reads, and how to change the paths inside them so that they point to the folder that Gluesync can access.

The wallet resolves the alias and secures the connection: it holds the CA certificates that the server certificate is validated against and, for a listener that requires client authentication such as Autonomous Database, the client certificate. It does not replace the credentials: Gluesync always sends the user name and the password that you enter in the form.

What Gluesync reads from the wallet folder

Gluesync opens jdbc:oracle:thin:@<Instance name>?TNS_ADMIN=<Wallet path>, so the folder in Wallet path is the TNS_ADMIN of the Oracle JDBC driver.

File Role

File	Role
`tnsnames.ora`	Defines the alias that you enter in Instance name (and in LogMiner instance name for the LogMiner agent). Required.
`ojdbc.properties`	Tells the driver where the wallet is, with `oracle.net.wallet_location`. Required for an alias that uses TCPS.
`cwallet.sso`	The auto-login wallet, which the driver opens without a password. Required for an alias that uses TCPS.
`ewallet.p12`	The wallet protected by a password. The driver does not need it, but keep it with the other files.
`sqlnet.ora`	Not read by Gluesync to find the wallet: `WALLET_LOCATION` in this file has no effect on Gluesync. Keep it if other Oracle tools use the folder.

tnsnames.ora

Defines the alias that you enter in Instance name (and in LogMiner instance name for the LogMiner agent). Required.

ojdbc.properties

Tells the driver where the wallet is, with oracle.net.wallet_location. Required for an alias that uses TCPS.

cwallet.sso

The auto-login wallet, which the driver opens without a password. Required for an alias that uses TCPS.

ewallet.p12

The wallet protected by a password. The driver does not need it, but keep it with the other files.

sqlnet.ora

Not read by Gluesync to find the wallet: WALLET_LOCATION in this file has no effect on Gluesync. Keep it if other Oracle tools use the folder.

Editing WALLET_LOCATION in sqlnet.ora is not enough. We tested the Oracle JDBC drivers that Gluesync bundles (23.3, 23.9 and 23.26) against a TCPS endpoint whose certificate was issued by a CA held only in the wallet: with WALLET_LOCATION in sqlnet.ora set to the right folder and no ojdbc.properties, the connection failed with PKIX path building failed. With ojdbc.properties it succeeded.

An alias that uses plain TCP needs only tnsnames.ora: the wallet files are read only for TCPS.

Get the wallet

Oracle Autonomous Database (OCI)

Sign in to the Oracle Cloud Infrastructure (OCI) console;
Go to Oracle Database → Autonomous Database and select your database;
On the details page of the database, select Database connection;
Choose the wallet type, Instance wallet for this database or Regional wallet for every database of the region, and select Download wallet;
Enter a password for the wallet and confirm the download. Gluesync does not need this password, because it uses the auto-login wallet cwallet.sso;
Extract the .zip file into a new folder. It contains, among other files, cwallet.sso, ewallet.p12, tnsnames.ora, sqlnet.ora and ojdbc.properties.

The tnsnames.ora of the wallet defines one alias per service, such as <database>_high, <database>_medium and <database>_low. Enter one of them in Instance name.

The ojdbc.properties of the wallet already contains the line that Gluesync needs. Check that it is not commented out:

oracle.net.wallet_location=(SOURCE=(METHOD=FILE)(METHOD_DATA=(DIRECTORY=${TNS_ADMIN})))

Leave the javax.net.ssl.* lines of the same file commented out.

Oracle Database on premises

Create a dedicated wallet for Gluesync instead of copying the wallet of the database server. The wallet of the server holds the private key of the server, which must not leave it, and a new wallet holds no trusted certificate until you add one.

Get the certificate of the CA that issued the certificate of the listener, from your PKI or by exporting it from the wallet of the server with orapki wallet export;
Create an auto-login wallet and add the CA certificate to it as a trusted certificate. -auto_login creates cwallet.sso next to ewallet.p12;
Check that the wallet lists the CA under Trusted Certificates.

orapki wallet create -wallet ./gluesync-wallet -pwd <wallet password> -auto_login
orapki wallet add -wallet ./gluesync-wallet -trusted_cert -cert ca.crt -pwd <wallet password>
orapki wallet display -wallet ./gluesync-wallet

orapki comes with the Oracle Database and the Oracle Client. Without them, you can run the same commands with the oraclepki.jar of the Oracle JDBC driver: java -cp oraclepki.jar oracle.security.pki.textui.OraclePKITextUI wallet create ….

If the listener requires client authentication (SSL_CLIENT_AUTHENTICATION = TRUE), the wallet also needs a user certificate signed by a CA that the server trusts. Follow the Oracle documentation of orapki to add it.

A wallet that has only ewallet.p12 is not an auto-login wallet. Add cwallet.sso to it with:

orapki wallet create -wallet ./gluesync-wallet -auto_login -pwd <wallet password>

Then create tnsnames.ora and ojdbc.properties in the same folder:

tnsnames.ora

GS_ORCL =
  (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCPS)(HOST = oracle.example.com)(PORT = 2484))
    (CONNECT_DATA = (SERVICE_NAME = ORCL))
    (SECURITY = (SSL_SERVER_DN_MATCH = YES)))

ojdbc.properties

oracle.net.wallet_location=(SOURCE=(METHOD=FILE)(METHOD_DATA=(DIRECTORY=${TNS_ADMIN})))

HOST must be reachable from Core Hub. With SSL_SERVER_DN_MATCH = YES, it must also match the certificate of the listener.

Point the paths to the folder that Gluesync reads

The wallet is read by Core Hub, so every path in the files must be a path that Core Hub can open, not a path of your workstation or of the database server.

In ojdbc.properties, keep DIRECTORY=${TNS_ADMIN}. The driver replaces it with Wallet path, so the files stay valid wherever you copy the folder. An absolute path works too, but only if Core Hub sees it: otherwise the connection fails with ORA-17956: Unable to parse the wallet location supplied: Couldn’t find file at <path>;
In tnsnames.ora, an alias may set its own wallet with (SECURITY = (MY_WALLET_DIRECTORY = <path>)). Remove it to use ojdbc.properties, or replace the path with the one that Core Hub sees;
In sqlnet.ora, WALLET_LOCATION and ?/network/admin can stay as they are: Gluesync does not read them.

Copy the folder where Core Hub can read it

Copy the whole folder, with every file of the wallet, and make the files readable by Core Hub.

In the Linux kit, the folder data/core-hub of the installation is mounted in Core Hub as /opt/gluesync/data. Copy the wallet to data/core-hub/oracle-wallet and enter /opt/gluesync/data/oracle-wallet in Wallet path;
In an installation that runs Core Hub directly on Windows, enter the path of the folder on that machine with forward slashes, for example C:/opt/gluesync/data/oracle-wallet.

Configure the connection

In the connection form of the agent, open the advanced connection properties and set:

Use wallet: on;
Instance name: the alias of tnsnames.ora, for example GS_ORCL or <database>_high;
Wallet path: the folder as Core Hub sees it;
LogMiner instance name (LogMiner agent only): the alias of the CDB root, so that the LogMiner connections go through the wallet too. This field is available from agent version 2.2.11.9: earlier versions open the LogMiner connections on the host and the port, outside the wallet.

Enter the user name and the password of the database user in the form as usual. Enable TLS and the trust store of the form are not applied to the connections that go through the alias.

The fields of each agent are described in Oracle LogMiner, Oracle XStream and Oracle Triggers.

Troubleshooting

Error Cause What to do

Error	Cause	What to do
`ORA-17002: I/O error: IO Error PKIX path building failed`	The driver did not find the wallet, or the wallet does not trust the CA of the listener	Check the `oracle.net.wallet_location` line in `ojdbc.properties` and that `cwallet.sso` is in the folder. Check with `orapki wallet display` that the CA is under `Trusted Certificates`. Changing `sqlnet.ora` does not fix it.
`ORA-17956: Unable to parse the wallet location supplied: Couldn’t find file at <path>`	The wallet path in `ojdbc.properties` or in `MY_WALLET_DIRECTORY` does not exist for Core Hub	Use `DIRECTORY=${TNS_ADMIN}`, or the path as Core Hub sees it
`ORA-17957: Unable to initialize the key store`	The folder has no `cwallet.sso`	Create the auto-login wallet with `orapki wallet create -wallet <folder> -auto_login`
`ORA-12263: Failed to access tnsnames.ora in the directory configured as TNS admin`	Wallet path is a path of the host, or the folder is not readable by Core Hub	Use the path as Core Hub sees it and make the files readable
`ORA-01017: invalid username/password; logon denied`	Wrong user name or password in the form	Enter the real credentials: the wallet does not replace them

ORA-17002: I/O error: IO Error PKIX path building failed

The driver did not find the wallet, or the wallet does not trust the CA of the listener

Check the oracle.net.wallet_location line in ojdbc.properties and that cwallet.sso is in the folder. Check with orapki wallet display that the CA is under Trusted Certificates. Changing sqlnet.ora does not fix it.

ORA-17956: Unable to parse the wallet location supplied: Couldn’t find file at <path>

The wallet path in ojdbc.properties or in MY_WALLET_DIRECTORY does not exist for Core Hub

Use DIRECTORY=${TNS_ADMIN}, or the path as Core Hub sees it

ORA-17957: Unable to initialize the key store

The folder has no cwallet.sso

Create the auto-login wallet with orapki wallet create -wallet <folder> -auto_login

ORA-12263: Failed to access tnsnames.ora in the directory configured as TNS admin

Wallet path is a path of the host, or the folder is not readable by Core Hub

Use the path as Core Hub sees it and make the files readable

ORA-01017: invalid username/password; logon denied

Wrong user name or password in the form

Enter the real credentials: the wallet does not replace them