Fazer Chamadas Externas Usando uma Wallet Gerenciada pelo Cliente

Quando sua instância do Autonomous Database estiver em um ponto final privado, você poderá usar uma wallet gerenciada pelo cliente para tratar chamadas externas ou com o scheduler quando ele enviar e-mail para vários eventos relacionados a jobs do scheduler.

No Autonomous Database, você pode fazer chamadas externas para qualquer uma das seguintes finalidades:

• Para usar serviços Web com o UTL_HTTP.

• Para acessar dados de servidores LDAP usando DBMS_LDAP.

• Para enviar email com UTL_SMTP.

• Para estabelecer comunicação com servidores externos baseados em TCP/IP usando TCP/IP com o UTL_TCP.

• Para notificações de e-mail do job do Oracle Scheduler.

Por padrão, quando você usa procedimentos nesses pacotes, o Autonomous Database mantém uma wallet interna e sempre usa conexões seguras (a wallet gerenciada pela Oracle contém mais de 90 dos certificados SSL intermediários e de raiz confiável mais comuns). Quando o seu Autonomous Database reside em um ponto final privado, você tem a opção de usar a wallet gerenciada pela Oracle padrão com as certificações SLL confiáveis e intermediárias ou pode fornecer uma wallet gerenciada pelo cliente.

Quando o seu Autonomous Database reside em um ponto final privado, você pode especificar uma wallet gerenciada pelo cliente para UTL_HTTP, UTL_SMTP, DBMS_LDAP e DBMS_NETWORK_ACL_ADMIN usando os seguintes procedimentos PL/SQL:

UTL_HTTP.SET_WALLET (
   path                 IN VARCHAR2,
   password             IN VARCHAR2 DEFAULT NULL);
UTL_HTTP.REQUEST (
   wallet_path          IN VARCHAR2 DEFAULT NULL,
   wallet_password      IN VARCHAR2 DEFAULT NULL)
UTL_HTTP.REQUEST_PIECES (
   wallet_p ath         IN VARCHAR2 DEFAULT NULL,
   wallet_password      IN VARCHAR2 DEFAULT NULL,
UTL_HTTP.CREATE_REQUEST_CONTEXT (
 wallet_path            IN VARCHAR2 DEFAULT NULL,
 wallet_password        IN VARCHAR2 DEFAULT NULL)
UTL_TCP.OPEN_CONNECTION
   wallet_path          IN  VARCHAR2 DEFAULT NULL,
   wallet_password      IN  VARCHAR2 DEFAULT NULL);
UTL_SMTP.OPEN_CONNECTION
   wallet_path          IN  VARCHAR2 DEFAULT NULL,
   wallet_password      IN  VARCHAR2 DEFAULT NULL)
DBMS_LDAP.OPEN_SSL(
  sslwrl                IN VARCHAR2,
  sslwalletpasswd       IN VARCHAR2)
DBMS_NETWORK_ACL_ADMIN.APPEND_WALLET_ACE
  wallet_path IN VARCHAR2
