Connecting to an Autonomous Database on Shared Exadata Infrastructure

This topic describes the following actions related to connecting client applications to an Autonomous Database:

  • Obtaining the credentials and information (wallet) you need to create a connection (applies to both shared Exadata infrastructure and dedicated Exadata infrastructure)
  • Rotating the keys and credentials (wallet) needed for a connection (applies to shared Exadata infrastructure only)
  • Obtaining access URLs for Oracle Application Express (APEX) and Oracle Database Actions
Tip

For more information on connecting a client to an Autonomous Database on dedicated Exadata infrastructure, see Connecting to Autonomous Database.

About Connecting to Autonomous Databases

Applications and tools connect to Autonomous Databases by using Oracle Net Services (also known as SQL*Net). SQL*Net supports a variety of connection types to Autonomous Databases, including Oracle Call Interface (OCI), ODBC drivers, JDBC OC, and JDBC Thin Driver.

To support connections of any type, you must download the client security credentials and network configuration settings required to access your database. You must also supply the applicable TNS names or connection strings for a connection, depending on the client application or tool, type of connection, and service level. You can view or copy the TNS names and connection strings in the DB Connection dialog for your Autonomous Database. For detailed information about the TNS names, see Predefined Database Service Names for Autonomous Transaction Processing and Predefined Database Service Names for Autonomous Data Warehouse.

Secure Connections to Autonomous Database

Connections to Autonomous Database are made either over the public Internet, optionally with an access control list (ACL) defined, or using a private endpoint inside a virtual cloud network (VCN) in your tenancy. When you specify a private endpoint configuration, this only allows traffic from the virtual cloud network you specify and blocks access to the database from all public IPs or VCNs. Configuring a private endpoint allows you to keep all traffic to and from your database off of the public internet.

Many applications provide support for more than one connection type, but each type of connection to Autonomous Database uses certificate authentication and TCPS (Secure TCP) database connection using standard TLS 1.2. This ensures that there is no unauthorized access to the Autonomous Database and that communications between the client and server are fully encrypted and cannot be intercepted or altered.

Autonomous Database by default supports Mutual TLS (mTLS) connections. You have the option to configure an Autonomous Database instance to support both mTLS and TLS connections.

About Mutual TLS (mTLS) Authentication

Using Mutual Transport Layer Security (mTLS), clients connect through a TCPS (Secure TCP) database connection using standard TLS 1.2 with a trusted client certificate authority (CA) certificate. With mutual authentication both the client application and Autonomous Database authenticate each other. Autonomous Database uses mTLS authentication by default.

Mutual TLS authentication requires that the client downloads or obtains a trusted client CA certificate for connecting to an Autonomous Database instance. Autonomous Database then uses the certificate to authenticate the client. This provides increased security and specifies the clients that can communicate with an Autonomous Database instance.

Certification authentication with Mutual TLS uses an encrypted key stored in a wallet on both the client (where the application is running) and the server (where your database service on the Autonomous Database is running). The key on the client must match the key on the server to make a connection. A wallet contains a collection of files, including the key and other information needed to connect to your Autonomous Database instance. All communications between the client and the server are encrypted.

To secure the connection to your Autonomous Database instance a service administrator downloads the client credentials (wallet files) from Autonomous Database. If you are not an Autonomous Database service administrator, your administrator provides you with the client credentials. See To download a wallet for an Autonomous Database on shared Exadata infrastructure for information.

The following figure shows client secure connections to Oracle Autonomous Database over the public Internet using Mutual TLS connections. If you configure your database to use private endpoints, then the public internet is not used and the connection uses a private endpoint inside a Virtual Cloud Network (VCN) in your tenancy.


Shows the security outline. This includes the following connection components (options) on the Client Computer: ODBC, JDBC OCI, Oracle Call Interface (OCI), JDBC “Thin”, and Wallet/Keystore. The connection is over TCP/IP encrypted using mutual TLS over public Internet (other options are available with TLS or private endpoint are not shown). On the database, the downloaded Wallet/Keystore secures the connection to your Oracle Autonomous Database.

About TLS Authentication

Using Transport Layer Security (TLS), clients connect through a TCPS (Secure TCP) database connection using standard TLS 1.2 with a root certificate authority (CA) certificate.

