Estabelecer Conexão com Aplicativos Python Usando mTLS

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

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

A conexão de um aplicativo Python com o 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 Database. O driver pode, opcionalmente, usar bibliotecas do Oracle Client, "modo Thick", para alguma funcionalidade adicional. As bibliotecas do Cliente Oracle podem ser do Oracle Instant Client, do Oracle Client completo, ou de uma instalação do Oracle Database.

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

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

Instalar o Python e o Driver python-oracledb

Para se conectar ao Autonomous AI Database a partir do seu aplicativo Python, instale o Python e o driver python-oracledb.

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

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

Observação: A Oracle recomenda que você se mantenha atualizado com as releases do driver Python e python-oracledb.

Instale o driver python-oracledb do 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 versão principal renomeada do driver cx_Oracle popular.

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

Execute o seguinte comando para atualizar python:

 python -m pip install oracledb --upgrade

Você deverá ver a 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 sobre a instalação do python-oracledb:

Se estiver atrás de 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 de você não ter permissão para gravar em 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 a sua plataforma, a execução de pip fará download do pacote de origem. A origem é compilada e o binário resultante é instalado.

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

Se 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 fino não requer bibliotecas do Oracle Client. No entanto, algumas funcionalidades adicionais estão disponíveis quando o python-oracledb é executado no modo Thick.

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

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

Quando você instala o Oracle Client Software, há diferenças nas versões mínimas necessárias para conexões mTLS e TLS, desta forma:
- Conexões MUTUAL TLS (mTLS):
  - Se o seu banco de dados estiver em um computador remoto, faça download do pacote 'Básico' ou 'Básico' gratuito do Oracle Instant Client para a arquitetura do seu sistema operacional. Use uma versão suportada: Oracle Instant Client: 18.19 (ou posterior), 19.2 (ou posterior) ou 21 (versão base ou posterior).
  - Como alternativa, você pode usar as bibliotecas clientes do Oracle Database Full quando elas estiverem disponíveis no seu sistema (incluindo o Cliente do Oracle Database Full: Oracle Database Client: 18.19 (ou posterior), 19.2 (ou posterior) ou 21 (versão base ou posterior).
- Conexões TLS: Os clientes do OCI (Oracle Call Interface) suportam autenticação TLS se você estiver usando as seguintes versões de cliente:
  - Oracle Instant Client/Oracle Database Client 19.14 (ou mais recente) e 21.5 (ou mais recente) - todas as plataformas
  - Como alternativa, você pode usar as bibliotecas do cliente Full Oracle Database quando elas estiverem disponíveis no seu sistema, incluindo Full Oracle Database Client 19.14 (ou posterior) e 21.5 (ou posterior).

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.

Faça download de um arquivo da wallet da instância do Autonomous AI 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 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: proteja o arquivo wallet.zip e seu conteúdo para impedir o acesso não autorizado ao banco de dados.
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 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:

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

Linux

Por exemplo, no Linux:
```
 /opt/OracleCloud/MYDB
```
Windows

Por exemplo, no Windows:
```
 C:\opt\OracleCloud\MYDB
```
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.
Linux

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)
```
Windows

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. Consulte HTTPS_PROXY no Oracle Database 19c Database Net Services Reference ou no Oracle Database 26ai 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 do python-oracledb estão disponíveis quando o driver é executado no modo Thick.

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 de SSO aberta automaticamente.

Para conectar no modo Grosso:

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 de 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: 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.
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.

Linux

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")
```
Windows

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.

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.

Conteúdo Relacionado

Sobre a Conexão com um Autonomous AI Database Dedicado