Connect Python Applications Using mTLS

APPLIES TO: Exadata Cloud@Customer only

You can connect Python applications to your Autonomous Database instance using mTLS.

Connecting a Python application with mTLS provides enhanced security for authentication and encryption, and security is enforced using client credentials (by providing a username and password).

The python-oracledb driver's default "Thin mode" connects directly to Oracle Database. The driver can optionally use Oracle Client libraries, "Thick mode", for some additional functionality. The Oracle Client libraries can be from Oracle Instant Client, the full Oracle Client, or from an Oracle Database installation.

Follow these steps to connect your Python application to an Autonomous Database instance using mTLS:

1. Install Python and the python-oracledb Driver
2. Obtain Security Credentials (Oracle Wallet) and Enable Network Connectivity
3. Perform this step if you only want to connect in Thin mode: Run Python Application with python-oracledb Thin Mode (mTLS)
4. Perform this step if you want to connect in Thick mode: Run Python Application with python-oracledb Thick Mode (mTLS)

Install Python and the python-oracledb Driver

To connect to Autonomous Database from your Python application, install Python and the python-oracledb driver.

1. Install Python 3, if it is not already available.

   The version of Python you use depends on your client-side OS and hardware. For example Windows, Linux, macOS, and others.

   Note:

   Oracle recommends you keep up to date with Python and python-oracledb driver releases.
2. Install the python-oracledb driver from PyPI.

   The python-oracledb driver is a Python programming language extension module allowing Python programs to connect to Oracle Database. The python-oracledb driver is the renamed, new major release of the popular cx_Oracle driver.

   Supported python-oracledb driver versions: python-oracledb 1.0 (or later)

   Run the following command to upgrade python:

   python -m pip install oracledb --upgrade

   You should see output similar to the following:

   Collecting oracledb
     Downloading oracledb-1.0.3-cp310-cp310-win_amd64.whl (1.0 MB)
        ---------------------------------------- 1.0/1.0 MB 1.8 MB/s eta 0:00:00
   Collecting cryptography>=3.4
     Downloading cryptography-37.0.4-cp36-abi3-win_amd64.whl (2.4 MB)
        ---------------------------------------- 2.4/2.4 MB 3.5 MB/s eta 0:00:00
   Collecting cffi>=1.12
     Downloading cffi-1.15.1-cp310-cp310-win_amd64.whl (179 kB)
        ---------------------------------------- 179.1/179.1 kB 5.4 MB/s eta 0:00:00
   Collecting pycparser
     Downloading pycparser-2.21-py2.py3-none-any.whl (118 kB)
        ---------------------------------------- 118.7/118.7 kB 7.2 MB/s eta 0:00:00
   Installing collected packages: pycparser, cffi, cryptography, oracledb
   Successfully installed cffi-1.15.1 cryptography-37.0.4 oracledb-1.0.3 pycparser-2.21

   Notes for installing python-oracledb:

   • If you are behind a proxy, use the --proxy option to add a proxy server to the command. For example:

     python -m pip install oracledb --upgrade --proxy=http://proxy.example.com:80

   • In the case where you do not have permission to write to system directories, include the --user option. For example:

     python -m pip install oracledb --upgrade --user

   • If a binary package is not available for your platform, running pip will download the source package instead. The source is compiled and the resulting binary is installed.

   See Installing python-oracledb for additional options and tips.