When you connect with TLS authentication using JDBC Thin Driver clients, including Oracle SQL Developer and Oracle SQLcl, you do not need to download a wallet to secure the connection to your Autonomous Database instance. TLS authentication enables the client to verify the identity of the Autonomous Database service to provide secure communication.

Depending on the type of client, a TLS connection has the following support with Autonomous Database:

  • If the client is connecting with JDBC Thin using TLS authentication, the client can connect without providing a wallet.
  • If the client is connecting with managed ODP.NET or ODP.NET Core versions 19.13 or 21.4 (or above) using TLS authentication, the client can connect without providing a wallet.
  • If the client is connecting with SQLNet and Oracle Call Interface (OCI), and for certain other connection types with TLS authentication, the clients must provide the CA certificate in a wallet.
Note

There are network access prerequisites for TLS connections. See Network Access Prerequisites for TLS Connections for more information.

Connecting to an Autonomous Database

You can connect to an Autonomous Database that uses shared Exadata infrastructure from a VCN with either a public or private endpoint.

To connect to Autonomous Databases that use a public endpoint from a VCN, the VCN must be configured with one of the following gateways:

Make sure to configure the subnet's route table with a rule that sends the desired traffic to the specific gateway. Also configure the subnet's security lists to allow the desired traffic.

You can also connect to your database from private IP addresses in your on-premises network by using transit routing with an Oracle Cloud Infrastructure VCN. This allows traffic to move directly from your on-premises network to your Autonomous Database without going over the internet. See Private Access to Oracle Services for more information on this method of access.

To connect to Autonomous Databases that use a private endpoint from a VCN, you must configure a security rule within one of the database's network security groups (NSGs) to allow access to the Autonomous Database endpoint. For more information on private endpoint network configuration, see Networking Prerequisites Needed for Private Endpoint.

About Downloading Client Credentials

The client credentials .zip that you download contains the following files:

  • tnsnames.ora and sqlnet.ora: Network configuration files storing connect descriptors and SQL*Net client side configuration.
  • cwallet.sso and ewallet.p12: Auto-open SSO wallet and PKCS12 file. The PKCS12 file is protected by the wallet password provided while downloading the wallet.
  • keystore.jks and truststore.jks: Java keystore and truststore files. They are protected by the wallet password provided while downloading the wallet.
  • ojdbc.properties: Contains the wallet related connection property required for JDBC connection. This should be in the same path as tnsnames.ora.
  • README: Contains wallet expiration information and links for Autonomous Database tools and resources.

For Autonomous Databases on shared Exadata infrastructure, you have the choice of downloading an instance wallet file or a regional wallet file. The instance wallet contains only credentials and keys for a single Autonomous Database. The regional wallet contains credentials and keys for all Autonomous Databases in a specified region. For security purposes, Oracle recommends that regional wallets be used only by database administrators, and that instance wallets be supplied to other users whenever possible.

For Autonomous Databases on dedicated Exadata infrastructure, the wallet file contains only credentials and keys for a single Autonomous Database.

Notes for Wallet Files and the Wallet Password

  • To invalidate database client certification keys associated with a wallet, see To rotate the wallet of an Autonomous Database on shared Exadata infrastructure.

  • Wallet files, along with the Database user ID and password provide access to data in your database. Store wallet files in a secure location. Share wallet files only with authorized users. If wallet files are transmitted in a way that might be accessed by unauthorized users (for example, over public email), transmit the wallet password separately and securely.

  • For better security, Oracle recommends using restricted permissions on wallet files. This means setting the file permissions to 600 on Linux/Unix. Similar restrictions can be achieved on Windows by letting the file owner have Read and Write permissions while all other users have no permissions.

  • Autonomous Database uses strong password complexity rules for all users based on Oracle Cloud security standards. For more information on the password complexity rules see Create Users on Autonomous Database - Connecting with a Client Tool.

  • The README file that contains wallet expiration information is not available in wallet zip files that were downloaded before April 2020.

  • Starting six weeks before the wallet expiration date Autonomous Database sends notification emails each week, indicating the wallet expiration date. These emails provide notice before your wallet expires that you need to download a new wallet.

    You can also use the WalletExpirationWarning event to be notified when a wallet is due to expire. See About Events Based Notification and Automation on Autonomous Database for more information.

Wallet README File

The wallet README file contains the wallet expiration information and details for Autonomous Database tools and resources.

