Documentação do Oracle Cloud Infrastructure

Conectar Aplicativos Python com uma Wallet (mTLS)

Você pode conectar aplicativos Python à sua instância do Autonomous AI Database com uma wallet.

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

O "modo fino" padrão do driver python-oracledb se conecta diretamente ao Oracle AI Database. O driver pode, opcionalmente, usar bibliotecas do Oracle Client, "modo Thick", para alguma funcionalidade adicional. As bibliotecas de Oracle Client podem ser do Oracle Instant Client, do Oracle Client completo, ou de uma instalação do Oracle AI Database.

Siga estas etapas para conectar seu aplicativo Python a uma instância do Autonomous AI Database usando uma wallet (mTLS):

  1. Instalar o Python e o Driver python-oracledb

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

Obtenha as credenciais do cliente para estabelecer conexão com uma instância do Autonomous AI Database.

  1. Faça download de um arquivo da wallet da instância do Autonomous AI Database para obter um arquivo compactado 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 AI 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 o Oracle Wallet do administrador da sua instância do Autonomous AI Database.

    Observação

    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 o Aplicativo Python com o Modo Thin python-oracledb com uma Wallet (mTLS)

Por padrão, o python-oracledb usa o modo Thin para se conectar diretamente à sua instância do Autonomous AI 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 aplicativos para seus serviços de banco de dados.

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

Para se conectar 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. Em seu aplicativo Python, defina os seguintes parâmetros de conexão para estabelecer conexão com uma instância do Autonomous AI Database:

    • config_dir: Especifica o diretório que contém tnsnames.ora.

    • dsn: Use para especificar o alias de rede desejado no arquivo tnsnames.ora.

    • password: Especifica a senha do 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 estabelecer conexão como o usuário ADMIN usando oracledb.connect com o nome do 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 estabelecer conexão como o usuário ADMIN usando oracledb.connect com o nome do 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 'bruta' r"..." significa que 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 tnsnames.ora e ewallet.pem). Não é necessário especificar o mesmo diretório para esses arquivos.

Se você estiver protegido por um firewall, poderá encapsular 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.

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 o Aplicativo Python com o Modo Thick python-oracledb com uma Wallet (mTLS)

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

Observação

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

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

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

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

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

Para conectar no modo Grosso:

  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 do subdiretório network/admin no diretório Instant Client. Por exemplo, dependendo da arquitetura ou de seu sistema cliente e onde você instalou o Instant Client, os arquivos deverão ser colocados em um local de 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 Cliente Oracle completo, mova os arquivos para $ORACLE_HOME/network/admin.

    • Como alternativa, 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 localização da wallet para o diretório que contém o arquivo cwallet.sso.

      Por exemplo, no Linux, edite 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 estão, seja com o parâmetro config_dir na chamada oracledb.init_oracle_client() ou definindo a variável de ambiente TNS_ADMIN.

    Observação

    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. Em seu aplicativo Python, defina os seguintes parâmetros de inicialização e conexão para estabelecer conexão com a instância do Autonomous AI Database:

    • config_dir: Especifica o diretório de configuração quando você está colocando os arquivos de configuração. Isto só é necessário quando os arquivos de configuração são colocados em um diretório fora do diretório de configuração do cliente instantâneo network/admin.

    • dsn: Especifica o alias de rede desejado do arquivo tnsnames.ora.

    • password: Especifica a senha do usuário do banco de dados.

    • user: Especifica o usuário do banco de dados.

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

    Por exemplo, para estabelecer conexão como o usuário ADMIN usando oracledb.init_oracle_client e estabelecer conexão com o nome do 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 ao chamar oracledb.init_oracle_client.

    Por exemplo, no Linux, para estabelecer conexão como o usuário ADMIN usando o nome do 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 estabelecer conexão como o usuário ADMIN usando o nome do 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 'bruta' r"..." significa que barras invertidas são tratadas como separadores de diretório.

Se você estiver protegido por um firewall, poderá encapsular 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.

No modo Thick, você pode 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 de python-oracledb para obter informações sobre o modo Thick.