Conexión de aplicaciones Python mediante mTLS

SOLO SE APLICA A: Aplicable Exadata Cloud@Customer

Puede conectar aplicaciones Python a la instancia de Autonomous AI Database mediante mTLS.

La conexión de una aplicación Python con mTLS proporciona seguridad mejorada para la autenticación y el cifrado. Además, la seguridad se aplica mediante credenciales de cliente (proporcionando un nombre de usuario y una contraseña).

El "modo fino" por defecto del controlador python-oracledb se conecta directamente a Oracle Database. De manera opcional, el controlador puede utilizar bibliotecas de Oracle Client, "modo grueso", para algunas funciones adicionales. Las bibliotecas de Oracle Client pueden ser de Oracle Instant Client, el cliente de Oracle completo o de una instalación de Oracle Database.

Siga estos pasos para conectar la aplicación Python a una instancia de base de datos de IA autónoma mediante mTLS:

  1. Instalación de Python y el controlador python-oracledb
  2. Obtención de credenciales de seguridad (Oracle Wallet) y activación de la conectividad de red
  3. Realice este paso si solo desea conectarse en modo Thin: Ejecute la aplicación Python con el modo Thin oracledb de python (mTLS)
  4. Realice este paso si desea conectarse en modo grueso: Ejecución de la aplicación Python con el modo grueso python-oracledb (mTLS)

Temas relacionados

Instalación de Python y el controlador python-oracledb

