JDBC Thin Connections with a Wallet (mTLS)
Autonomous Database mandates a secure connection that uses Transport Layer Security (TLSv1.2). Depending on the network configuration options, Autonomous Database supports mTLS and TLS authentication.
If you use TLS, instead of mTLS, for your connections using JDBC Thin Driver with JDK8u162 or higher, a wallet is not required. TLS connections are enabled for the following network configurations:
-
Private endpoint access only: network configuration with a private endpoint
-
Secure access from allowed IPs and VCNs only: configuration with an Access Control List (ACL)
If your Autonomous Database is on a public endpoint without any ACL, you can add
0.0.0.0/0
as your CIDR ACL and enable TLS authentication. Adding0.0.0.0/0
as your CIDR ACL is identical to having your Autonomous Database on public endpoint with no ACL.
See About TLS Authentication for more information.
- JDBC Thin Driver Connection Prerequisites Connections with Wallets (mTLS)
Applications that use JDBC Thin driver support TLS and mutual TLS (mTLS) authentication. Using mTLS authentication requires that you supply Oracle database credentials including the Oracle wallets or Java KeyStore (JKS) files when connecting to the database. - Using a JDBC URL Connection String with JDBC Thin Driver and Wallets
The connection string is found in the filetnsnames.ora
which is part of the client credentials download. Thetnsnames.ora
file contains the predefined service names. Each service has its own TNS alias and connection string. - Using a JDBC Connection with 18.3 JDBC Driver
Applications that use JDBC Thin driver can connect to Autonomous Databases using either Oracle Wallets or Java KeyStore (JKS). - Connecting Using JDBC Thin Driver 12.2 or Older
If you are using the JDBC driver 12.2.0.2 or older, set the Java properties prior to starting the application. Usually you set the properties in the application's startup script. - JDBC Thin 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, you need to use the JDBC Thin Client 18.1 or higher which enables connections through HTTP proxies.
Parent topic: Connect with JDBC Thin Driver
JDBC Thin Driver Connection Prerequisites Connections with Wallets (mTLS)
Applications that use JDBC Thin driver support TLS and mutual TLS (mTLS) authentication. Using mTLS authentication requires that you supply Oracle database credentials including the Oracle wallets or Java KeyStore (JKS) files when connecting to the database.
Perform the following steps before connecting to the database:
Parent topic: JDBC Thin Connections with a Wallet (mTLS)
Using a JDBC URL Connection String with JDBC Thin Driver and Wallets
The
connection string is found in the file tnsnames.ora
which is part of
the client credentials download. The tnsnames.ora
file contains the
predefined service names. Each service has its own TNS alias and connection
string.
dbname_high
as the TNS alias and a
connection string in tnsnames.ora
follows:dbname_high= (description=
(address=(protocol=tcps)(port=1522)(host=adb.example.oraclecloud.com))
(connect_data=(service_name=dbname_high.oraclecloud.com))(security=(ssl_server_dn_match=yes)))
Set the location of tnsnames.ora
with the property
TNS_ADMIN
in one of the following ways:
- As part of the connection string (only with the 18.3 or newer JDBC driver)
- As a system property,
-Doracle.net.tns_admin
- As a connection property
(
OracleConnection.CONNECTION_PROPERTY_TNS_ADMIN
)
Using the 18.3 JDBC driver, the connection string includes the TNS alias and
the TNS_ADMIN
connection property.
Sample connection string using 18.3 JDBC driver (Linux):
DB_URL="jdbc:oracle:thin:@dbname_high?TNS_ADMIN=/Users/test/wallet_dbname"
Sample connection string using 18.3 JDBC driver (Windows):
DB_URL="jdbc:oracle:thin:@dbname_high?TNS_ADMIN=C:\\Users\\test\\wallet_dbname"
The TNS_ADMIN
connection property specifies the following:
- The location of
tnsnames.ora
. - The location of Oracle Wallet (
ewallet.sso
,ewallet.p12
) or Java KeyStore (JKS) files (truststore.jks
,keystore.jks
). - The location of
ojdbc.properties
. This file contains the connection properties required to use Oracle Wallets or Java KeyStore (JKS).
If you are using 12.2.0.1 or older JDBC drivers, then the connection string contains only the TNS alias. To connect using older JDBC drivers:
- Set the location of the
tnsnames.ora
, either as a system property with-Doracle.net.tns_admin
or as a connection property (OracleConnection.CONNECTION_PROPERTY_TNS_ADMIN
). - Set the wallet or JKS related connection properties in addition to
TNS_ADMIN
.
For example, in this case you set the TNS alias in the
DB_URL
without the TNS_ADMIN
part as:
DB_URL=”jdbc:oracle:thin:@dbname_high”
See Database Service Names for Autonomous Database for more details.
Parent topic: JDBC Thin Connections with a Wallet (mTLS)
Using a JDBC Connection with 18.3 JDBC Driver
Applications that use JDBC Thin driver can connect to Autonomous Databases using either Oracle Wallets or Java KeyStore (JKS).
Using Oracle Wallet
To use Java and the 18.3 JDBC Thin Driver to connect to Autonomous Database with the Oracle Wallet, do the following:
-
Make sure that the prerequisites are met: See JDBC Thin Driver Connection Prerequisites Connections with Wallets (mTLS) for more information.
-
Verify the connection: You can either use a Java program, a servlet, or IDEs to verify the connection to the database. A simple test is to download DataSourceSample.java or UCPSample.java from JDBC code samples and update the connection URL to have the required TNS alias and pass
TNS_ADMIN
, providing the path fortnsnames.ora
and the wallet files. Also, in the sample source code update the database username and password. For example:DB_URL="jdbc:oracle:thin:@dbname_high?TNS_ADMIN=/Users/test/wallet_dbname"
Note
If you are using Microsoft Active Directory with a database, then in the sample source code update the username with the Active Directory username and update the password with the Active Directory user password. See Use Microsoft Active Directory with Autonomous Database for more information. -
Set the wallet location: The properties file
ojdbc.properties
is pre-loaded with the wallet related connection property.oracle.net.wallet_location=(SOURCE=(METHOD=FILE)(METHOD_DATA=(DIRECTORY=${TNS_ADMIN})))
Note
You do not modify the fileojdbc.properties
. The value ofTNS_ADMIN
determines the wallet location. -
Compile and Run: Compile and run the sample to get a successful connection. Make sure you have
oraclepki.jar
,osdt_core.jar
, andosdt_cert.jar
, in theclasspath
. For example:java –classpath ./lib/ojdbc8.jar:./lib/ucp.jar:./lib/oraclepki.jar:./lib/osdt_core.jar:./lib/osdt_cert.jar:. UCPSample
The auto-login wallet part of Autonomous Database downloaded client credentials zip file removes the need for your application to use username/password authentication.
Using Java KeyStore
To use Java and the 18.3 JDBC Thin Driver to connect to Autonomous Database with Java KeyStore (JKS), do the following:
-
Make sure that the prerequisites are met: See JDBC Thin Driver Connection Prerequisites Connections with Wallets (mTLS) for more information.
-
Ready the database details: You can either use a Java program, a servlet, or IDEs to check the connection to your database. A simple test is to download DataSourceSample.java or UCPSample.java from JDBC code samples. In this sample, use the connection URL as shown. Note that the connection
DB_URL
contains the TNS alias, for example,dbname_high
present intnsnames.ora
. You can provide the path fortnsnames.ora
file throughTNS_ADMIN
property as shown in the URL. Make sure to use the database username and password related to your database.DB_URL="jdbc:oracle:thin:@dbname_high?TNS_ADMIN=/Users/test/wallet_dbname"
Note
If you are using Microsoft Active Directory with Autonomous Database, then make sure to change the sample source code to use the Active Directory username and the Active Directory user password. See Use Microsoft Active Directory with Autonomous Database for more information. -
Set JKS related connection properties: Add the JKS related connection properties to
ojdbc.properties
file. The keyStore and truststore password are the password specified when you downloading the client credentials.zip
file.To use SSL connectivity instead of Oracle Wallet, specify the keystore and truststore files and their respective password in the
ojdbc.properties
file as follows:# Properties for using Java KeyStore (JKS) oracle.net.ssl_server_dn_match=true javax.net.ssl.trustStore==${TNS_ADMIN}/truststore.jks javax.net.ssl.trustStorePassword=password javax.net.ssl.keyStore==${TNS_ADMIN}/keystore.jks javax.net.ssl.keyStorePassword=password
Note
Make sure to comment the wallet related property inojdbc.properties
. For example:# Property for using Oracle Wallets # oracle.net.wallet_location=(SOURCE=(METHOD=FILE)(METHOD_DATA=(DIRECTORY=${TNS_ADMIN})))
-
Compile and Run: Compile and run the sample to get a successful connection. For example:
java –classpath ./lib/ojdbc8.jar:./lib/ucp.jar UCPSample
Parent topic: JDBC Thin Connections with a Wallet (mTLS)
Connecting Using JDBC Thin Driver 12.2 or Older
If you are using the JDBC driver 12.2.0.2 or older, set the Java properties prior to starting the application. Usually you set the properties in the application's startup script.
If you are not able to use the latest 18.3 JDBC drivers, then you can
connect to Autonomous Database
using 12.2.0.2 or other older JDBC drivers. The 12.2 or older JDBC drivers do not
support the ojdbc.properties
file. With older JDBC driver
versions, you need to pass wallets or JKS related properties either as system
properties or as connection properties to establish a connection.
Using Oracle Wallet
To use Java and the 12.2 or older JDBC Drivers to connect to Autonomous Database with the Oracle Wallet, do the following:
-
Make sure that the prerequisites are met: See JDBC Thin Driver Connection Prerequisites Connections with Wallets (mTLS) for more information.
-
Verify the connection: You can either use a Java program, a servlet, or IDEs to verify the connection to the database. A simple test is to download DataSourceSample.java or UCPSample.java from JDBC code samples and update the connection URL to have the required TNS alias. Also, update the sample source code to use the database username and password. For example:
DB_URL="jdbc:oracle:thin:@dbname_high”
Note
If you are using Microsoft Active Directory with Autonomous Database, then update the sample source code to use the Active Directory username and Active Directory user password. See Use Microsoft Active Directory with Autonomous Database for more information. -
Set the wallet location: Add the
OraclePKIProvider
at the end of the provider list in the filejava.security
(this file is part of your JRE install located at$JRE_HOME/jre/lib/security/java.security
) which typically looks like:security.provider.14=oracle.security.pki.OraclePKIProvider
-
Compile and Run: Compile and run the sample to get a successful connection. Make sure to have
oraclepki.jar
,osdt_core.jar
, andosdt_cert.jar
, in theclasspath
. Also, you need to pass the connection properties. Update the properties with the location wheretnsnames.ora
and wallet files are located.java –classpath ./lib/ojdbc8.jar:./lib/ucp.jar:./lib/oraclepki.jar:./lib/osdt_core.jar:./lib/osdt_cert.jar:. -Doracle.net.tns_admin=/users/test/wallet_dbname -Doracle.net.ssl_server_dn_match=true -Doracle.net.ssl_version=1.2 (Not required for 12.2) -Doracle.net.wallet_location= “(SOURCE=(METHOD=FILE)(METHOD_DATA=(DIRECTORY=/users/test/wallet_dbname)))” UCPSample
These are Windows system examples. Add a
\
continuation character if you are setting
–D
properties on multiple lines on UNIX ( Linux or a
Mac).
Using Java KeyStore
To use Java and the 12.2 or older JDBC Thin Drivers to connect to Autonomous Database with Java KeyStore (JKS), do the following:
-
Make sure that the prerequisites are met: See JDBC Thin Driver Connection Prerequisites Connections with Wallets (mTLS) for more information.
-
Verify the connection: You can either use a Java program, a servlet, or IDEs to verify the connection to the database. A simple test is to download DataSourceSample.java or UCPSample.java from JDBC code samples and update the connection URL to have the required TNS alias and pass
TNS_ADMIN
, providing the path fortnsnames.ora
and update the connection URL to have the required TNS alias. Also, in the sample source code update the database username and password. For example:DB_URL="jdbc:oracle:thin:@dbname_high”
Note
If you are using Microsoft Active Directory with Autonomous Database, then update the sample source code to use the Active Directory username and Active Directory user password. See Use Microsoft Active Directory with Autonomous Database for more information. -
Compile and Run: Compile and run the sample to get a successful connection. You need to pass the connection properties as shown. Update the properties with the location where
tnsnames.ora
and JKS files are placed. If you want to pass these connection properties programmatically then refer to DataSourceForJKS.java. For example:java -Doracle.net.tns_admin=/users/test/wallet_dbname -Djavax.net.ssl.trustStore=truststore.jks -Djavax.net.ssl.trustStorePassword=********** -Djavax.net.ssl.keyStore=keystore.jks -Djavax.net.ssl.keyStorePassword=************ -Doracle.net.ssl_server_dn_match=true -Doracle.net.ssl_version=1.2 // Not required for 12.2
Parent topic: JDBC Thin Connections with a Wallet (mTLS)
JDBC Thin 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, you need to use the JDBC Thin Client 18.1 or higher which enables connections through HTTP proxies.
To connect to Autonomous Database through an HTTPS proxy, open and update your
tnsnames.ora
file. Add the HTTP proxy
hostname(https_proxy) and port (https_proxy_port) to the connection string.
Replace the values with your HTTPS proxy information. For example:
-
Add the HTTP proxy hostname and port to the connection definitions in
tnsnames.ora
. You need to add the https_proxy and https_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:
db2022adb_high =
(description=
(address=
(https_proxy=proxyhostname)(https_proxy_port=80)(protocol=tcps)(port=1522)(host=adb.example.oraclecloud.com)
)
(connect_data=(service_name=db2022adb_high.adb.oraclecloud.com)
)
(security=security=(ssl_server_dn_match=yes)
)
)
-
JDBC Thin client versions earlier than 18.1 do not support connections through HTTP proxy.
-
Successful connection depends on specific proxy configurations and the performance of data transfers would depend on proxy capacity. Oracle does not recommend using this feature in Production environments where performance is critical.
-
Configuring
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 all cases, contact your network administrator to open outbound connections to hosts in the
oraclecloud.com
domain using the relevant port without going through an HTTP proxy.
Parent topic: JDBC Thin Connections with a Wallet (mTLS)