Documentação do Oracle Cloud Infrastructure

Fazer Chamadas Externas Usando uma Wallet Gerenciada pelo Cliente

Quando sua instância do Autonomous AI Database estiver em um ponto final privado, você poderá usar uma wallet gerenciada pelo cliente com procedimentos em UTL_HTTP, DBMS_LDAP, UTL_SMTP ou UTL_TCP. Você também pode usar uma wallet gerenciada pelo cliente quando o scheduler envia notificações por e-mail SMTP para vários eventos relacionados a jobs do scheduler.

Sobre o Uso de uma Wallet Gerenciada pelo Cliente com Chamadas Externas

Quando sua instância do Autonomous AI 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 AI 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 AI 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 Autonomous AI 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 seu Autonomous AI 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 UTL_HTTP para obter mais informações:

Sobre o Uso de uma Wallet Gerenciada pelo Cliente com o Scheduler Email Server

O servidor de e-mail do scheduler está disponível para enviar notificações por e-mail sobre vários eventos relacionados ao scheduler, como notificação de jobs iniciados, com falha ou concluídos. Por padrão, o servidor de e-mail SMTP do scheduler usa a wallet definida na propriedade SSL_WALLET para comunicações SSL/TLS. Opcionalmente, você pode usar uma wallet gerenciada pelo cliente com o servidor de e-mail SMTP do scheduler.

Os seguintes atributos globais suportam o uso de uma wallet gerenciada pelo cliente:

  • EMAIL_SERVER_WALLET_DIRECTORY: é definido como um objeto de diretório que especifica o caminho no qual reside a wallet SSL.

  • EMAIL_SERVER_WALLET_CREDENTIAL: é definido como um objeto de credencial com um par nome de usuário/senha, em que o nome de usuário é qualquer valor e a senha é a senha da wallet SSL.

Você define valores para esses atributos usando DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE.

Para obter mais informações, consulte:

Pré-requisitos para Usar uma Wallet Gerenciada pelo Cliente com Chamadas Externas

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.

Execute as etapas de pré-requisito:

  1. Verifique se a instância do Autonomous AI 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 valor TRUE ao conceder as ACLs necessárias com dbms_network_acl_admin.append_wallet_ace ou defina a propriedade do banco de dados ROUTE_OUTBOUND_CONNECTIONS.

    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.

Usar uma Wallet Gerenciada pelo Cliente para Chamadas Externas com o UTL_HTTP

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

Estas etapas descrevem o uso de uma wallet gerenciada pelo cliente com UTL_HTTP. As etapas são as mesmas para os outros pacotes suportados, incluindo: DMBS_LDAP, UTL_SMTP e UTL_TCP.

Execute as etapas de pré-requisito para usar uma wallet gerenciada pelo cliente. Consulte Pré-requisitos para Usar uma Wallet Gerenciada pelo Cliente com Chamadas Externas para obter mais informações.

Para configurar um Autonomous AI Database para usar uma wallet gerenciada pelo cliente:

  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 AI 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 AI 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;

Usar uma Wallet Gerenciada pelo Cliente com Notificações por E-mail do Scheduler

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

Execute as etapas de pré-requisito para usar uma wallet gerenciada pelo cliente. Consulte Pré-requisitos para Usar uma Wallet Gerenciada pelo Cliente com Chamadas Externas para obter mais informações.

Para usar uma wallet gerenciada pelo cliente com o servidor de e-mail do scheduler:

  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 AI 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 Procedimento SET_SCHEDULER_ATTRIBUTE 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"

Observações para Usar uma Wallet Gerenciada pelo Cliente com Chamadas Externas

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 as carteiras de login automático quanto as 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 Procedimento SET_AUTHENTICATION_FROM_WALLET 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.