Estabelecer Conexão com Aplicativos Python Usando mTLS

APLICA-SE A: Aplicável Somente Exadata Cloud@Customer

Você pode conectar aplicativos Python à instância do Autonomous Database usando mTLS.

A conexão de um aplicativo Python com mTLS fornece segurança avançada para autenticação e criptografia, e a segurança é aplicada usando as credenciais do cliente (fornecendo um nome de usuário e uma senha).

O "modo Thin" padrão do driver python-oracledb se conecta diretamente ao Oracle Database. O driver tem a opção de usar as bibliotecas do Oracle Client, "Modo Thick", para funcionalidade adicional. As bibliotecas do Oracle Client podem ser do Oracle Instant Client, do Cliente Oracle completo ou de uma instalação do Oracle Database.

Siga estas etapas para conectar seu aplicativo Python a uma instância do Autonomous Database usando o comando mTLS:

  1. Instalar o Python e o Driver python-oracledb
  2. Obter Credenciais de Segurança (Oracle Wallet) e Ativar a Conectividade de Rede
  3. Execute esta etapa se quiser se conectar apenas no modo Thin: Executar Aplicativo Python com o Modo Thin python-oracledb (mTLS)
  4. Execute esta etapa se quiser estabelecer conexão no modo Thick: Executar Aplicativo Python com o Modo Thick python-oracledb (mTLS)

Tópicos Relacionados

Instalar o Python e o Driver python-oracledb

