Prepare for Oracle Call Interface, ODBC, and JDBC OCI Connections with Wallets (mTLS)
Preparing for any type of Oracle Call Interface (OCI) connection with mTLS authentication requires the installation of client software, downloading client credentials, and configuring certain files and environment variables.
This topic covers the steps to prepare an application to connect using mTLS authentication with a wallet that you download from an Autonomous Database instance. See Prepare for Oracle Call Interface, ODBC, and JDBC OCI Connections Using TLS Authentication for information on the steps to prepare for TLS authentication with these connection types.
New Oracle Client Installation
The following steps assume Oracle client software has not
already been installed on the client computer. If Oracle client software has already been installed
and there are working copies of sqlnet.ora
and
tnsnames.ora
, see Updating an Existing Oracle Client
Installation.
Before making an Oracle Call Interface (OCI), ODBC, or JDBC OCI connection, do the following:
-
Install Oracle Client software on your computer.
-
Oracle Instant Client/Oracle Database Client: 18.19 (or later), 19.2 (or later), or 21 (base release or later). The Instant Client contains the minimal software needed to make an Oracle Call Interface connection.
-
-
Download client credentials and store the file in a secure folder on your client computer. See Download Client Credentials (Wallets).
-
Unzip/uncompress the credentials file into a secure folder on your client computer.
-
Edit the
sqlnet.ora
file in the folder where you unzip the credentials file, replacing"?/network/admin"
with the name of the folder containing the client credentials.For example, edit
sqlnet.ora
as follows:WALLET_LOCATION = (SOURCE = (METHOD = file) (METHOD_DATA = (DIRECTORY="?/network/admin"))) SSL_SERVER_DN_MATCH=yes
The changed value on UNIX/Linux is:
WALLET_LOCATION = (SOURCE = (METHOD = file) (METHOD_DATA = (DIRECTORY="/home/adb_credentials"))) SSL_SERVER_DN_MATCH=yes
The changed value for Windows is:
WALLET_LOCATION = (SOURCE = (METHOD = file) (METHOD_DATA = (DIRECTORY="D:\\myapp\\adb_credentials"))) SSL_SERVER_DN_MATCH=yes
-
Create the
TNS_ADMIN
environment variable and set it to the location of the credentials file.Use this environment variable to change the directory path of Oracle Net Services configuration files from the default location of
ORACLE_HOME\network\admin
to the location of the secure folder containing the credentials file you saved in Step 2. Set theTNS_ADMIN
environment variable to the directory where the unzipped credentials files are, not to the credentials file itself.For example, on UNIX/Linux set
TNS_ADMIN
to the full path of the directory where you unzipped the client credentials:export TNS_ADMIN=/home/adb_credentials
For example on Windows:
set TNS_ADMIN=d:\myapp\adb_credentials
Connections with an HTTP Proxy
If the client is behind a firewall and your network configuration requires an HTTP
proxy to connect to the internet, then perform the following steps to update the
sqlnet.ora
and tnsnames.ora
files.
Connections through an HTTP proxy are only available with Oracle Client software
version 12.2.0.1 or later.
To avoid manual updates in
sqlnet.ora
and tnsnames.ora
files, you
can use SQLcl and specify the HTTP proxy on the command line. See Connect Oracle SQLcl Cloud with a Wallet (mTLS) for more information.
-
Add the following line to the
sqlnet.ora
file to enable connections through an HTTP proxy:SQLNET.USE_HTTPS_PROXY=on
-
Add the HTTP proxy hostname and port to the connection definitions in
tnsnames.ora
. You need to add thehttps_proxy
andhttps_proxy_port
parameters in the address section of connection definitions. For example, the following sets the HTTP proxy toproxyhostname
and the HTTP proxy port to80
; replace these values with your HTTP proxy information:ADB1_high = (description= (address= (https_proxy=proxyhostname)(https_proxy_port=80)(protocol=tcps)(port=1522)(host=adb.example.oraclecloud.com) ) (connect_data=(service_name=adb1_high.adb.oraclecloud.com) ) (security=(ssl_server_dn_match=yes)) ) )
Configuring
sqlnet.ora
and tnsnames.ora
for the HTTP proxy may not be enough
depending on your organization's network configuration and security policies. For example, some
networks require a username
and password
for the HTTP proxy. In
such cases contact your network administrator to open outbound connections to hosts in the
oraclecloud.com domain using port 1522 without going through an HTTP proxy.
For
more information on SQLNET.USE_HTTPS_PROXY
, see Net Services
Reference.
For information on HTTPS_PROXY
and
HTTPS_PROXY_PORT
, see Protocol Address
Section.
Updating an Existing Oracle Client Installation
If you have an existing Oracle Client installation,
you already have sqlnet.ora
and tnsnames.ora
files and the
TNS_ADMIN
environment variable. In this case, do the following:
-
Update your
sqlnet.ora
file by adding the following:WALLET_LOCATION = (SOURCE = (METHOD = file) (METHOD_DATA = (DIRECTORY="/home/adb_credentials")))
-
Copy the entries in the
tnsnames.ora
file provided in the Autonomous Database wallet to your existingtnsnames.ora
file.