Documentação do Oracle Cloud Infrastructure

Conexões JDBC Thin com uma Wallet (mTLS)

O Autonomous Database exige uma conexão segura que use o TLSv1.2 (Transport Layer Security). Dependendo das opções de configuração de rede, o Autonomous Database suporta autenticação mTLS e TLS.

Observação

Se você usar TLS, em vez de mTLS, para suas conexões usando o Driver JDBC Thin com JDK8u162 ou superior, não será necessária uma wallet. Conexões TLS são ativadas para as seguintes configurações de rede:



  • Somente acesso ao ponto final privado: configuração de rede com um ponto final privado

  • Acesso seguro somente de IPs e VCNs permitidos: configuração com uma ACL (Lista de Controle de Acesso)

    Se o seu Autonomous Database estiver em um ponto final público sem qualquer ACL, você poderá adicionar 0.0.0.0/0 como sua ACL CIDR e ativar a autenticação TLS. A adição de 0.0.0.0/0 como sua ACL CIDR é idêntica a ter seu Autonomous Database no ponto final público sem ACL.

Consulte Conexões Seguras com o Autonomous Database com mTLS ou com TLS para obter mais informações.

Tópico principal: Estabelecer Conexão com o Driver JDBC Thin

Conexões de Pré-requisitos de Conexão do Driver JDBC Thin com Wallets (mTLS)

Os aplicativos que usam o driver JDBC Thin suportam autenticação TLS e mTLS (TLS mútuo). O uso da autenticação mTLS requer que você forneça credenciais do banco de dados Oracle, incluindo as wallets Oracle ou os arquivos JKS (Java KeyStore) ao estabelecer conexão com o banco de dados.

Execute as seguintes etapas antes de estabelecer conexão com o banco de dados:

  1. Provisionar o Autonomous Database: Crie um banco de dados e obtenha suas credenciais de banco de dados (nome de usuário e senha).
  2. Para conexões TLS mútuas, Fazer Download de Credenciais do Cliente: Descompacte o wallet_databasename.zip em um local seguro. Certifique-se de que apenas usuários autorizados tenham acesso a esses arquivos.

    Consulte Fazer Download de Credenciais do Cliente (Wallets) para mais informações sobre como fazer download de credenciais de cliente para o Autonomous Database.

  3. Verificar sua versão do JDK para fins de segurança: Se você estiver usando JDK11, JDK10 ou JDK9, não precisará fazer nada para esta etapa. Se sua versão do JDK for menor que JDK8u162, você precisará fazer download dos Arquivos de Política de Jurisdição de Força Ilimitada do JCE. Consulte o arquivo README para obter notas de instalação. Faça download dos arquivos JCE no Download do Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 8.
  4. Verificar Versão do Driver JDBC: Faça download de um driver JDBC Thin suportado (ojdbc8.jar e ucp.jar). Você também precisa dos jars adicionais: oraclepki.jar, osdt_core.jar e osdt_cert.jar para uso com wallets Oracle.

    As versões com suporte são:

    • JDBC Thin: 11.2.0.4 (ou posterior com patch one-off para o Bug 28492769), 12.2 (ou posterior com patch one-off para o Bug 28492769), 18 (versão base ou posterior com patch one-off para o Bug 28492769), 19 (versão base ou posterior) ou 21 (versão base ou posterior)

    Para aplicativos que usam o recurso Universal Connection Pool (UCP) do JDBC, é altamente recomendável usar as versões 19.13 ou superior ou 21.3 ou superior do driver JDBC. Essas versões incluem um comportamento de drenagem adequado para minimizar o impacto nos aplicativos quando a manutenção planejada é executada no Autonomous Database. O UCP reabastecerá as conexões no pool de forma proativa para que as conexões ativas não sejam afetadas pela manutenção.

    Para versões anteriores do driver, um patch para o bug 31112088 também pode ser solicitado preenchendo uma Solicitação de serviço.

    Faça download das versões suportadas: Downloads do driver JDBC do Oracle Database e Jars Companion.