Para estabelecer conexão com o Autonomous Database do seu aplicativo Python, instale o driver Python e o driver python-oracledb.

  1. Instale o Python 3, se ele ainda não estiver disponível.

    A versão do Python que você usa depende do sistema operacional e do hardware do cliente. Por exemplo, Windows, Linux, macOS e outros.

    Observação:

    A Oracle recomenda que você mantenha-se atualizado com as versões do driver Python e python-oracledb.
  2. Instale o driver python-oracledb em PyPI.

    O driver python-oracledb é um módulo de extensão da linguagem de programação Python que permite que programas Python se conectem ao Oracle Database. O driver python-oracledb é a nova release principal renomeada do popular driver cx_Oracle.

    Versões suportadas do driver python-oracledb: python-oracledb 1.0 (ou posterior)

    Execute o seguinte comando para fazer upgrade do python:

    python -m pip install oracledb --upgrade

    Você deverá ver uma saída semelhante a esta:

    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

    Observações da instalação do python-oracledb:

    • Se você estiver usando um proxy, utilize a opção --proxy para adicionar um servidor proxy ao comando. Por exemplo: 

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

    • No caso em de você não ter permissão para gravar nos diretórios do sistema, inclua a opção --user. Por exemplo: 

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

    • Se um pacote binário não estiver disponível para sua plataforma, a execução de pip fará download do pacote de origem. A origem é compilada e o binário resultante é instalado.

    Consulte Instalando o python-oracledb para obter opções e dicas adicionais.

  3. Se você quiser usar o driver python-oracledb no modo Thick, instale o software Oracle Client.

    Por padrão, o python-oracledb é executado no modo Thin que se conecta diretamente ao Oracle Database. O modo Thin não exige bibliotecas do Oracle Client. No entanto, uma funcionalidade adicional está disponível quando o python-oracledb é executado no modo Thick.

    Observação:

    Consulte Recursos do Oracle Database Suportados pelo python-oracledb para obter informações sobre os recursos suportados nos modos Thin e Thick do python-oracledb. Nem todos os recursos mostrados nesse link estão disponíveis com o Autonomous Database.

    O python-oracledb usa o modo Thick quando você usa as bibliotecas do cliente Oracle Instant ou do Oracle Database Client e chama oracledb.init_oracle_client() no código Python.

    Ao instalar o Oracle Client Software, há diferenças nas versões mínimas obrigatórias para conexões mTLS e TLS, conforme a seguir:

    • Conexões mTLS (TLS Mútuo):

      • Se o seu banco de dados estiver em um computador remoto, faça download do pacote "Basic" ou "Basic Light" do Oracle Instant Client gratuito para sua arquitetura de sistema operacional. Use uma versão suportada: Oracle Instant Client: 18.19 (ou mais recente), 19.2 (ou mais recente) ou 21 (versão base ou mais recente).

      • Como alternativa, você pode usar as bibliotecas do cliente Oracle Database Completo quando elas estiverem disponíveis no seu sistema (incluindo o Oracle Database Client Completo: Oracle Database Client Completo: 18.19 (ou posterior), 19.2 (ou posterior) ou 21 (versão base ou posterior).

    • Conexões TLS: Os clientes Oracle Call Interface (OCI) suportarão a autenticação TLS se você estiver usando as seguintes versões do cliente:

      • Oracle Instant Client/Oracle Database Client 19.14 (ou mais recente) e 21.5 (ou mais recente) - todas as plataformas

      • Se preferir, você poderá usar as bibliotecas do cliente Oracle Database Completo quando elas estiverem disponíveis no seu sistema, incluindo o Oracle Database Client Completo 19.14 (ou mais recente) e 21.5 (ou mais recente).

Obter Credenciais de Segurança (Oracle Wallet) e Ativar a Conectividade de Rede

Obtenha credenciais de segurança do cliente para estabelecer conexão com uma instância do Autonomous Database.

  1. Faça download de um arquivo de wallet na instância do Autonomous Database para obter um arquivo zip que contenha as credenciais de segurança do cliente e as definições de configuração de rede necessárias para acessar uma instância do Autonomous Database.

    Obtenha as credenciais de segurança do cliente (arquivo wallet.zip):

    • Usuário ADMIN: Na Console do Oracle Cloud Infrastructure, clique em Conexão do banco de dados. Consulte Fazer Download das Credenciais do Cliente (Wallets).

    • Outro usuário (não administrador): Obtenha a Oracle Wallet junto ao administrador da instância do Autonomous Database.

    Observação:

    Proteja o arquivo wallet.zip e seu conteúdo para impedir o acesso não autorizado ao banco de dados.
  2. Descompacte o arquivo de credenciais do cliente (wallet.zip).

Executar Aplicativo Python com o Modo Thin python-oracledb (mTLS)

Por padrão, o python-oracledb usa o modo Thin para estabelecer conexão diretamente com a instância do Autonomous Database.

No modo Thin, são necessários apenas dois arquivos do zip da wallet:

  • tnsnames.ora: Mapeia nomes de serviço de rede usados para strings de conexão de aplicativo para seus serviços de banco de dados.

  • ewallet.pem: Ativa conexões SSL/TLS no modo Thin.

Para estabelecer conexão no modo Thin:

  1. Mova os arquivos tnsnames.ora e ewallet.pem para um local no sistema.

    Por exemplo, no Linux:

    /opt/OracleCloud/MYDB

    Por exemplo, no Windows:

    C:\opt\OracleCloud\MYDB
  2. No seu aplicativo Python, defina os seguintes parâmetros de conexão para conectar-se a uma instância do Autonomous Database:
    • config_dir: Especifica o diretório que contém o arquivo tnsnames.ora.
    • dsn: Use para especificar o alias de rede desejado do arquivo tnsnames.ora.
    • password: Especifica a senha de usuário do banco de dados.
    • user: Especifica o usuário do banco de dados.
    • wallet_location: Especifica o diretório que contém o arquivo PEM (ewallet.pem).
    • wallet_password: Especifica a senha do arquivo PEM (ewallet.pem). Você define essa senha quando faz download do arquivo wallet.zip.

    Por exemplo, no Linux, para conectar-se como usuário ADMIN utilizando oracledb.connect com o nome de serviço de rede db2024_low (o nome do serviço é encontrado em 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 exemplo, no Windows, para conectar-se como usuário ADMIN utilizando oracledb.connect com o nome de serviço de rede db2024_low (o nome do serviço é encontrado em 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)

    O uso de uma string 'bruto' r"..." significa que as barras invertidas são tratadas como separadores de diretório.

    Conforme mostrado neste exemplo, wallet_location e config_dir são definidos para o mesmo diretório (e o diretório contém os arquivos tnsnames.ora e ewallet.pem. Não é obrigatório especificar o mesmo diretório para esses arquivos.

Se você estiver protegido por um firewall, poderá tunelar conexões TLS/SSL por meio de um proxy usando HTTPS_PROXY no descritor de conexão ou definindo atributos de conexão. A conexão bem-sucedida depende de configurações de proxy específicas. A Oracle não recomenda o uso de um proxy em um ambiente de produção, devido ao possível impacto no desempenho. Consulte HTTPS_PROXY em Oracle Database 19c Database Net Services Reference ou Oracle Database 23ai Database Net Services Reference para obter mais informações.

No modo Thin, você pode especificar um proxy adicionando os parâmetros https_proxy e http_proxy_port.

Por exemplo, no 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 exemplo, no 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)

Executar Aplicativo Python com o Modo Thick python-oracledb (mTLS)

Por padrão, o python-oracledb é executado no modo Thin, que se conecta diretamente ao Oracle Database. Recursos adicionais de python-oracledb estão disponíveis quando o driver é executado no modo Thick.

Observação:

O modo Thick exige que as bibliotecas do Oracle Client sejam instaladas onde você executa o Python. Você também deve chamar oracledb.init_oracle_client() em seu código Python.

No modo Thick, os três arquivos a seguir do arquivo zip da wallet são necessários:

  • tnsnames.ora: Contém os nomes de serviço de rede usados para strings de conexão de aplicativo e mapeia as strings para os serviços de banco de dados.

  • sqlnet.ora: Especifica a configuração do cliente SQL*Net.

  • cwallet.sso: Contém a wallet de SSO aberta automaticamente.

Para estabelecer conexão no modo Thick:

  1. Coloque os arquivos tnsnames.ora, sqlnet.ora e cwallet.sso no sistema.

    Use uma das duas opções para colocar esses arquivos no sistema:

    • Se você estiver usando o Instant Client, mova os arquivos para uma hierarquia de subdiretórios network/admin no diretório Instant Client. Por exemplo, dependendo da arquitetura ou do sistema cliente e onde você instalou o Instant Client, os arquivos deverão ser colocados em um diretório como: 

      /home/myuser/instantclient_19_21/network/admin

      ou

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

      Por exemplo, no Linux, se você estiver usando o Oracle Client completo, mova os arquivos para $ORACLE_HOME/network/admin.

    • Se preferir, mova os arquivos para qualquer diretório acessível.

      Por exemplo, no Linux, mova os arquivos para o diretório /opt/OracleCloud/MYDB e edite sqlnet.ora para alterar o diretório de local da wallet para o diretório que contém o arquivo cwallet.sso.

      Por exemplo, no Linux, edite o arquivo sqlnet.ora da seguinte forma: 

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

      Quando os arquivos de configuração não estão no local padrão, seu aplicativo precisa indicar onde eles estão, com o parâmetro config_dir na chamada oracledb.init_oracle_client() ou definindo a variável de ambiente TNS_ADMIN.

      Observação:

      Nenhuma dessas definições é necessária e você não precisará editar sqlnet.ora se colocar todos os arquivos de configuração no diretório network/admin.
  2. No seu aplicativo Python, defina os seguintes parâmetros de inicialização e conexão para conectar-se à instância do Autonomous Database:
    • config_dir: Especifica o diretório de configuração quando você está colocando os arquivos de configuração. Isso só é necessário quando os arquivos de configuração são colocados em um diretório fora do diretório de configuração instantânea do cliente network/admin.
    • dsn: Especifica o alias de rede desejado do arquivo tnsnames.ora.
    • password: Especifica a senha de usuário do banco de dados.
    • user: Especifica o usuário do banco de dados.

    No primeiro caso de posicionamento dos arquivos de configuração, conecte-se à instância do Autonomous Database usando suas credenciais de banco de dados definindo o parâmetro dsn como alias de rede desejado no arquivo tnsnames.ora.

    Por exemplo, para conectar-se como usuário ADMIN usando oracledb.init_oracle_client e conectar-se com o nome de serviço de rede db2024_low (em que o nome do serviço é encontrado em tnsnames.ora): 

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

    Quando os arquivos de configuração estiverem em um diretório fora do diretório de configuração do cliente instantâneo, defina o parâmetro config_dir quando chamar oracledb.init_oracle_client.

    Por exemplo, no Linux, para conectar-se como usuário ADMIN usando o nome de serviço de rede db2024_low: 

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

    Por exemplo, no Windows, para conectar-se como usuário ADMIN usando o nome de serviço de rede db2024_low: 

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

    O uso de uma string 'bruto' r"..." significa que as barras invertidas são tratadas como separadores de diretório.

Se você estiver protegido por um firewall, poderá tunelar conexões TLS/SSL por meio de um proxy usando HTTPS_PROXY no descritor de conexão ou definindo atributos de conexão. A conexão bem-sucedida depende de configurações de proxy específicas. A Oracle não recomenda o uso de um proxy em um ambiente de produção, devido ao possível impacto no desempenho. Consulte HTTPS_PROXY em Oracle Database 19c Database Net Services Reference ou Oracle Database 23ai Database Net Services Reference para obter mais informações.

No modo Thick, é possível especificar um proxy editando o arquivo sqlnet.ora e adicionando uma linha: 

SQLNET.USE_HTTPS_PROXY=on

Além disso, edite tnsnames.ora e adicione um nome de proxy HTTPS_PROXY e uma porta HTTPS_PROXY_PORT à lista de endereços do descritor de conexão de qualquer nome de serviço que você planeja usar.

Por exemplo:

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

Consulte Ativando o modo Thick python-oracledb para obter informações no modo Thick.