Para conectarse a Autonomous AI Database desde la aplicación Python, instale Python y el controlador python-oracledb.

  1. Si aún no está disponible, instale Python 3.

    La versión de Python que utilice dependerá del hardware y el sistema operativo del cliente. Por ejemplo, Windows, Linux, macOS y otros.

    Note:

    Oracle recomienda que se mantenga actualizado con las versiones de controladores Python y python-oracledb.
  2. Instale el controlador python-oracledb desde PyPI.

    El controlador python-oracledb es un módulo de extensión de lenguaje de programación Python que permite a los programas Python conectarse a Oracle Database. El controlador python-oracledb es la nueva versión principal con nombre cambiado del controlador cx_Oracle.

    Versiones admitidas del controlador python-oracledb: python-oracledb 1.0 (o posterior)

    Ejecute el siguiente comando para actualizar python:

    python -m pip install oracledb --upgrade

    Aparece una salida similar a la siguiente:

    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

    Notas sobre la instalación de python-oracledb:

    • Si está protegido por un proxy, utilice la opción --proxy para agregar un servidor proxy al comando. Por ejemplo: 

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

    • En caso de que no tenga permiso para escribir en los directorios del sistema, incluya la opción --user. Por ejemplo: 

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

    • Si no hay un paquete binario disponible para la plataforma, al ejecutar pip se descargará el paquete de origen en su lugar. Se compilará el origen y se instalará el binario resultante.

    Consulte Instalación de python-oracledb para obtener más opciones y consejos.

  3. Si desea utilizar el controlador python-oracledb en modo Grueso, instale el software de Oracle Client.

    Por defecto, python-oracledb se ejecuta en modo Grueso, que se conecta directamente a Oracle Database. En el modo Grueso no se necesitan bibliotecas de Oracle Client. Sin embargo, hay algunas funciones adicionales disponibles cuando python-oracledb se ejecuta en modo grueso.

    Note:

    Consulte Funciones de Oracle Database compatibles con python-oracledb para obtener información sobre las funciones admitidas en los modos Thin y Thick de python-oracledb. No todas las funciones que se muestran en este enlace están disponibles con Autonomous AI Database.

    Python-oracledb utiliza el modo Grueso cuando utiliza las bibliotecas de Oracle Instant Client o las bibliotecas de Oracle Database Client y llama a oracledb.init_oracle_client() en el código Python.

    Al instalar el software de Oracle Client, existen diferencias en las versiones mínimas requeridas para las conexiones mTLS y TLS, de la siguiente manera:

    • Conexiones TLS mutuas (mTLS):

      • Si la base de datos está en una computadora remota, descargue el paquete gratuito Oracle Instant Client "Basic" o "Basic Light" para la arquitectura del sistema operativo. Utilice una versión admitida: Oracle Instant Client: 18.19 (o posterior), 19.2 (o posterior) o 21 (versión base o posterior).

      • También puede utilizar las bibliotecas de cliente de Full Oracle Database cuando estén disponibles en el sistema (incluido Full Oracle Database Client: Oracle Database Client: 18.19 (o posterior), 19.2 (o posterior) o 21 (versión base o posterior).

    • Conexiones TLS: los clientes de Oracle Call Interface (OCI) soportan la autenticación TLS si utiliza las siguientes versiones de cliente:

      • Oracle Instant Client/Oracle Database Client 19.14 (o posterior) y 21.5 (o posterior): todas las plataformas

      • También puede utilizar las bibliotecas de cliente de Full Oracle Database cuando estén disponibles en el sistema, incluidos Full Oracle Database Client 19.14 (o posterior) y 21.5 (o posterior).

Obtención de credenciales de seguridad (Oracle Wallet) y activación de la conectividad de red

Obtenga credenciales del cliente de seguridad para conectarse a una instancia de la base de datos de IA autónoma.

  1. Descargue un archivo de cartera de la instancia de Autonomous AI Database para obtener un archivo zip que contenga las credenciales de seguridad del cliente y los valores de configuración de red necesarios para acceder a una instancia de Autonomous AI Database.

    Obtenga las credenciales de seguridad del cliente (archivo wallet.zip):

    • Usuario ADMIN: en la consola de Oracle Cloud Infrastructure, haga clic en Conexión a base de datos. Consulte Download Client Credentials (Wallets).

    • Otro usuario (no administrativo): obtenga Oracle Wallet del administrador para su instancia de la base de datos de IA autónoma.

    Note:

    Proteja el archivo wallet.zip y su contenido para evitar el acceso no autorizado a la base de datos.
  2. Elimine el archivo de credenciales de cliente (wallet.zip).

Ejecución de la aplicación Python con el modo fino python-oracledb (mTLS)

Por defecto, python-oracledb utiliza el modo Thin para conectarse directamente a su instancia de Autonomous AI Database.

En el modo grueso solo se necesitan dos archivos del zip de cartera:

  • tnsnames.ora: asigna nombres de servicio de red utilizados para cadenas de conexión de aplicaciones a los servicios de base de datos.

  • ewallet.pem: activa las conexiones SSL/TLS en modo fino.

Para conectarse en modo fino:

  1. Mueva los archivos tnsnames.ora y ewallet.pem a una ubicación del sistema.

    Por ejemplo, en Linux:

    /opt/OracleCloud/MYDB

    Por ejemplo, en Windows:

    C:\opt\OracleCloud\MYDB
  2. En la aplicación Python, defina los siguientes parámetros de conexión para conectarse a una instancia de base de datos de IA autónoma:
    • config_dir: especifica el directorio que contiene tnsnames.ora.
    • dsn: se utiliza para especificar el alias de red deseado del archivo tnsnames.ora.
    • password: especifica la contraseña del usuario de la base de datos.
    • user: especifica el usuario de base de datos.
    • wallet_location: especifica el directorio que contiene el archivo PEM (ewallet.pem).
    • wallet_password: especifica la contraseña para el archivo PEM (ewallet.pem). Esta contraseña se define al descargar el archivo wallet.zip.

    Por ejemplo, en Linux para conectarse como usuario ADMIN mediante oracledb.connect con el nombre de servicio de red db2024_low (el nombre de servicio se encuentra en 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)

    Por ejemplo, en Windows para conectarse como usuario ADMIN mediante oracledb.connect con el nombre de servicio de red db2024_low (el nombre de servicio se encuentra en 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)

    El uso de una cadena 'raw' r"..." significa que las barras invertidas se tratan como separadores de directorio.

    Como se muestra en este ejemplo, wallet_location y config_dir se definen en el mismo directorio (y el directorio contiene tnsnames.ora y ewallet.pem). No es necesario especificar el mismo directorio para estos archivos.

Si está detrás de un firewall, puede establecer un túnel de las conexiones TLS/SSL a través de un proxy mediante HTTPS_PROXY en el descriptor de conexión o definiendo atributos de conexión. La conexión correcta depende de configuraciones de proxy específicas. Oracle no recomienda utilizar un proxy en un entorno de producción, debido al posible impacto en el rendimiento. Consulte HTTPS_PROXY en Referencia de servicios de red de base de datos de Oracle Database 19c u Referencia de servicios de red de base de datos de Oracle Database 26ai para obtener más información.

En el modo fino, puede especificar un proxy agregando los parámetros https_proxy y http_proxy_port.

Por ejemplo, en 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)

Por ejemplo, en 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)

Ejecución de la aplicación Python con modo grueso python-oracledb (mTLS)

Por defecto, python-oracledb se ejecuta en modo Grueso, que se conecta directamente a Oracle Database. Hay disponibles funciones adicionales de python-oracledb cuando el controlador se ejecuta en modo grueso.

Note:

El modo grueso requiere que las bibliotecas de Oracle Client estén instaladas donde se ejecuta Python. También debe llamar a oracledb.init_oracle_client() en el código de Python.

En el modo grueso, se necesitan los siguientes tres archivos del archivo zip de cartera:

  • tnsnames.ora: contiene los nombres de servicio de red utilizados para las cadenas de conexión de aplicaciones y asigna las cadenas a los servicios de base de datos.

  • sqlnet.ora: especifica la configuración del cliente de SQL*Net.

  • cwallet.sso: contiene la cartera de SSO automática.

Para conectarse en modo grueso:

  1. Coloque los archivos tnsnames.ora, sqlnet.ora y cwallet.sso en el sistema.

    Utilice una de las dos opciones para colocar estos archivos en el sistema:

    • Si va a utilizar Instant Client, mueva los archivos a la jerarquía de subdirectorios network/admin en el directorio Instant Client. Por ejemplo, en función de la arquitectura o el sistema cliente y de dónde haya instalado Instant Client, los archivos deben estar ubicados en una ubicación de directorio como: 

      /home/myuser/instantclient_19_21/network/admin

      o bien,

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

      Por ejemplo, en Linux si va a utilizar Oracle Client completo, mueva los archivos a $ORACLE_HOME/network/admin.

    • También puede mover los archivos a cualquier directorio al que se pueda acceder.

      Por ejemplo, en Linux, mueva los archivos al directorio /opt/OracleCloud/MYDB y edite sqlnet.ora para cambiar el directorio de ubicación de cartera al directorio que contiene el archivo cwallet.sso.

      Por ejemplo, en Linux, edite sqlnet.ora de la siguiente manera: 

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

      Cuando los archivos de configuración no están en la ubicación por defecto, la aplicación debe indicar dónde están, ya sea con el parámetro config_dir en la llamada oracledb.init_oracle_client() o definiendo la variable de entorno TNS_ADMIN.

      Note:

      Ninguno de estos valores es necesario y no necesita editar sqlnet.ora si coloca todos los archivos de configuración en el directorio network/admin.
  2. En la aplicación Python, defina los siguientes parámetros de inicialización y conexión para conectarse a la instancia de base de datos de IA autónoma:
    • config_dir: especifica el directorio de configuración al colocar los archivos de configuración. Esto sólo es necesario cuando los archivos de configuración se colocan en un directorio fuera del directorio de configuración de cliente instantáneo network/admin.
    • dsn: especifica el alias de red deseado del archivo tnsnames.ora.
    • password: especifica la contraseña del usuario de la base de datos.
    • user: especifica el usuario de base de datos.

    En el primer caso para la ubicación de los archivos de configuración, conéctese a la instancia de Autonomous AI Database mediante las credenciales de la base de datos definiendo el parámetro dsn en el alias de red deseado de tnsnames.ora.

    Por ejemplo, para conectarse como usuario ADMIN mediante oracledb.init_oracle_client y conectarse con el nombre de servicio de red db2024_low (donde el nombre de servicio se encuentra en tnsnames.ora): 

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

    Cuando los archivos de configuración estén en un directorio fuera del directorio de configuración de cliente instantáneo, defina el parámetro config_dir al llamar a oracledb.init_oracle_client.

    Por ejemplo, en Linux para conectarse como usuario ADMIN con el nombre de servicio de red db2024_low: 

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

    Por ejemplo, en Windows para conectarse como usuario ADMIN mediante el nombre de servicio de red db2024_low: 

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

    El uso de una cadena 'raw' r"..." significa que las barras invertidas se tratan como separadores de directorio.

Si está detrás de un firewall, puede establecer un túnel de las conexiones TLS/SSL a través de un proxy mediante HTTPS_PROXY en el descriptor de conexión o definiendo atributos de conexión. La conexión correcta depende de configuraciones de proxy específicas. Oracle no recomienda utilizar un proxy en un entorno de producción, debido al posible impacto en el rendimiento. Consulte HTTPS_PROXY en Referencia de servicios de red de base de datos de Oracle Database 19c u Referencia de servicios de red de base de datos de Oracle Database 26ai para obtener más información.

En el modo Grueso, puede especificar un proxy editando el archivo sqlnet.ora y agregando una línea: 

SQLNET.USE_HTTPS_PROXY=on

Además, edite tnsnames.ora y agregue un nombre de proxy HTTPS_PROXY y un puerto HTTPS_PROXY_PORT a la lista de direcciones del descriptor de conexión de cualquier nombre de servicio que tenga previsto utilizar.

Por ejemplo:

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

Consulte Activación del modo grueso de python-oracledb para obtener información sobre el modo Grueso.