The wallet expiration information at the top of the README file shows the following information:

  • The date when the wallet was downloaded.
  • The date when the wallet SSL certificate provided in the wallet expires. If your wallet is nearing expiration or is expired, then download a new wallet or obtain a new wallet from your Autonomous Database administrator. If you do not download a new wallet before the expiration date, you will no longer be able to connect to your database.

The Autonomous Database tools and resources area provides the following information:

Tool or Resource Description
Database Actions

Load, explore, transform, model, and catalog your data. Use an SQL worksheet, build REST interfaces and low-code apps, manage users and connections, build and apply machine learning models.

Access Link: provides the link to use Database Actions. See Connect with Built-in Oracle Database Actions for more information.

Graph Studio

Oracle Graph Studio lets you create scalable property graph databases. Graph Studio automates the creation of graph models and in-memory graphs from database tables. It includes notebooks and developer APIs that allow you to execute graph queries using PGQL (an SQL-like graph query language) and over 50 built-in graph algorithms. Graph Studio also offers dozens of visualization, including native graph visualization.

Access Link provides the link to use Graph Studio. See About Oracle Graph Studio with Autonomous Database for more information.

Oracle Application Express

Oracle Application Express (APEX) is a low-code development platform that enables you to build scalable, secure enterprise apps that can be deployed anywhere.

Access Link: provides the link to use Oracle Application Express. See Access Oracle Application Express Administration Services for more information.

Oracle Machine Learning User Management

Create new Oracle Machine Learning user accounts and manage the credentials for existing Oracle Machine Learning users.

Access Link: provides the link to use Oracle Machine Learning User Management. See Create and Update User Accounts for Oracle Machine Learning Notebooks for more information.

Oracle Machine Learning User Notebooks

Oracle Machine Learning notebooks provide easy access to Oracle's parallelized, scalable in-database implementations of a library of Oracle Advanced Analytics' machine learning algorithms (classification, regression, anomaly detection, clustering, associations, attribute importance, feature extraction, times series, etc.), SQL, PL/SQL and Oracle's statistical and analytical SQL functions.

Access Link: provides the link to use Oracle Machine Learning User Notebooks. See Work with Oracle Machine Learning Notebooks for Data Access, Analysis, and Discovery for more information.

Service Console

Monitor real-time and historical information about the utilization of the service, perform administrative operations or access to developer tools.

Access Link: provides the link to access the Service Console. See Open Service Console to Monitor Activity and Utilization for more information.

SODA Drivers

Simple Oracle Document Access (SODA) is a set of APIs that let you work with JSON documents managed by the Oracle Database without needing to use SQL. SODA drivers are available for REST, Java, Node.js, Python, PL/SQL, and C.

Access Link: provides the link to download the SODA drivers. See Work with Simple Oracle Document Access (SODA) in Autonomous Database for more information.

Notes for wallet README file:

  • If you rename your Autonomous Database instance, the tools links change and the old links no longer work. To obtain valid tools links you must download a new Wallet zip file with an updated README file. The SODA drivers link is a resource link and this link does not change when you rename an instance.
  • The README in a regional wallet does not contain the Autonomous Database tools and resources links.
Important

Wallet files, along with the database user ID and password, provide access to data in your Autonomous Database. Store wallet files in a secure location. Share wallet files only with authorized users. If wallet files are transmitted in a way that might be accessed by unauthorized users (for example, over public email), transmit the wallet password separately and securely.

Wallet Password Requirements

The wallet password you provide when you download the wallet protects the downloaded Client Credentials wallet. For commercial regions, the Wallet password complexity for the password you supply in these steps requires the following:

  • Minimum of 8 characters
  • Minimum of 1 letter
  • Minimum of 1 numeric character or 1 special character

For U.S. government regions, the Wallet password complexity for the password you supply in these steps requires the following:

  • Minimum of 15 characters
  • Minimum of 1 lowercase letter
  • Minimum of 1 uppercase letter
  • Minimum of 1 numeric character
  • Minimum 1 special character

About Rotating Your Autonomous Database Wallet

For Autonomous Databases on shared Exadata infrastructure, you can rotate an instance or regional wallet for security purposes. When your wallet rotation is complete, you will have a new set of certificate keys and credentials, and the old wallet's keys and credentials will be invalid. Rotating an instance wallet does not invalidate the regional wallet that covers the same database instance. Rotating a regional wallet affects all databases in the specified region. User session termination begins after wallet rotation completes, however this process does not happen immediately.

