Documentación de Oracle Cloud Infrastructure

Realizar llamadas externas mediante una cartera gestionada por el cliente

Cuando la instancia de Autonomous Database está en un punto final privado, puede utilizar una cartera gestionada por el cliente con procedimientos en UTL_HTTP, DBMS_LDAP, UTL_SMTP o UTL_TCP. También puede utilizar una cartera gestionada por el cliente cuando el programador envía notificaciones de correo electrónico SMTP para varios eventos relacionados con trabajos del programador.

Tema principal: Desarrollo

Acerca del Uso de Carteras Gestionadas por el Cliente con Llamadas Externas

Cuando la instancia de Autonomous Database está en un punto final privado, puede utilizar una cartera gestionada por el cliente para gestionar llamadas externas o con el programador cuando el programador envía un correo electrónico para varios eventos relacionados con los trabajos del programador.

En Autonomous Database, puede realizar llamadas externas para cualquiera de los siguientes fines:

  • Para utilizar servicios web con UTL_HTTP.

  • Para acceder a los datos desde servidores LDAP mediante DBMS_LDAP.

  • Para enviar un correo electrónico a UTL_SMTP.

  • Para comunicarse con servidores basados en TCP/IP externos mediante TCP/IP con UTL_TCP.

  • Para las notificaciones de correo electrónico del trabajo de Oracle Scheduler.

Por defecto, cuando se utilizan procedimientos en estos paquetes, Autonomous Database mantiene una cartera interna y siempre utiliza conexiones seguras (la cartera gestionada por Oracle contiene más de 90 de los certificados SSL intermedio y raíz de confianza más comunes). Cuando su instancia de Autonomous Database reside en un punto final privado, tiene la opción de utilizar la cartera gestionada por Oracle por defecto con las certificaciones SLL intermedias y de confianza, o bien puede proporcionar una cartera gestionada por el cliente.

Cuando su instancia de Autonomous Database reside en un punto final privado, puede especificar una cartera gestionada por el cliente para UTL_HTTP, UTL_SMTP, DBMS_LDAP y DBMS_NETWORK_ACL_ADMIN mediante los siguientes procedimientos 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

En estas llamadas, según el procedimiento, utilice el parámetro path o wallet_path para especificar una cartera gestionada por el cliente. Defina el directorio de cartera con el prefijo DIR: e incluya una ruta de acceso de cartera. Por ejemplo: 

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

El usuario actual que llama a la API debe tener privilegios READ en el objeto de directorio o tener otorgado el privilegio del sistema CREATE ANY DIRECTORY.

El prefijo DIR: es el formulario preferido que se debe utilizar para especificar una cartera gestionada por el cliente. Además, está soportado el prefijo file:. Por ejemplo: 

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

Consulte Uso de una cartera gestionada por el cliente para llamadas externas con UTL_HTTP para obtener más información:

Acerca del Uso de Carteras Gestionadas por el Cliente con el Servidor de Correo Electrónico del Planificador

El servidor de correo electrónico del programador está disponible para enviar notificaciones de correo electrónico para varios eventos relacionados con el programador, como la notificación de trabajos iniciados, fallidos o completados. Por defecto, el servidor de correo electrónico SMTP del programador utiliza la cartera definida en la propiedad SSL_WALLET para las comunicaciones SSL/TLS. Opcionalmente, puede utilizar una cartera gestionada por el cliente con el servidor de correo electrónico SMTP del programador.

Los siguientes atributos globales admiten el uso de una cartera gestionada por el cliente:

  • EMAIL_SERVER_WALLET_DIRECTORY: se define en un objeto de directorio que especifica la ruta de acceso en la que reside la cartera SSL.

  • EMAIL_SERVER_WALLET_CREDENTIAL: se establece en un objeto de credencial con un par username/password, donde username es cualquier valor y la password es la contraseña de cartera SSL.

Los valores para estos atributos se definen mediante DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE.

Puede obtener más información en los siguientes enlaces:

Requisitos para utilizar una cartera gestionada por el cliente con llamadas externas

Muestra los pasos necesarios para utilizar una cartera gestionada por el cliente con llamadas externas o notificaciones de correo electrónico SMTP del programador.

Realice los pasos previos necesarios:

  1. Verifique que la instancia de Autonomous Database está configurada con un punto final privado.
  2. Defina el parámetro private_target en el valor TRUE cuando otorgue las ACL necesarias con dbms_network_acl_admin.append_wallet_ace o defina ROUTE_OUTBOUND_CONNECTIONS en el valor PRIVATE_ENDPOINT.
  3. Obtenga o cree una cartera gestionada por el cliente.

    Por ejemplo, para crear una cartera con 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: ********
  4. Almacene la cartera en un cubo de Cloud Object Storage.

    Después de obtener o crear la cartera gestionada por el cliente que contiene certificados autofirmados, almacene la cartera en una ubicación de Cloud Object Storage.

