Connect Python Applications with a Wallet (mTLS)

You can connect Python applications to your Autonomous Database instance with a wallet.

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

The Python python-oracledb driver's default "Thin mode" connects directly to Oracle Database. It 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 an Oracle Database installation.

Follow these steps to connect your Python application to an Autonomous Database instance using a wallet (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 with a Wallet (mTLS)
  4. Perform this step if you want to connect in Thick mode: Run Python Application with python-oracledb Thick Mode with a Wallet (mTLS)

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 your Autonomous Database.

    Obtain the client security credentials wallet.zip file as follows:

    Note:

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

Run Python Application with python-oracledb Thin Mode with a Wallet (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, do the following:

  1. Move tnsnames.ora and ewallet.pem files to a location on your system such as /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.
    • wallet_location: Specifies the directory containing the PEM file (ewallet.pem).
    • password: Specifies the database user password.
    • user: Specifies the database user.
    • wallet_password: Specifies the password for the PEM file (ewallet.pem). You set this password when you download the wallet.zip file.

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

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

    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:

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

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

By default, python-oracledb runs in Thin mode which connects directly to Oracle Database. Additional python-oracledb features are available when it is run in Thick mode.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 three files from the zip 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, do the following:

  1. Use one of two options for placing the files tnsnames.ora, sqlnet.ora, and cwallet.sso 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 depending on where you installed Instant Client, the files should placed be in a directory location such as:

      /home/myuser/instantclient_19_16/network/admin

      or

      /usr/lib/oracle/19.16/client64/lib/network/admin

      If you are using the full Oracle Client move the files to $ORACLE_HOME/network/admin.

      In this case, you can connect to Autonomous Database 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 with the db20222022_low network service name:

      oracledb.init_oracle_client()
      connection=oracledb.connect(
           user="admin",
           password=password,
           dsn="db20222022_low")
    • Alternatively, move the three files to any accessible directory. For example, 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, edit sqlnet.ora as follows:

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

      When tnsnames.ora and sqlnet.ora files are not in the default location your application needs to indicate where they are, either using the config_dir parameter with oracledb.init_oracle_client(), or using 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 files in the network/admin directory.

      For example, to connect as the ADMIN user using the db20222022_low network service name:

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

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.