使用 mTLS 连接 Python 应用程序

适用于：适用 仅限 Exadata Cloud@Customer

您可以使用 mTLS 将 Python 应用连接到自治 AI 数据库实例。

将 Python 应用程序与 mTLS 连接可提供增强的身份验证和加密安全性，并使用客户端凭证（通过提供用户名和密码）强制实施安全性。

python-oracledb 驱动程序的默认“瘦模式”直接连接到 Oracle Database。驱动程序可以选择使用 Oracle Client 库“Thick mode（厚模式）”来获得一些其他功能。Oracle Client 库可以来自 Oracle Instant Client、完整的 Oracle Client 或 Oracle Database 安装。

按照以下步骤使用 mTLS 将 Python 应用连接到自治 AI 数据库实例：

  1. 安装 Python 和 python-oracledb 驱动程序
  2. 获取安全凭证 (Oracle Wallet) 和启用网络连接
  3. 如果您只想在瘦模式下连接，请执行此步骤：使用 python-oracledb 瘦模式 (mTLS) 运行 Python 应用程序
  4. 如果要以 Thick 模式连接，请执行此步骤：使用 python-oracledb 厚模式 (mTLS) 运行 Python 应用程序

安装 Python 和 python-oracledb 驱动程序

要从您的 Python 应用连接到自治 AI 数据库，请安装 Python 和 python-oracledb 驱动程序。

  1. 安装 Python 3 （如果尚不可用）。

    你使用的 Python 版本取决于你的客户端操作系统和硬件。例如 Windows、Linux、macOS 等。

    注：Oracle 建议您与 Python 和 python-oracledb 驱动程序发行版保持同步。

  2. 从 PyPI 安装 python-oracledb 驱动程序。

    python-oracledb 驱动程序是一个 Python 编程语言扩展模块，允许 Python 程序连接到 Oracle Database。python-oracledb 驱动程序是主流 cx_Oracle 驱动程序的重命名新主要发行版。

    支持的 python-oracledb 驱动程序版本：python-oracledb 1.0（或更高版本）

    运行以下命令升级 python：

     python -m pip install oracledb --upgrade

    您应看到类似如下的输出结果：

     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

    安装 python-oracledb 的说明：

    • 如果位于代理后面，请使用 --proxy 选项将代理服务器添加到命令。例如：

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

    • 如果您无权写入系统目录，请包括 --user 选项。例如：

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

    • 如果某个二进制软件包不适用于您的平台，则运行 pip 将改为下载源软件包。将编译源并安装生成的二进制文件。

    有关其他选项和提示，请参见 Installing python-oracledb 。

  3. 如果要以 Thick 模式使用 python-oracledb 驱动程序，请安装 Oracle Client 软件。

    默认情况下，python-oracledb 以 Thin 模式运行，该模式直接连接到 Oracle Database。瘦模式不需要 Oracle Client 库。但是，当 python-oracledb 在 Thick 模式下运行时，一些附加功能可用。

    注：有关 python-oracledb Thin 和 Thick 模式中支持的功能的信息，请参阅 Oracle Database Features Supported by python-oracledb 。并非此链接中显示的所有功能都可用于自治 AI 数据库。

    使用 Oracle Instant 客户端库或 Oracle Database 客户端库时，Python-oracledb 使用 Thick 模式，并在 Python 代码中调用 oracledb.init_oracle_client()。

    安装 Oracle Client Software 时，mTLS 和 TLS 连接所需的最低版本存在差异，如下所示：

    • 相互 TLS (mTLS) 连接：

      • 如果您的数据库位于远程计算机上，则下载适用于您的操作系统体系结构的免费 Oracle Instant Client “基本”或“基本光”程序包。使用支持的版本：Oracle Instant Client ：18.19（或更高版本）、19.2（或更高版本）或 21（基本发行版或更高版本）。

      • 或者，您可以在系统中提供完整的 Oracle Database 客户端库（包括完整的 Oracle Database 客户端：Oracle Database Client ：18.19（或更高版本）、19.2（或更高版本）或 21（基本发行版或更高版本）时使用它们。

    • TLS 连接：如果使用以下客户机版本，Oracle Call Interface (OCI) 客户机支持 TLS 验证：

      • Oracle Instant Client/Oracle Database Client 19.14（或更高版本）和 21.5（或更高版本）- 所有平台

      • 或者，您可以在系统中提供完整的 Oracle Database 客户端库时使用它们，包括完整的 Oracle Database Client 19.14（或更高版本）和 21.5（或更高版本）。