Usando uma String de Conexão de URL JDBC com Driver e Wallets JDBC Thin

A string de conexão é encontrada no arquivo tnsnames.ora, que faz parte do download das credenciais do cliente. O arquivo tnsnames.ora contém os nomes de serviço predefinidos. Cada serviço tem seu próprio alias TNS e string de conexão.

Veja a seguir um exemplo de entrada, com dbname_high como alias TNS e uma string de conexão em tnsnames.ora:
dbname_high= (description=
      (address=(protocol=tcps)(port=1522)(host=adb.example.oraclecloud.com))
      (connect_data=(service_name=dbname_high.oraclecloud.com))(security=(ssl_server_dn_match=yes)))

Defina o local de tnsnames.ora com a propriedade TNS_ADMIN de uma das seguintes maneiras:

  • Como parte da string de conexão (somente com o driver JDBC 18.3 ou mais recente)
  • Como uma propriedade do sistema, -Doracle.net.tns_admin
  • Como propriedade de conexão (OracleConnection.CONNECTION_PROPERTY_TNS_ADMIN)

Usando o driver JDBC 18.3, a string de conexão inclui o alias TNS e a propriedade de conexão TNS_ADMIN.

Amostra de string de conexão usando o driver JDBC 18.3 (Linux):

DB_URL="jdbc:oracle:thin:@dbname_high?TNS_ADMIN=/Users/test/wallet_dbname"

Amostra de string de conexão usando o driver JDBC 18.3 (Windows):

DB_URL="jdbc:oracle:thin:@dbname_high?TNS_ADMIN=C:\\Users\\test\\wallet_dbname"

A propriedade de conexão TNS_ADMIN especifica o seguinte:

  • O local do tnsnames.ora.
  • O local dos arquivos Oracle Wallet (ewallet.sso, ewallet.p12) ou Java KeyStore (JKS) (truststore.jks, keystore.jks).
  • O local do ojdbc.properties. Esse arquivo contém as propriedades de conexão necessárias para usar o Oracle Wallets ou o Java KeyStore (JKS).
Observação

Se você estiver usando drivers JDBC 12.2.0.1 ou mais antigos, a string de conexão conterá apenas o alias TNS. Para estabelecer conexão usando drivers JDBC mais antigos:

  • Defina o local do tnsnames.ora, como uma propriedade do sistema com -Doracle.net.tns_admin ou como uma propriedade de conexão (OracleConnection.CONNECTION_PROPERTY_TNS_ADMIN).
  • Defina as propriedades de conexão relacionadas à wallet ou JKS além de TNS_ADMIN.

Por exemplo, nesse caso, você define o alias TNS no DB_URL sem a parte TNS_ADMIN como: 

DB_URL=”jdbc:oracle:thin:@dbname_high”

Consulte Nomes de Serviço de Banco de Dados para Autonomous Database para ver mais detalhes.

Usando uma Conexão JDBC com o Driver JDBC 18.3

Os aplicativos que usam o driver JDBC Thin podem se conectar a Autonomous Databases usando o Oracle Wallets ou o Java KeyStore (JKS).

Usando o Oracle Wallet