Uso de una cartera gestionada por el cliente para llamadas externas con UTL_HTTP

Cuando la instancia de Autonomous Database está en un punto final privado, puede utilizar una cartera gestionada por el cliente para gestionar llamadas externas.

En estos pasos se describe el uso de una cartera gestionada por el cliente con UTL_HTTP. Los pasos son los mismos para los demás paquetes soportados, incluidos: DMBS_LDAP, UTL_SMTP y UTL_TCP.

Realice los pasos necesarios para utilizar una cartera gestionada por el cliente. Consulte Requisitos para utilizar una cartera gestionada por el cliente con llamadas externas para obtener más información.

Para configurar una instancia de Autonomous Database para utilizar una cartera gestionada por el cliente:

  1. Cree una credencial mediante DBMS_CLOUD.CREATE_CREDENTIAL para acceder a Cloud Object Storage.
    BEGIN
  DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'DEF_CRED_NAME',
    username => 'user1@example.com',
    password => 'password'
  );
END;
/

    Los valores que proporcione para username y password dependen del servicio de Cloud Object Storage que utilice.

    Esto crea la credencial que utiliza para acceder a Cloud Object Storage donde reside la cartera gestionada por el cliente.

    No es necesario crear una credencial para acceder al almacén de objetos de Oracle Cloud Infrastructure si activa las credenciales de entidad de recurso. Consulte Uso de la entidad de recurso para acceder a los Recursos de Oracle Cloud Infrastructure para obtener más información.

  2. Utilice un directorio existente o cree un nuevo directorio para el archivo de cartera.

    Por ejemplo:

    CREATE DIRECTORY wallet_dir AS 'directory_path_of_your_choice';

    Consulte Creación de directorio en Autonomous Database para obtener información sobre la creación de directorios.

  3. Utilice DBMS_CLOUD.GET_OBJECT para cargar la cartera gestionada por el cliente en el directorio que ha creado en el paso anterior, WALLET_DIR.

    Por ejemplo:

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

    En este ejemplo, namespace-string es el espacio Oracle Cloud Infrastructure Object Storage Namepace, y bucketname es el nombre del cubo. Consulte Descripción de los espacios de nombres de Object Storage para obtener más información.

  4. Otorgue las ACL necesarias para permitirle leer las credenciales del directorio 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 la ruta de acceso de cartera para utilizarla con procedimientos UTL_HTTP.
    BEGIN
    UTL_HTTP.set_wallet('DIR:WALLET_DIR', 'password');
END;
/

    Para especificar el directorio de cartera con UTL_HTTP.set_wallet puede utilizar el prefijo dir: o el prefijo file:.

    El prefijo dir: solo está disponible en Autonomous Database. Consulte UTL_HTTP para obtener información sobre el prefijo file:.

  6. Ahora puede ejecutar procedimientos UTL_HTTP para acceder a un punto final mediante la cartera gestionada por el cliente con un certificado autofirmado.

    Por ejemplo:

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

Uso de Carteras Gestionadas por el Cliente con Notificaciones por Correo Electrónico del Planificador

Describe los pasos para utilizar el servidor de correo electrónico SMTP del programador con una cartera gestionada por el cliente.

Realice los pasos necesarios para utilizar una cartera gestionada por el cliente. Consulte Requisitos para utilizar una cartera gestionada por el cliente con llamadas externas para obtener más información.

Para utilizar una cartera gestionada por el cliente con el servidor de correo electrónico del programador:

  1. Cree una credencial mediante DBMS_CLOUD.CREATE_CREDENTIAL para acceder a Cloud Object Storage.

    Por ejemplo:

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

    Los valores que proporcione para username y password dependen del servicio de Cloud Object Storage que utilice.

    Esto crea la credencial que utiliza para acceder a Cloud Object Storage donde reside la cartera gestionada por el cliente.

    No es necesario crear una credencial para acceder al almacén de objetos de Oracle Cloud Infrastructure si activa las credenciales de entidad de recurso. Consulte Uso de la entidad de recurso para acceder a los Recursos de Oracle Cloud Infrastructure para obtener más información.

  2. Utilice un directorio existente o cree un nuevo directorio para el archivo de cartera.

    Por ejemplo:

    CREATE DIRECTORY wallet_dir AS 'directory_path_of_your_choice';

    Consulte Creación de directorio en Autonomous Database para obtener información sobre la creación de directorios.

  3. Utilice DBMS_CLOUD.GET_OBJECT para cargar la cartera en el directorio que ha creado en el paso anterior, WALLET_DIR.

    Por ejemplo:

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

    En este ejemplo, namespace-string es el espacio Oracle Cloud Infrastructure Object Storage Namepace, y bucketname es el nombre del cubo. Consulte Descripción de los espacios de nombres de Object Storage para obtener más información.

  4. Ejecute los comandos para configurar el programador para que envíe el correo electrónico SMTP para las notificaciones de trabajos del programador.

    Por ejemplo:

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

    Estos comandos definen el servidor SMTP de correo electrónico del programador, crean el objeto de credencial que contiene las credenciales SMTP y definen el atributo del programador para las credenciales SMTP, y especifican que se utilice TLS para el correo electrónico enviado para la notificación del trabajo del programador.

    Consulte SET_SCHEDULER_ATTRIBUTE Procedure para obtener más información.

  5. Cree una credencial para almacenar la contraseña para la cartera gestionada por el cliente.
    BEGIN
     DBMS_CLOUD.CREATE_CREDENTIAL(
         credential_name  => 'WALLET_CRED',
         username         =>  'any_user', 
         password         => 'password');