获取安全凭证 (Oracle Wallet) 和启用网络连接

获取客户端安全身份证明以连接到自治 AI 数据库实例。

  1. 从自治 AI 数据库实例下载 wallet 文件以获取包含访问自治 AI 数据库实例所需的客户端安全身份证明和网络配置设置的 zip 文件。

    获取客户机安全凭证（wallet.zip 文件）：

    • 管理用户：在 Oracle Cloud Infrastructure 控制台上，单击数据库连接。请参见 Download Client Credentials (Wallets) 。

    • 其他用户（非管理员）：从管理员处获取自治 AI 数据库实例的 Oracle Wallet。

      注：保护 wallet.zip 文件及其内容，以防止未经授权的数据库访问。

  2. 解压缩客户机凭证文件 (wallet.zip)。

使用 python-oracledb 瘦模式 (mTLS) 运行 Python 应用程序

默认情况下，python-oracledb 使用 Thin 模式直接连接到自治 AI 数据库实例。

在瘦模式下，只需要钱包 zip 中的两个文件：

要在瘦模式下连接：

  1. 将 tnsnames.ora 和 ewallet.pem 文件移动到系统上的某个位置。

    Linux

    例如在 Linux 上：

     /opt/OracleCloud/MYDB

    Windows

    例如，在 Windows 上：

     C:\opt\OracleCloud\MYDB

  2. 在 Python 应用程序中，设置以下连接参数以连接到自治 AI 数据库实例：

    • config_dir：指定包含 tnsnames.ora 的目录。

    • dsn：用于从 tnsnames.ora 文件指定所需的网络别名。

    • password：指定数据库用户密码。

    • user：指定数据库用户。

    • wallet_location：指定包含 PEM 文件 (ewallet.pem) 的目录。

    • wallet_password：指定 PEM 文件 (ewallet.pem) 的密码。下载 wallet.zip 文件时设置此密码。

    Linux

    例如，在 Linux 上使用带有 db2024_low 网络服务名称的 oracledb.connect 以 ADMIN 用户身份进行连接（服务名称位于 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)

    Windows

    例如，在 Windows 上，使用带有 db2024_low 网络服务名称的 oracledb.connect 以 ADMIN 用户身份进行连接（服务名称位于 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)

    使用 'raw' 字符串 r“...”表示反斜杠被视为目录分隔符。

    如本示例所示，wallet_location 和 config_dir 设置为同一目录（该目录包含 tnsnames.ora 和 ewallet.pem）。不需要为这些文件指定相同的目录。

如果您位于防火墙后面，则可以使用连接描述符中的 HTTPS_PROXY 或通过设置连接属性通过代理来隧道 TLS/SSL 连接。成功的连接取决于特定的代理配置。Oracle 不建议在生产环境中使用代理，因为这可能对性能产生影响。有关详细信息，请参阅 Oracle Database 19c Database Net Services Reference 中的 HTTPS_PROXY 或 Oracle Database 26ai Database Net Services Reference 。

在瘦模式下，您可以通过添加 https_proxy 和 http_proxy_port 参数来指定代理。

例如，在 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)

例如，在 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)

使用 python-oracledb 厚模式 (mTLS) 运行 Python 应用程序

默认情况下，python-oracledb 以 Thin 模式运行，该模式直接连接到 Oracle Database。当驱动程序在 Thick 模式下运行时，其他 python-oracledb 功能可用。