Para usar o Java e o Driver Thin JDBC 18.3 para estabelecer conexão com o Autonomous Database com o Oracle Wallet, faça o seguinte:

  1. Certifique-se de que os pré-requisitos sejam atendidos: Consulte Conexões de Pré-requisitos de Conexão do Driver Thin JDBC com Wallets (mTLS) para obter mais informações.

  2. Verificar a conexão: Você pode usar um programa Java, um servlet ou IDEs para verificar a conexão com o banco de dados. Um teste simples é fazer download de DataSourceSample.java ou UCPSample.java em amostras de código JDBC e atualizar o URL de conexão para ter o alias TNS necessário e informar TNS_ADMIN, fornecendo o caminho para tnsnames.ora e os arquivos da wallet. Além disso, na amostra de código-fonte, atualize o nome de usuário e a senha do banco de dados. Por exemplo: 

    DB_URL="jdbc:oracle:thin:@dbname_high?TNS_ADMIN=/Users/test/wallet_dbname"
    Observação

    Se você estiver usando o Microsoft Active Directory com um banco de dados, na amostra de código-fonte, atualize o nome de usuário com o nome de usuário do Active Directory e atualize a senha com a senha de usuário do Active Directory. Consulte Usar o Microsoft Active Directory com o Autonomous Database para obter mais informações.

  3. Definir a localização da wallet: O arquivo de propriedades ojdbc.properties é pré-carregado com a propriedade de conexão relacionada à wallet. 

    oracle.net.wallet_location=(SOURCE=(METHOD=FILE)(METHOD_DATA=(DIRECTORY=${TNS_ADMIN})))
    Observação

    Você não modifica o arquivo ojdbc.properties. O valor de TNS_ADMIN determina o local da wallet.

  4. Compilar e Executar: Compile e execute a amostra para obter uma conexão bem-sucedida. Certifique-se de ter oraclepki.jar , osdt_core.jar e osdt_cert.jar, no classpath. Por exemplo: 

    java –classpath
      ./lib/ojdbc8.jar:./lib/ucp.jar:./lib/oraclepki.jar:./lib/osdt_core.jar:./lib/osdt_cert.jar:. UCPSample
Observação

A parte da wallet de log-in automático do arquivo zip de credenciais do cliente submetido a download do Autonomous Database elimina a necessidade de seu aplicativo usar a autenticação de nome de usuário/senha.

Usando o Java KeyStore

Para usar o Java e o Driver Thin JDBC 18.3 para estabelecer conexão com o Autonomous Database com o Java KeyStore (JKS), faça o seguinte:

  1. Certifique-se de que os pré-requisitos sejam atendidos: Consulte Conexões de Pré-requisitos de Conexão do Driver Thin JDBC com Wallets (mTLS) para obter mais informações.

  2. Pronto para os detalhes do banco de dados: Você pode usar um programa Java, um servlet ou IDEs para verificar a conexão com seu banco de dados. Um teste simples é fazer download de DataSourceSample.java ou UCPSample.java em amostras de código JDBC. Nesta amostra, use o URL de conexão conforme mostrado. Observe que a conexão DB_URL contém o alias TNS, por exemplo, dbname_high presente em tnsnames.ora. Você pode fornecer o caminho para o arquivo tnsnames.ora por meio da propriedade TNS_ADMIN, conforme mostrado no URL. Certifique-se de usar o nome de usuário e a senha do banco de dados relacionados ao banco de dados. 

    DB_URL="jdbc:oracle:thin:@dbname_high?TNS_ADMIN=/Users/test/wallet_dbname"
    Observação

    Se você estiver usando o Microsoft Active Directory com o Autonomous Database, certifique-se de alterar o código-fonte de amostra para usar o nome de usuário do Active Directory e a senha de usuário do Active Directory. Consulte Usar o Microsoft Active Directory com o Autonomous Database para obter mais informações.

  3. Definir propriedades de conexão relacionadas a JKS: Adicione as propriedades de conexão relacionadas a JKS ao arquivo ojdbc.properties. A senha keyStore e a senha do armazenamento confiável são a senha especificada quando você faz download do arquivo .zip de credenciais do cliente.

    Para usar a conectividade SSL em vez do Oracle Wallet, especifique os arquivos de armazenamento de chaves e armazenamento confiável e sua respectiva senha no arquivo ojdbc.properties da seguinte forma: 

    
# Properties for using Java KeyStore (JKS)
oracle.net.ssl_server_dn_match=true
javax.net.ssl.trustStore==${TNS_ADMIN}/truststore.jks
javax.net.ssl.trustStorePassword=password
javax.net.ssl.keyStore==${TNS_ADMIN}/keystore.jks
javax.net.ssl.keyStorePassword=password
    Observação

    Não deixe de comentar a propriedade relacionada à wallet em ojdbc.properties. Por exemplo:
    