END;
/

    Esto crea la credencial que utiliza en el siguiente paso para proporcionar la contraseña para la cartera gestionada por el cliente.

  6. Defina el directorio de cartera del programador y la credencial de cartera.
    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 la vista DBA_SCHEDULER_GLOBAL_ATTRIBUTE para verificar los valores definidos en los pasos 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"

Notas para el Uso de Carteras Gestionadas por el Cliente con Llamadas Externas

Proporciona notas para el uso de una cartera gestionada por el cliente con llamadas externas.

  • Las solicitudes DBMS_CLOUD no respetan la cartera personalizada que ha definido con UTL_HTTP.set_wallet. Esto incluye DBMS_CLOUD.SEND_REQUEST y todo el acceso de almacenamiento de objetos para las tablas externas DBMS_CLOUD que defina con DBMS_CLOUD.CREATE_EXTERNAL_TABLE, DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE o DBMS_CLOUD.CREATE_HYBRID_PART_TABLE. Al realizar una consulta en una tabla externa que ha creado con un procedimiento DBMS_CLOUD, las consultas no respetan la cartera personalizada definida con UTL_HTTP.set_wallet.

  • Las solicitudes APEX_WEB_SERVICE no respetan la cartera personalizada que ha definido con UTL_HTTP.set_wallet.

    Para utilizar una cartera gestionada por el cliente con APEX, especifique el parámetro p_wallet_path en las llamadas a la API APEX_WEB_SERVICE o defina la configuración de la instancia de la ruta de acceso de cartera en los servicios de administración de APEX.

    Consulte Acceso a los servicios de administración de Oracle APEX para obtener más información.

  • Están soportadas las carteras de conexión automática y las carteras protegidas por contraseña. Al utilizar una cartera de conexión automática, especifique NULL para el parámetro wallet_password.

  • El usuario actual que llama a la API UTL_HTTP.set_wallet debe tener privilegios READ en el objeto de directorio o tener otorgado el privilegio del sistema CREATE ANY DIRECTORY.

  • Se permite la API UTL_HTTP.SET_AUTHENTICATION_FROM_WALLET. Consulte SET_AUTHENTICATION_FROM_WALLET Procedure para obtener más información.

  • El prefijo file: está soportado con UTL_HTTP.set_wallet siempre que la ruta de acceso del archivo especificada sea compatible con PATH_PREFIX.

    Puede determinar la conformidad PATH_PREFIX para una ruta de acceso proporcionada como entrada con el procedimiento DBMS_PDB_IS_VALID_PATH (otorgada a PUBLIC, incluido el usuario ADMIN).

    Por ejemplo:

    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 garantizar la compatibilidad con versiones anteriores cuando se utiliza UTL_HTTP.set_wallet, en los casos en los que se ignora la ruta de acceso de cartera, se aceptan valores de entrada como file:, NULL, etc. Estos valores se ignoran y especifican que se utilice la ruta de acceso de cartera SSL por defecto con UTL_HTTP.set_wallet.

  • Están soportadas las API de ACL de cartera DBMS_NETWORK_ACL_ADMIN, como APPEND_WALLET_ACL. Estos procedimientos permiten otorgar/revocar privilegios de ACL de cartera. Consulte DBMS_NETWORK_ACL_ADMIN para obtener más información.

  • Para soportar el uso de las credenciales de contraseña en una cartera SSL para la autenticación, el usuario actual que llama a las API UTL_HTTP debe tener el privilegio de ACL "use-passwords" en la ruta de acceso de cartera.

  • Notas para definir EMAIL_SERVER_WALLET_DIRECTORY y EMAIL_SERVER_WALLET_CREDENTIAL con DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE:

    • Para definir los valores de atributo con DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE, debe ser un usuario administrativo o un usuario con privilegios MANAGE SCHEDULER (el usuario ADMIN tiene estos privilegios).

    • Además del privilegio MANAGE SCHEDULER, el usuario que llama a DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE debe tener el privilegio READ en el objeto de directorio definido con EMAIL_SERVER_WALLET_DIRECTORY y el privilegio EXECUTE en el objeto de credencial definido con EMAIL_SERVER_WALLET_CREDENTIAL.