DBMS_NETWORK_ACL_ADMIN.APPEND_WALLET_ACL(
  wallet_path IN VARCHAR2

Nessas chamadas, dependendo do procedimento, use o parâmetro path ou wallet_path para especificar uma wallet gerenciada pelo cliente. Defina o diretório da wallet com o prefixo DIR: e inclua um caminho da wallet. Por exemplo:

UTL_HTTP.set_wallet('DIR:WALLET_DIR', 'password');

O usuário atual que está chamando a API deve ter privilégios READ no objeto de diretório ou receber o privilégio de sistema CREATE ANY DIRECTORY.

O prefixo DIR: é o formulário preferencial a ser usado para especificar uma wallet gerenciada pelo cliente. Além disso, o prefixo file: é suportado. Por exemplo:

UTL_HTTP.set_wallet('file:WALLET_DIR/wallet.sso', 'password');

Consulte Usar uma Wallet Gerenciada pelo Cliente para Chamadas Externas com o UTL_HTTP para obter mais informações:

Mostra as etapas de pré-requisito para usar uma wallet gerenciada pelo cliente com chamadas externas ou com notificações por e-mail SMTP do scheduler.

1. Verifique se a instância do Autonomous Database está configurada com um ponto final privado.

   Consulte Configurar o Acesso à Rede com Pontos Finais Privados para mais informações.

2. Defina o parâmetro private_target como o valor TRUE ao conceder as ACLs necessárias com dbms_network_acl_admin.append_wallet_ace ou defina ROUTE_OUTBOUND_CONNECTIONS como o valor PRIVATE_ENDPOINT.

   Consulte Usar uma Wallet Gerenciada pelo Cliente para Chamadas Externas com UTL_HTTP e Segurança Aprimorada para Conexões de Saída com Pontos Finais Privados e para obter mais informações.

3. Obtenha ou crie uma wallet gerenciada pelo cliente.

   Por exemplo, para criar uma wallet com orapki:

   -- Create an SSL Wallet and load the Root CERTs using orapki utility
   $ORACLE_HOME/bin/orapki wallet create -wallet /u01/web/wallet -pwd ********
   $ORACLE_HOME/bin/orapki wallet add -wallet /u01/web/wallet -trusted_cert -cert MyWebServer.cer -pwd ********
   -- Store the credentials in the SSL Wallet using mkstore utility
   $ORACLE_HOME/bin/mkstore -wrl /u01/web/wallet -createCredential secret-from-the-wallet 'example@oracle.com' ********
   Enter wallet password: ********

   Consulte Gerenciando Elementos PKI (Public Key Infrastructure) para obter mais informações.

4. Armazene a wallet em um bucket no Cloud Object Storage.

   Depois de obter ou criar a wallet gerenciada pelo cliente que contém certificados autoassinados, armazene a wallet em um local no Cloud Object Storage.

Quando sua instância do Autonomous Database estiver em um ponto final privado, você poderá usar uma wallet gerenciada pelo cliente para tratar chamadas externas.

1. Crie uma credencial usando DBMS_CLOUD.CREATE_CREDENTIAL para acessar o Cloud Object Storage.

   BEGIN
     DBMS_CLOUD.CREATE_CREDENTIAL(
       credential_name => 'DEF_CRED_NAME',
       username => 'user1@example.com',
       password => 'password'
     );
   END;
   /

   Os valores fornecidos para username e password dependem do serviço de Cloud Object Storage que você está usando.

   Isso cria a credencial usada para acessar o Cloud Object Storage no qual reside a wallet gerenciada pelo cliente.

   Não será necessário criar uma credencial para acessar o Oracle Cloud Infrastructure Object Store se você ativar as credenciais do controlador de recursos. Consulte Usar o Controlador de Recursos para Acessar Recursos da Oracle Cloud Infrastructure para obter mais informações.

2. Use um diretório existente ou crie um novo para o arquivo da wallet.

   Por exemplo:

   CREATE DIRECTORY wallet_dir AS 'directory_path_of_your_choice';
               

   Consulte Criar Diretório no Autonomous Database para obter informações sobre como criar diretórios.

3. Use DBMS_CLOUD.GET_OBJECT para fazer upload da wallet gerenciada pelo cliente para o diretório criado na etapa anterior, WALLET_DIR.

   Por exemplo:

   BEGIN 
       DBMS_CLOUD.GET_OBJECT(
           credential_name => 'DEF_CRED_NAME',
           object_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/cwallet.sso',
           directory_name => 'WALLET_DIR'); 
   END;
   /

   Neste exemplo, namespace-string é o namespace do Oracle Cloud Infrastructure Object Storage e bucketname é o nome do bucket. Consulte Noções Básicas de Namespaces do serviço Object Storage para obter mais informações.

4. Conceda as ACLs necessárias para permitir que você leia as credenciais no diretório especificado.

   BEGIN
     dbms_network_acl_admin.append_wallet_ace(
         wallet_path => 'dir:WALLET_DIR',
         ace         => xs$ace_type(
              privilege_list => xs$name_list('use_client_certificates', 'use_passwords'),
              principal_name => 'USER_NAME',
              principal_type => xs_acl.ptype_db)
       );
   END;
   /

5. Defina o caminho da wallet para uso com procedimentos UTL_HTTP.

   BEGIN
       UTL_HTTP.set_wallet('DIR:WALLET_DIR', 'password');
   END;
   /

   Para especificar o diretório da wallet com UTL_HTTP.set_wallet, você pode usar o prefixo dir: ou o prefixo file:.

   O prefixo dir: só está disponível no Autonomous Database. Consulte UTL_HTTP para obter informações sobre o prefixo file:.

6. Agora você pode executar procedimentos do UTL_HTTP para acessar um ponto final usando a wallet gerenciada pelo cliente com um certificado autoassinado.

   Por exemplo:

   SELECT UTL_HTTP.REQUEST('https://example.com') from dual;

Descreve as etapas para usar o servidor de e-mail SMTP do scheduler com uma wallet gerenciada pelo cliente.

1. Crie uma credencial usando DBMS_CLOUD.CREATE_CREDENTIAL para acessar o Cloud Object Storage.

   Por exemplo:

   BEGIN
     DBMS_CLOUD.CREATE_CREDENTIAL(
       credential_name => 'DEF_CRED_NAME',
       username => 'user1@example.com',
       password => 'password'
     );
   END;
   /

   Os valores fornecidos para username e password dependem do serviço de Cloud Object Storage que você está usando.

   Isso cria a credencial usada para acessar o Cloud Object Storage no qual reside a wallet gerenciada pelo cliente.

   Não será necessário criar uma credencial para acessar o Oracle Cloud Infrastructure Object Store se você ativar as credenciais do controlador de recursos. Consulte Usar o Controlador de Recursos para Acessar Recursos da Oracle Cloud Infrastructure para obter mais informações.

2. Use um diretório existente ou crie um novo para o arquivo da wallet.

   Por exemplo:

   CREATE DIRECTORY wallet_dir AS 'directory_path_of_your_choice';
               

   Consulte Criar Diretório no Autonomous Database para obter informações sobre como criar diretórios.

3. Use DBMS_CLOUD.GET_OBJECT para fazer upload da wallet para o diretório criado na etapa anterior, WALLET_DIR.

   Por exemplo:

   BEGIN 
       DBMS_CLOUD.GET_OBJECT(
           credential_name => 'DEF_CRED_NAME',
           object_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/cwallet.sso',
           directory_name => 'WALLET_DIR'); 
   END;
   /

   Neste exemplo, namespace-string é o namespace do Oracle Cloud Infrastructure Object Storage e bucketname é o nome do bucket. Consulte Noções Básicas de Namespaces do serviço Object Storage para obter mais informações.

4. Execute os comandos para configurar o scheduler e enviar um e-mail SMTP para notificações de job do scheduler.

   Por exemplo:

   BEGIN
       DBMS_SCHEDULER.set_scheduler_attribute('EMAIL_SERVER','smtp.email.us-ashburn-1.oci.oraclecloud.com:587');
       DBMS_CLOUD.create_credential('EMAIL_CRED', 'ocid1.user.oc1..username', 'password');
       DBMS_SCHEDULER.set_scheduler_attribute('EMAIL_SERVER_CREDENTIAL','ADMIN.EMAIL_CRED');
       DBMS_SCHEDULER.set_scheduler_attribute('EMAIL_SERVER_ENCRYPTION','STARTTLS');
   END;
   /

   Esses comandos definem o servidor SMTP de e-mail do scheduler, criam o objeto da credencial que contém as credenciais SMTP e definem o atributo do scheduler para as credenciais SMTP e especificam o uso do TLS para o e-mail enviado para notificação do job do scheduler.

   Consulte SET_SCHEDULER_ATTRIBUTE Procedures para obter mais informações.

5. Crie uma credencial para armazenar a senha da wallet gerenciada pelo cliente.

   BEGIN
        DBMS_CLOUD.CREATE_CREDENTIAL(
            credential_name  => 'WALLET_CRED',
            username         =>  'any_user', 
            password         => 'password');
   END;
   /

   Isso cria a credencial usada na próxima etapa para fornecer a senha da wallet gerenciada pelo cliente.

6. Defina o diretório da wallet do scheduler e a credencial da wallet.

   BEGIN
        DBMS_SCHEDULER.set_scheduler_attribute('EMAIL_SERVER_WALLET_DIRECTORY','WALLET_DIR'); 
        DBMS_SCHEDULER.set_scheduler_attribute('EMAIL_SERVER_WALLET_CREDENTIAL', 'ADMIN.WALLET_CRED');
   END;
   /

7. Consulte a exibição DBA_SCHEDULER_GLOBAL_ATTRIBUTE para verificar os valores definidos nas etapas anteriores.

   SELECT attribute_name, value
          FROM DBA_SCHEDULER_GLOBAL_ATTRIBUTE
          WHERE attribute_name LIKE 'EMAIL_SERVER%' ORDER BY 1, 2;

   ATTRIBUTE_NAME                 VALUE
   ------------------------------ -----------------------------------------------
   EMAIL_SERVER                   smtp.email.us-ashburn-1.oci.oraclecloud.com:587
   EMAIL_SERVER_CREDENTIAL        "ADMIN"."EMAIL_CRED"
   EMAIL_SERVER_ENCRYPTION        STARTTLS
   EMAIL_SERVER_WALLET_CREDENTIAL "ADMIN"."WALLET_CRED"
   EMAIL_SERVER_WALLET_DIRECTORY  "WALLET_DIR"

Fornece observações para usar uma wallet gerenciada pelo cliente com chamadas externas.

• As solicitações DBMS_CLOUD não respeitam a wallet personalizada definida com UTL_HTTP.set_wallet. Isso inclui DBMS_CLOUD.SEND_REQUEST e todo o acesso ao armazenamento de objetos para tabelas externas DBMS_CLOUD que você define com DBMS_CLOUD.CREATE_EXTERNAL_TABLE, DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE ou DBMS_CLOUD.CREATE_HYBRID_PART_TABLE. Quando você executa uma consulta em uma tabela externa que criou com um procedimento DBMS_CLOUD, as consultas não respeitam a wallet personalizada definida com UTL_HTTP.set_wallet.

• As solicitações APEX_WEB_SERVICE não respeitam a wallet personalizada definida com UTL_HTTP.set_wallet.

  Para usar uma wallet gerenciada pelo cliente com o APEX, especifique o parâmetro p_wallet_path em chamadas de API APEX_WEB_SERVICE ou defina a definição de instância do Caminho da Wallet no APEX Administration Services.

  Consulte Acessar o Oracle APEX Administration Services para obter mais informações.

• Tanto carteiras de login automático quanto carteiras protegidas por senha são suportadas. Ao usar uma wallet de log-in automático, especifique NULL para o parâmetro wallet_password.

• O usuário atual que está chamando a API UTL_HTTP.set_wallet deve ter privilégios READ no objeto de diretório ou receber o privilégio de sistema CREATE ANY DIRECTORY.

• A API UTL_HTTP.SET_AUTHENTICATION_FROM_WALLET é permitida. Consulte SET_AUTHENTICATION_FROM_WALLET Procedures para obter mais informações.

• O prefixo file: é suportado com UTL_HTTP.set_wallet, desde que o caminho de arquivo especificado seja compatível com PATH_PREFIX.

  Você pode determinar a conformidade de PATH_PREFIX para um caminho fornecido como entrada com o procedimento DBMS_PDB_IS_VALID_PATH (concedido a PUBLIC, incluindo o usuário ADMIN).

  Por exemplo:

  with function check_path_prefix_compliance(file_path varchar2)
    return varchar2 as
  BEGIN
    if dbms_pdb_is_valid_path(file_path) then
      return 'YES';
    else
      return 'NO';
    end if;
  END;
  SELECT
    check_path_prefix_compliance('/u03/dbfs/1276CDexample/data/dpdump') as PATH_PREFIX_COMPLIANT,
    check_path_prefix_compliance('/u01/app/oracle/diag') as PATH_PREFIX_COMPLIANT
  FROM
    dual;
  /

• Para garantir a compatibilidade com versões anteriores quando você usa UTL_HTTP.set_wallet, nos casos em que o caminho da wallet é ignorado, os valores de entrada, como file:, NULL etc., são aceitos. Esses valores são ignorados e especificados para usar o caminho da wallet SSL padrão com UTL_HTTP.set_wallet.

• As APIs ACL da wallet DBMS_NETWORK_ACL_ADMIN, como APPEND_WALLET_ACL, são suportadas. Esses procedimentos permitem conceder/revogar privilégios de ACL da wallet. Consulte DBMS_NETWORK_ACL_ADMIN para obter mais informações.

• Para suportar o uso das credenciais de senha em uma wallet SSL para autenticação, o usuário atual que chama APIs UTL_HTTP deve ter o privilégio ACL "use-passwords" no caminho da wallet.

• Observações para definir EMAIL_SERVER_WALLET_DIRECTORY e EMAIL_SERVER_WALLET_CREDENTIAL com DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE:

  • Para definir os valores de atributo com DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE, você deve ser um usuário administrativo ou um usuário com privilégios MANAGE SCHEDULER (o usuário ADMIN tem esses privilégios).

  • Além do privilégio MANAGE SCHEDULER, o usuário que está chamando DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE deve ter o privilégio READ no objeto de diretório definido com EMAIL_SERVER_WALLET_DIRECTORY e o privilégio EXECUTE no objeto de credencial definido com EMAIL_SERVER_WALLET_CREDENTIAL.