# Property for using Oracle Wallets
# oracle.net.wallet_location=(SOURCE=(METHOD=FILE)(METHOD_DATA=(DIRECTORY=${TNS_ADMIN})))

  4. Compilar e Executar: Compile e execute a amostra para obter uma conexão bem-sucedida. Por exemplo: 

    java –classpath ./lib/ojdbc8.jar:./lib/ucp.jar UCPSample

Estabelecendo Conexão Usando o JDBC Thin Driver 12.2 ou Mais Antigo

Se você estiver usando o driver JDBC 12.2.0.2 ou mais antigo, defina as propriedades do Java antes de iniciar o aplicativo. Geralmente, você define as propriedades no script de inicialização do aplicativo.

Se você não conseguir usar os drivers JDBC mais recentes, poderá estabelecer conexão com o Autonomous Database usando o 12.2.0.2 ou outros drivers JDBC mais antigos. Os drivers JDBC 12.2 ou mais antigos não suportam o arquivo ojdbc.properties. Com versões mais antigas do driver JDBC, você precisa passar wallets ou propriedades relacionadas a JKS como propriedades do sistema ou como propriedades de conexão para estabelecer uma conexão.

Usando o Oracle Wallet

Para usar o Java e os Drivers JDBC 12.2 ou mais antigos para estabelecer conexão com o Autonomous Database com o Oracle Wallet, faça o seguinte:

  1. Certifique-se de que os pré-requisitos sejam atendidos: Consulte Conexões de Pré-requisitos de Conexão do Driver Thin JDBC com Wallets (mTLS) para obter mais informações.

  2. Verificar a conexão: Você pode usar um programa Java, um servlet ou IDEs para verificar a conexão com o banco de dados. Um teste simples é fazer download de DataSourceSample.java ou UCPSample.java em amostras de código JDBC e atualizar o URL de conexão para ter o alias de TNS necessário. Além disso, atualize o código-fonte de amostra para usar o nome de usuário e a senha do banco de dados. Por exemplo: 

    DB_URL="jdbc:oracle:thin:@dbname_high”
    Observação

    Se você estiver usando o Microsoft Active Directory com o Autonomous Database, atualize o código-fonte de amostra para usar o nome de usuário do Active Directory e a senha do usuário do Active Directory. Consulte Usar o Microsoft Active Directory com o Autonomous Database para obter mais informações.

  3. Definir o local da wallet: Adicione o OraclePKIProvider no final da lista de provedores no arquivo java.security (esse arquivo faz parte da instalação do JRE localizada em $JRE_HOME/jre/lib/security/java.security) que geralmente se parece com: 

    security.provider.14=oracle.security.pki.OraclePKIProvider

  4. Compilar e Executar: Compile e execute a amostra para obter uma conexão bem-sucedida. Certifique-se de ter oraclepki.jar , osdt_core.jar e osdt_cert.jar, no classpath. Além disso, você precisa passar as propriedades de conexão. Atualize as propriedades com o local em que os arquivos tnsnames.ora e da wallet estão localizados. 

    java –classpath 
./lib/ojdbc8.jar:./lib/ucp.jar:./lib/oraclepki.jar:./lib/osdt_core.jar:./lib/osdt_cert.jar:.
-Doracle.net.tns_admin=/users/test/wallet_dbname  
-Doracle.net.ssl_server_dn_match=true  
-Doracle.net.ssl_version=1.2  (Not required for 12.2)
-Doracle.net.wallet_location= “(SOURCE=(METHOD=FILE)(METHOD_DATA=(DIRECTORY=/users/test/wallet_dbname)))” 
UCPSample
Observação

Estes são exemplos de sistema do Windows. Adicione um caractere de continuação \ se estiver definindo propriedades –D em várias linhas no UNIX (Linux ou Mac).

Usando o Java KeyStore