注： Thick 模式要求在运行 Python 的位置安装 Oracle Client 库。您还必须在 Python 代码中调用 oracledb.init_oracle_client()。

在 Thick 模式下，需要 Wallet zip 文件中的以下三个文件：

在“厚”模式下连接：

  1. 将文件 tnsnames.ora、sqlnet.ora 和 cwallet.sso 放在系统上。

    使用以下两个选项之一在系统上放置这些文件：

    • 如果使用 Instant Client，请将这些文件移到 Instant Client 目录下的 network/admin 子目录分层结构中。例如，根据体系结构或客户机系统以及安装 Instant Client 的位置，文件应放置在目录位置，例如：

      /home/myuser/instantclient_19_21/network/admin

      或者

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

      例如，在 Linux 上，如果使用的是完整的 Oracle Client，则将文件移动到 $ORACLE_HOME/network/admin。

    • 或者，将文件移动到任何可访问的目录。

      例如，在 Linux 上，将文件移动到目录 /opt/OracleCloud/MYDB 并编辑 sqlnet.ora 以将 wallet 位置目录更改为包含 cwallet.sso 文件的目录。

      例如，在 Linux 上，按如下方式编辑 sqlnet.ora：

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

      如果配置文件不在默认位置，则应用程序需要通过调用 oracledb.init_oracle_client() 中的 config_dir 参数或通过设置 TNS_ADMIN 环境变量来指示其所在位置。

      注：这些设置均不是必需的，如果将所有配置文件放在 network/admin 目录中，则不需要编辑 sqlnet.ora。

  2. 在 Python 应用程序中，设置以下初始化参数和连接参数以连接到自治 AI 数据库实例：

    • config_dir：在放置配置文件时指定配置目录。仅当配置文件位于即时客户机配置目录 network/admin 之外的目录中时，才需要执行此操作。

    • dsn：从 tnsnames.ora 文件指定所需的网络别名。

    • password：指定数据库用户密码。

    • user：指定数据库用户。

    在放置配置文件的第一种情况下，使用数据库凭证连接到自治 AI 数据库实例，方法是将 dsn 参数设置为所需的 tnsnames.ora 网络别名。

    例如，要以 ADMIN 用户身份使用 oracledb.init_oracle_client 进行连接并连接 db2024_low 网络服务名称（服务名称位于 tnsnames.ora 中）：

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

    当配置文件位于即时客户机配置目录外部的目录中时，请在调用 oracledb.init_oracle_client 时设置 config_dir 参数。

    Linux

    例如，在 Linux 上，以 ADMIN 用户身份使用 db2024_low 网络服务名称进行连接：

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

    Windows

    例如，在 Windows 上，以 ADMIN 用户身份使用 db2024_low 网络服务名称进行连接：

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

    使用 'raw' 字符串 r“...”表示反斜杠被视为目录分隔符。

如果您位于防火墙后面，则可以使用连接描述符中的 HTTPS_PROXY 或通过设置连接属性通过代理来隧道 TLS/SSL 连接。成功的连接取决于特定的代理配置。Oracle 不建议在生产环境中使用代理，因为这可能对性能产生影响。有关详细信息，请参阅 Oracle Database 19c Database Net Services Reference 中的 HTTPS_PROXY 或 Oracle Database 26ai Database Net Services Reference 。

在 "Thick" 模式下，可以通过编辑 sqlnet.ora 文件并添加一行来指定代理：

SQLNET.USE_HTTPS_PROXY=on

此外，编辑 tnsnames.ora 并将 HTTPS_PROXY 代理名和 HTTPS_PROXY_PORT 端口添加到计划使用的任何服务名的连接描述符地址列表中。

例如：

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

有关 "Thick" 模式的信息，请参见 Enabling python-oracledb Thick mode 。

相关内容

关于连接到专用自治 AI 数据库