使用 mTLS 连接 Python 应用程序

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

您可以使用 mTLS 将 Python 应用连接到 Autonomous Database 实例。

使用 mTLS 连接 Python 应用程序可增强验证和加密的安全性，并使用客户机凭证（提供用户名和密码）实施安全性。

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

按照以下步骤使用 mTLS 将 Python 应用连接到 Autonomous Database 实例：

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

安装 Python 和 python-oracledb 驱动程序

要从 Python 应用程序连接到 Autonomous Database ，请安装 Python 和 python-oracledb 驱动程序。

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

   您使用的 Python 版本取决于您的客户端 OS 和硬件。例如，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 。Autonomous Database 中没有提供此链接中显示的所有功能。

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

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

   • 相互 TLS (mTLS) 连接：

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

     • 或者，您可以在系统上提供完整的 Oracle Database 客户端库（包括完整的 Oracle Database 客户端：Oracle Database 客户端：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) 并启用网络连接

获取客户端安全身份证明以连接到 Autonomous Database 实例。

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

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

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

   • 其他用户（非管理员）：从管理员获取 Autonomous Database 实例的 Oracle Wallet。

   注意：

   保护 wallet.zip 文件及其内容，以防止未经授权的数据库访问。
2. 解压缩客户机凭证文件 (wallet.zip)。

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

默认情况下，python-oracledb 使用瘦模式直接连接到 Autonomous Database 实例。

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

• tnsnames.ora：将用于应用程序连接字符串的网络服务名映射到数据库服务。

• ewallet.pem：在瘦模式下启用 SSL/TLS 连接。

要以瘦模式连接：

1. 将 tnsnames.ora 和 ewallet.pem 文件移至系统上的某个位置。
   • Linux
   • Windows

   例如，在 Linux 上：

   /opt/OracleCloud/MYDB

   例如，在 Windows 上：

   C:\opt\OracleCloud\MYDB

2. 在 Python 应用程序中，设置以下连接参数以连接到 Autonomous Database 实例：
   • config_dir：指定包含 tnsnames.ora 的目录。
   • dsn：用于指定 tnsnames.ora 文件中所需的网络别名。
   • password：指定数据库用户密码。
   • user：指定数据库用户。
   • wallet_location：指定包含 PEM 文件 (ewallet.pem) 的目录。
   • wallet_password：指定 PEM 文件 (ewallet.pem) 的口令。下载 wallet.zip 文件时可设置此密码。
   • Linux
   • Windows

   例如，在 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 上，使用带有 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)

   使用“原始”字符串 r...”表示将反斜杠视为目录分隔符。

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

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

在瘦模式下，可以通过添加 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 Thick Mode (mTLS) 运行 Python 应用程序

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

注意：

厚模式要求在运行 Python 的位置安装 Oracle 客户端库。您还必须在 Python 代码中调用 oracledb.init_oracle_client()。

在厚模式下，需要从 wallet zip 文件中获取以下三个文件：

• tnsnames.ora：包含用于应用程序连接字符串的网络服务名，并将字符串映射到数据库服务。

• sqlnet.ora：指定 SQL*Net 客户端配置。

• cwallet.sso：包含自动打开的 SSO wallet。

要在“厚”模式下连接，请执行以下操作：

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 应用程序中，设置以下初始化和连接参数以连接到 Autonomous Database 实例：
   • config_dir：在放置配置文件时指定配置目录。仅当配置文件放置在即时客户机配置目录 network/admin 之外的目录中时，才需要执行此操作。
   • dsn：指定 tnsnames.ora 文件中所需的网络别名。
   • password：指定数据库用户密码。
   • user：指定数据库用户。

   在用于放置配置文件的第一个情况下，使用数据库身份证明连接到 Autonomous Database 实例，方法是从 tnsnames.ora 将 dsn 参数设置为所需的网络别名。

   例如，要以 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
   • Windows

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

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

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

   使用“原始”字符串 r...”表示将反斜杠视为目录分隔符。

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

在“厚”模式下，可以通过编辑 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 。

---

标题和版权信息

Copyright ©2022,2024,

Oracle 和/或其关联公司。