Para usar o Java e os Drivers JDBC Thin 12.2 ou mais antigos para estabelecer conexão com o Autonomous Database com o Java KeyStore (JKS), faça o seguinte:

  1. Certifique-se de que os pré-requisitos sejam atendidos: Consulte Conexões de Pré-requisitos de Conexão do Driver Thin JDBC com Wallets (mTLS) para obter mais informações.

  2. Verificar a conexão: Você pode usar um programa Java, um servlet ou IDEs para verificar a conexão com o banco de dados. Um teste simples é fazer download de DataSourceSample.java ou UCPSample.java em amostras de código JDBC e atualizar o URL de conexão para ter o alias de TNS necessário e informar TNS_ADMIN, fornecendo o caminho para tnsnames.ora e atualizando o URL de conexão para ter o alias de TNS necessário. Além disso, na amostra de código-fonte, atualize o nome de usuário e a senha do banco de dados. Por exemplo: 

    DB_URL="jdbc:oracle:thin:@dbname_high”
    Observação

    Se você estiver usando o Microsoft Active Directory com o Autonomous Database, atualize o código-fonte de amostra para usar o nome de usuário do Active Directory e a senha do usuário do Active Directory. Consulte Usar o Microsoft Active Directory com o Autonomous Database para obter mais informações.

  3. Compilar e Executar: Compile e execute a amostra para obter uma conexão bem-sucedida. Você precisa informar as propriedades de conexão conforme mostrado. Atualize as propriedades com o local onde os arquivos tnsnames.ora e JKS são colocados. Se quiser especificar essas propriedades de conexão de forma programática, consulte DataSourceForJKS.java. Por exemplo: 

    java 
-Doracle.net.tns_admin=/users/test/wallet_dbname
-Djavax.net.ssl.trustStore=truststore.jks
-Djavax.net.ssl.trustStorePassword=**********
-Djavax.net.ssl.keyStore=keystore.jks    
-Djavax.net.ssl.keyStorePassword=************   
-Doracle.net.ssl_server_dn_match=true    
-Doracle.net.ssl_version=1.2 // Not required for 12.2

Conexões JDBC Thin com um Proxy HTTP

Se o cliente estiver protegido por um firewall e sua configuração de rede exigir que um proxy HTTP se conecte à internet, você precisará usar o JDBC Thin Client 18.1 ou superior, que ativa conexões por meio de proxies HTTP.

Para estabelecer conexão com o Autonomous Database por meio de um proxy HTTPS, abra e atualize seu arquivo tnsnames.ora. Adicione o nome do host do proxy HTTP (https_proxy) e a porta (https_proxy_port) à string de conexão. Substitua os valores pelas informações de proxy HTTPS. Por exemplo:

  1. Adicione o nome de host e a porta do proxy HTTP às definições de conexão no tnsnames.ora. Você precisa adicionar os parâmetros https_proxy e https_proxy_port na seção de endereço das definições de conexão. Por exemplo, o seguinte define o proxy HTTP como proxyhostname e a porta do proxy HTTP como 80; substitua esses valores pelas informações do proxy HTTP: 

db2022adb_high =
       (description=
             (address=
                   (https_proxy=proxyhostname)(https_proxy_port=80)(protocol=tcps)(port=1522)(host=adb.example.oraclecloud.com)
             )
             (connect_data=(service_name=db2022adb_high.adb.oraclecloud.com)
             )
             (security=security=(ssl_server_dn_match=yes)
             )
       )
Observação

  • As versões do cliente JDBC Thin anteriores à versão 18.1 não suportam conexões por meio do proxy HTTP.

  • A conexão bem-sucedida depende de configurações de proxy específicas e o desempenho das transferências de dados dependerá da capacidade do proxy. A Oracle não recomenda o uso desse recurso em ambientes de Produção nos quais o desempenho é crítico.

  • A configuração do tnsnames.ora para o proxy HTTP pode não ser suficiente, dependendo da configuração de rede e das políticas da sua organização. Por exemplo, algumas redes exigem um nome de usuário e uma senha para o proxy HTTP.

  • Em todos os casos, entre em contato com o administrador da rede para abrir conexões de saída com hosts no domínio oraclecloud.com usando a porta relevante sem passar por um proxy HTTP.