3. If you want to use the python-oracledb driver in Thick mode, install Oracle Client software.

   By default, python-oracledb runs in Thin mode which connects directly to Oracle Database. Thin mode does not require Oracle Client libraries. However, some additional functionality is available when python-oracledb runs in Thick mode.

   Note:

   See Oracle Database Features Supported by python-oracledb for information on supported features in python-oracledb Thin and Thick modes. Not all of the features shown in this link are available with Autonomous Database.

   Python-oracledb uses Thick mode when you use either the Oracle Instant client libraries or the Oracle Database Client libraries and you call oracledb.init_oracle_client() in your Python code.

   When you install Oracle Client Software, there are differences in required minimum versions for mTLS and TLS connections, as follows:

   • Mutual TLS (mTLS) Connections:

     • If your database is on a remote computer, then download the free Oracle Instant Client “Basic” or “Basic Light” package for your operating system architecture. Use a supported version: Oracle Instant Client: 18.19 (or later), 19.2 (or later), or 21 (base release or later).

     • Alternatively, you can use the Full Oracle Database client libraries when they are available on your system (including Full Oracle Database Client: Oracle Database Client: 18.19 (or later), 19.2 (or later), or 21 (base release or later).

   • TLS Connections: Oracle Call Interface (OCI) clients support TLS authentication if you are using the following client versions:

     • Oracle Instant Client/Oracle Database Client 19.14 (or later) and 21.5 (or later) - all platforms

     • Alternatively, you can use the Full Oracle Database client libraries when they are available on your system, including Full Oracle Database Client 19.14 (or later) and 21.5 (or later).

Obtain Security Credentials (Oracle Wallet) and Enable Network Connectivity

Obtain client security credentials to connect to an Autonomous Database instance.

1. Download a wallet file from the Autonomous Database instance to obtain a zip file that contains the client security credentials and network configuration settings required to access an Autonomous Database instance.

   Obtain the client security credentials (wallet.zip file):

   • ADMIN user: On the Oracle Cloud Infrastructure Console, click Database connection. See Download Client Credentials (Wallets).

   • Other user (non-administrator): Obtain the Oracle Wallet from the administrator for your Autonomous Database instance.

   Note:

   Protect the wallet.zip file and its contents to prevent unauthorized database access.
2. Unzip the client credentials file (wallet.zip).

Run Python Application with python-oracledb Thin Mode (mTLS)

By default, python-oracledb uses Thin mode to connect directly to your Autonomous Database instance.

In Thin mode only two files from the wallet zip are needed:

• tnsnames.ora: Maps net service names used for application connection strings to your database services.

• ewallet.pem: Enables SSL/TLS connections in Thin mode.

To connect in Thin mode:

1. Move tnsnames.ora and ewallet.pem files to a location on your system.
   • Linux
   • Windows

   For example on Linux:

   /opt/OracleCloud/MYDB

   For example on Windows:

   C:\opt\OracleCloud\MYDB

2. In your Python application, set the following connection parameters to connect to an Autonomous Database instance:
   • config_dir: Specifies the directory containing tnsnames.ora.
   • dsn: Use to specify the desired network alias from the tnsnames.ora file.
   • password: Specifies the database user password.
   • user: Specifies the database user.
   • wallet_location: Specifies the directory containing the PEM file (ewallet.pem).
   • wallet_password: Specifies the password for the PEM file (ewallet.pem). You set this password when you download the wallet.zip file.
   • Linux
   • Windows

   For example, on Linux to connect as the ADMIN user using oracledb.connect with the db2024_low network service name (the service name is found in tnsnames.ora):

   connection=oracledb.connect(
        config_dir="/opt/OracleCloud/MYDB",
        user="admin",
        password=password,
        dsn="db2024_low",
        wallet_location="/opt/OracleCloud/MYDB",
        wallet_password=wallet_pw)

   For example, on Windows to connect as the ADMIN user using oracledb.connect with the db2024_low network service name (the service name is found in tnsnames.ora):

   connection=oracledb.connect(
        config_dir=r"C:\opt\OracleCloud\MYDB",
        user="admin",
        password=password,
        dsn="db2024_low",
        wallet_location=r"C:\opt\OracleCloud\MYDB",
        wallet_password=wallet_pw)

   The use of a ‘raw’ string r"..." means that backslashes are treated as directory separators.

   As shown in this example, wallet_location and config_dir are set to the same directory (and the directory contains tnsnames.ora and ewallet.pem). Specifying the same directory for these files is not required.

If you are behind a firewall, you can tunnel TLS/SSL connections through a proxy using HTTPS_PROXY in the connect descriptor or by setting connection attributes. Successful connection depends on specific proxy configurations. Oracle does not recommend using a proxy in a production environment, due to the possible impact on performance.

In Thin mode you can specify a proxy by adding the https_proxy and http_proxy_port parameters.

For example, on Linux:

connection=oracledb.connect(
     config_dir="/opt/OracleCloud/MYDB",
     user="admin",
     password=password,
     dsn="db2024_low",
     wallet_location="/opt/OracleCloud/MYDB",
     wallet_password=wallet_pw,
     https_proxy='myproxy.example.com',
     https_proxy_port=80)

For example, on Windows:

connection=oracledb.connect(
     config_dir=r"C:\opt\OracleCloud\MYDB",
     user="admin",
     password=password,
     dsn="db2024_low",
     wallet_location=r"C:\opt\OracleCloud\MYDB",
     wallet_password=wallet_pw,
     https_proxy='myproxy.example.com',
     https_proxy_port=80)

Run Python Application with python-oracledb Thick Mode (mTLS)

By default, python-oracledb runs in Thin mode which connects directly to Oracle Database. Additional python-oracledb features are available when the driver runs in Thick mode.

Note:

Thick mode requires that the Oracle Client libraries are installed where you run Python. You must also call oracledb.init_oracle_client() in your Python code.

In Thick mode the following three files from the wallet zip file are required:

• tnsnames.ora: Contains the net service names used for application connection strings and maps the strings to your database services.

• sqlnet.ora: Specifies the SQL*Net client side configuration.

• cwallet.sso: Contains the auto-open SSO wallet.

To connect in Thick mode:

1. Place the files tnsnames.ora, sqlnet.ora, and cwallet.sso on your system.

   Use one of two options to place these files on your system:

   • If you are using Instant Client, move the files to a network/admin subdirectory hierarchy under the Instant Client directory. For example depending on the architecture or your client system and where you installed Instant Client, the files should placed be in a directory location such as:

     /home/myuser/instantclient_19_21/network/admin

     or

     /usr/lib/oracle/19.21/client64/lib/network/admin

     For example, on Linux if you are using the full Oracle Client move the files to $ORACLE_HOME/network/admin.

   • Alternatively, move the files to any accessible directory.

     For example, on Linux move the files to the directory /opt/OracleCloud/MYDB and edit sqlnet.ora to change the wallet location directory to the directory containing the cwallet.sso file.

     For example, on Linux edit sqlnet.ora as follows:

     WALLET_LOCATION = (SOURCE = (METHOD=file) (METHOD_DATA = (DIRECTORY="/opt/OracleCloud/MYDB")))
     SSL_SERVER_DN_MATCH=yes

     When the configuration files are not in the default location, your application needs to indicate where they are, either with the config_dir parameter in the call oracledb.init_oracle_client() or by setting the TNS_ADMIN environment variable.

     Note:

     Neither of these settings are needed, and you do not need to edit sqlnet.ora if you put all the configuration files in the network/admin directory.
2. In your Python application set the following initialization and connection parameters to connect to the Autonomous Database instance:
   • config_dir: Specifies the configuration directory when you are putting the configuration files. This is only required when the configuration files are placed in a directory outside of the instant client configuration directory network/admin.
   • dsn: Specifies the desired network alias from the tnsnames.ora file.
   • password: Specifies the database user password.
   • user: Specifies the database user.

   In the first case for placement of the configuration files, connect to the Autonomous Database instance using your database credentials by setting the dsn parameter to the desired network alias from tnsnames.ora.

   For example, to connect as the ADMIN user using oracledb.init_oracle_client and connect with the db2024_low network service name (where the service name is found in tnsnames.ora):

   oracledb.init_oracle_client()
      connection=oracledb.connect(
          user="admin",
          password=password,
          dsn="db2024_low")

   When configuration files are in a directory outside of the instant client configuration directory, set the config_dir parameter when you call oracledb.init_oracle_client.

   • Linux
   • Windows

   For example, on Linux to connect as the ADMIN user using the db2024_low network service name:

   oracledb.init_oracle_client(config_dir="/opt/OracleCloud/MYDB")
      connection=oracledb.connect(
         user="admin",
         password=password,
         dsn="db2024_low")

   For example, on Windows to connect as the ADMIN user using the db2024_low network service name:

   oracledb.init_oracle_client(config_dir=r"C:\opt\OracleCloud\MYDB")
      connection=oracledb.connect(
         user="admin",
         password=password,
         dsn="db2024_low")

   The use of a ‘raw’ string r"..." means that backslashes are treated as directory separators.

If you are behind a firewall, you can tunnel TLS/SSL connections through a proxy using HTTPS_PROXY in the connect descriptor or by setting connection attributes. Successful connection depends on specific proxy configurations. Oracle does not recommend using a proxy in a production environment, due to the possible impact on performance.

In Thick mode you can specify a proxy by editing the sqlnet.ora file and adding a line:

SQLNET.USE_HTTPS_PROXY=on

In addition, edit tnsnames.ora and add an HTTPS_PROXY proxy name and HTTPS_PROXY_PORT port to the connect descriptor address list of any service name you plan to use.

For example:

mydb_high=(description=
(address=(https_proxy=myproxy.example.com)
(https_proxy_port=80)
(protocol=tcps)(port=1522)(host=...)

See Enabling python-oracledb Thick mode for information on Thick mode.

---

Title and Copyright Information

Connect Python Applications Using mTLS

Copyright © 2022, 2023, Oracle and/or its affiliates. 

Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customers that have purchased support have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.