Documentación de Oracle Cloud Infrastructure

Realizar llamadas externas con 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 los trabajos del programador.

Tema principal: Desarrollo

Acerca del uso de una cartera gestionada 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 manejar 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 las siguientes finalidades:

  • Para utilizar los servicios web con UTL_HTTP.

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

  • Para enviar un correo electrónico con UTL_SMTP.

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

  • Para notificaciones de correo electrónico de trabajos de Oracle Scheduler.

Por defecto, al utilizar 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 intermedios y raíz de confianza más comunes). Cuando Autonomous Database reside en un punto final privado, tiene la opción de utilizar la cartera gestionada por Oracle por defecto con las certificaciones de SLL de confianza e intermedias, o puede proporcionar una cartera gestionada por el cliente.

Cuando 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 se le debe otorgar el privilegio del sistema CREATE ANY DIRECTORY.

El prefijo DIR: es la forma preferida que se utiliza 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 diversos eventos relacionados con el programador, como la notificación de trabajos iniciados, fallidos o finalizados. 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 soportan 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 define en un objeto de credencial con un par nombre de usuario/contraseña, donde nombre de usuario es cualquier valor y contraseña es la contraseña de cartera SSL.

Defina valores para estos atributos 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 de requisitos para utilizar una cartera gestionada por el cliente con llamadas externas o con notificaciones de correo electrónico SMTP del programador.

Realice los siguientes pasos:

  1. Verifique que la instancia de Autonomous Database está configurada con un punto final privado.

    Consulte Configuración del acceso de red con puntos finales privados para obtener más información.

  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. Obtener o crear 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: ********

    Consulte Gestión de elementos de infraestructura de claves públicas para obtener más información.

  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, guarde 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 manejar 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 admitidos, 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.

    De esta forma, se crea la credencial que utiliza para acceder al almacenamiento de objetos en la nube en el que reside la cartera gestionada por el cliente.

    La creación de una credencial para acceder al almacén de objetos de Oracle Cloud Infrastructure no es necesaria si activa las credenciales de la entidad de recurso. Consulte Uso de la principal 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 directorio nuevo para el archivo de cartera.

    Por ejemplo:

    CREATE DIRECTORY wallet_dir AS 'directory_path_of_your_choice';

    Consulte Creación de directorios 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 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 de nombres de almacenamiento de objetos de Oracle Cloud Infrastructure, 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 que pueda 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 su uso con los 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;

Utilizar una cartera gestionada por el cliente con notificaciones por correo electrónico del programador

Describe los pasos para utilizar el servidor de correo electrónico SMTP del planificador 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. Crear 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.

    De esta forma, se crea la credencial que utiliza para acceder a Cloud Object Storage donde reside la cartera gestionada por el cliente.

    La creación de una credencial para acceder al almacén de objetos de Oracle Cloud Infrastructure no es necesaria si activa las credenciales de la entidad de recurso. Consulte Uso de la principal 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 directorio nuevo para el archivo de cartera.

    Por ejemplo:

    CREATE DIRECTORY wallet_dir AS 'directory_path_of_your_choice';

    Consulte Creación de directorios 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 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 de nombres de almacenamiento de objetos de Oracle Cloud Infrastructure, 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 un 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 establecen el atributo del programador para las credenciales SMTP, y especifican que se debe utilizar TLS para el correo electrónico enviado para la notificación del trabajo del programador.

    Consulte el procedimiento SET_SCHEDULER_ATTRIBUTE para obtener más información.

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

    De esta forma se 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 que ha definido 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 sobre el uso de una cartera gestionada por el cliente con llamadas externas

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

  • Las solicitudes DBMS_CLOUD no respetan la cartera personalizada definida 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 definida con UTL_HTTP.set_wallet.

  • Están soportadas tanto las carteras de conexión automática como las 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 se le debe otorgar el privilegio del sistema CREATE ANY DIRECTORY.

  • La API UTL_HTTP.SET_AUTHENTICATION_FROM_WALLET está permitida. Consulte el procedimiento SET_AUTHENTICATION_FROM_WALLET para obtener más información.

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

    Puede determinar la conformidad PATH_PREFIX para una ruta proporcionada como entrada con el procedimiento DBMS_PDB_IS_VALID_PATH (otorgado 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 al utilizar 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 le 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 de 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.