Important

If you are rotating a wallet to address a security breach and need to reestablish all database connections immediately using the keys and credentials of your newly rotated wallet, stop and restart the database instance.

Before You Begin

The Autonomous Database is preconfigured to support Oracle Net Services (a TNS listener is installed and configured to use secure TCPS and client credentials.) The client computer must be prepared to use Oracle Net Services to connect to the Autonomous Database. Preparing your client includes downloading the client credentials. See the following links for steps you might have to perform before you access the client credentials and connection information for your Autonomous Database:

Using the Oracle Cloud Infrastructure Console

For instructions on downloading a wallet for Autonomous Database on dedicated Exadata infrastructure, see Download Client Credentials in the Autonomous Database on Dedicated Exadata Infrastructure section of the documentation.

To download a wallet for an Autonomous Database on shared Exadata infrastructure
  1. Open the navigation menu. Click Oracle Database. Under Autonomous Database, click Autonomous Data Warehouse, Autonomous JSON Database, or Autonomous Transaction Processing.
  2. Choose your Compartment.
  3. In the list of Autonomous Databases, click on the display name of the database you are interested in.
  4. Click DB Connection.
  5. In the Download Client Credentials (Wallet) section, select the Wallet Type. You can choose to download an instance wallet  or a regional wallet .
  6. To obtain the client credentials, click Download Wallet.

    You will be prompted to provide a password to encrypt the keys inside the wallet. The password must be at least 8 characters long and must include at least 1 letter and either 1 numeric character or 1 special character.

    Save the client credentials zip file to a secure location. See About Downloading Client Credentials for information about the files included in the download.

  7. Take note of or copy the TNS names or connection strings you need for your connection. See About Connecting to Autonomous Databases for information about making connections.
To view TNS names and connection strings for an Autonomous Database on shared Exadata infrastructure

From the Database Connection page on the Oracle Cloud Infrastructure Console you can view Autonomous Database TNS names and connection strings.

Note

See Update your Autonomous Database Instance to Allow both TLS and mTLS Authentication for information on allowing TLS connections.

Perform the following steps as necessary:

  • From the Oracle Cloud Infrastructure Console left navigation menu, click Oracle Database and then, depending on your workload click one of the following: Autonomous Data Warehouse, Autonomous JSON Database, or Autonomous Transaction Processing.
  • On the Autonomous Databases page select your Autonomous Database from the links under the Display Name column.

To view the TNS names and connection strings, do the following:

  1. On the Autonomous Database details page, click DB Connection.

    By default this shows the Mutual TLS connection information in a table with the TNS names and connection strings for the Autonomous Database instance.

  2. When both Mutual TLS (mTLS) and TLS connections are allowed, under TLS Authentication select TLS to view the TNS names and connection strings for connections with TLS authentication.

    The TNS names are the same for mTLS and TLS authentication. The connection strings differ for mTLS and TLS connections, with different port definitions. Mutual TLS (mTLS) connections use port 1522. TLS connections use port 1521.

    In the Connection String column, click Show to display the full value of a connection string or click Copy to copy a connection string.

To rotate the wallet of an Autonomous Database on shared Exadata infrastructure
  1. Open the navigation menu. Click Oracle Database. Under Autonomous Database, click Autonomous Data Warehouse, Autonomous JSON Database, or Autonomous Transaction Processing.
  2. Choose your Compartment.
  3. In the list of Autonomous Databases, click on the display name of the database you are interested in.
  4. Click DB Connection.
  5. In the Download Client Credentials (Wallet) section, select the Wallet Type. You can choose to rotate an instance wallet  or a regional wallet .
  6. Click Rotate Wallet. A confirmation dialog will prompt you to enter the database name to confirm the rotation.
  7. Enter the name of the database, then click Rotate Wallet.

    The rotation takes a few minutes to complete.

Using the API

Use the GenerateAutonomousDatabaseWallet API operation to download the client credentials for your Autonomous Database.

Use the UpdateAutonomousDatabaseWalletDetails API operation to rotate the wallet for your Autonomous Database.

Use the AutonomousDatabase API operation to get the access URLs for Application Express (APEX) and SQL Developer Web.

For information about using the API and signing requests, see REST APIs and Security Credentials. For information about SDKs, see Software Development Kits and Command Line Interface.