Effectuer des appels externes à l'aide d'un portefeuille géré par le client

Lorsque votre instance de base de données Autonomous AI Database se trouve sur un point d'extrémité privé, vous pouvez utiliser un portefeuille géré par le client pour gérer les appels externes, ou avec le programmateur lorsque le programmateur envoie des courriels pour divers événements liés aux tâches du programmateur.

Sur Autonomous AI Database, vous pouvez effectuer des appels externes à l'une des fins suivantes :

• Pour utiliser les services Web avec UTL_HTTP.

• Pour accéder aux données des serveurs LDAP à l'aide de DBMS_LDAP.

• Pour envoyer un courriel à UTL_SMTP.

• Pour communiquer avec des serveurs TCP/IP externes à l'aide de TCP/IP avec UTL_TCP.

• Pour les avis par courriel de tâche d'Oracle Scheduler.

Par défaut, lorsque vous utilisez des procédures dans ces packages, Autonomous AI Database gère un portefeuille interne et utilise toujours des connexions sécurisées (le portefeuille géré par Oracle contient plus de 90 des certificats SSL racine et intermédiaire de confiance les plus courants). Lorsque votre base de données Autonomous AI Database réside sur un point d'extrémité privé, vous avez la possibilité d'utiliser le portefeuille géré par Oracle par défaut avec les certifications SLL fiables et intermédiaires, ou vous pouvez fournir un portefeuille géré par le client.

Lorsque votre base de données d'intelligence artificielle autonome réside sur un point d'extrémité privé, vous pouvez spécifier un portefeuille géré par le client pour UTL_HTTP, UTL_SMTP, DBMS_LDAP et DBMS_NETWORK_ACL_ADMIN à l'aide des procédures PL/SQL suivantes :

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

Dans ces appels, selon la procédure, utilisez le paramètre path ou wallet_path pour spécifier un portefeuille géré par le client. Vous définissez le répertoire de portefeuille avec le préfixe DIR: et incluez un chemin d'accès au portefeuille. Exemple :

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

L'utilisateur courant qui appelle l'API doit disposer des privilèges READ sur l'objet de répertoire ou disposer du privilège système CREATE ANY DIRECTORY.

Le préfixe DIR: est le formulaire privilégié à utiliser pour spécifier un portefeuille géré par le client. En outre, le préfixe file: est pris en charge. Exemple :

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

Pour plus d'informations, voir Utiliser un portefeuille géré par le client pour les appels externes avec UTL_HTTP :

Affiche les étapes préalables à l'utilisation d'un portefeuille géré par le client avec des appels externes ou avec des avis par courriel SMTP du programmateur.

1. Vérifiez que l'instance de base de données de l'IA autonome est configurée avec un point d'extrémité privé.

   Pour plus d'informations, voir Configurer l'accès au réseau à l'aide de points d'extrémité privés.

2. Réglez le paramètre private_target à la valeur TRUE lorsque vous accordez les listes de contrôle d'accès requises avec dbms_network_acl_admin.append_wallet_ace ou réglez ROUTE_OUTBOUND_CONNECTIONS à la valeur PRIVATE_ENDPOINT.

   Voir Utiliser un portefeuille géré par le client pour les appels externes avec UTL_HTTP et Sécurité améliorée pour les connexions sortantes avec des points d'extrémité privés et pour plus d'informations.

3. Obtenez ou créez un portefeuille géré par le client.

   Par exemple, pour créer un portefeuille avec 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: ********

   Pour plus d'informations, voir Gestion des éléments d'infrastructure à clé publique.

4. Stockez le portefeuille dans un seau du service de stockage d'objets en nuage.

   Après avoir obtenu ou créé le portefeuille géré par le client contenant des certificats auto-signés, stockez le portefeuille dans un emplacement du service de stockage d'objets en nuage.

Lorsque votre instance de base de données Autonomous AI Database se trouve sur un point d'extrémité privé, vous pouvez utiliser un portefeuille géré par le client pour gérer les appels externes.

1. Créez des données d'identification à l'aide de DBMS_CLOUD.CREATE_CREDENTIAL pour accéder au service de stockage d'objets en nuage.

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

   Les valeurs que vous indiquez pour username et password dépendent du service de stockage d'objets en nuage que vous utilisez .

   Les données d'identification que vous utilisez pour accéder au service de stockage d'objets en nuage où réside le portefeuille géré par le client.

   La création de données d'identification pour accéder au magasin d'objets Oracle Cloud Infrastructure n'est pas requise si vous activez les données d'identification du principal de ressource. Pour plus d'informations, voir Utiliser un principal de ressource pour accéder aux ressources Oracle Cloud Infrastructure.

2. Utilisez un répertoire existant ou créez-en un nouveau pour le fichier de portefeuille.

   Exemple :

   CREATE DIRECTORY wallet_dir AS 'directory_path_of_your_choice';
               

   Voir Créer un répertoire dans Autonomous AI Database pour plus d'informations sur la création de répertoires.

3. Utilisez DBMS_CLOUD.GET_OBJECT pour charger le portefeuille géré par le client dans le répertoire que vous avez créé à l'étape précédente, WALLET_DIR.

   Exemple :

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

   Dans cet exemple, namespace-string est l'espace de noms du stockage d'objets pour Oracle Cloud Infrastructure et bucketname est le nom du seau. Pour plus d'informations, voir Présentation des espaces de noms du stockage d'objets.

4. Accordez les listes de contrôle d'accès requises pour vous permettre de lire les données d'identification à partir du répertoire spécifié.

   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. Définissez le chemin du portefeuille à utiliser avec les procédures UTL_HTTP.

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

   Pour spécifier le répertoire de portefeuille avec UTL_HTTP.set_wallet, vous pouvez utiliser le préfixe dir: ou le préfixe file:.

   Le préfixe dir: n'est disponible que dans la base de données d'intelligence artificielle autonome. Voir UTL_HTTP pour plus d'informations sur le préfixe file:.

6. Vous pouvez maintenant exécuter des procédures UTL_HTTP pour accéder à un point d'extrémité à l'aide du portefeuille géré par le client avec un certificat auto-signé.

   Exemple :

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

Décrit les étapes à suivre pour utiliser le serveur de courriel SMTP du programmateur avec un portefeuille géré par le client.

1. Créez des données d'identification à l'aide de DBMS_CLOUD.CREATE_CREDENTIAL pour accéder au service de stockage d'objets en nuage.

   Exemple :

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

   Les valeurs que vous indiquez pour username et password dépendent du service de stockage d'objets en nuage que vous utilisez .

   Les données d'identification que vous utilisez pour accéder au service de stockage d'objets en nuage où réside le portefeuille géré par le client.

   La création de données d'identification pour accéder au magasin d'objets Oracle Cloud Infrastructure n'est pas requise si vous activez les données d'identification du principal de ressource. Pour plus d'informations, voir Utiliser un principal de ressource pour accéder aux ressources Oracle Cloud Infrastructure.

2. Utilisez un répertoire existant ou créez-en un nouveau pour le fichier de portefeuille.

   Exemple :

   CREATE DIRECTORY wallet_dir AS 'directory_path_of_your_choice';
               

   Voir Créer un répertoire dans Autonomous AI Database pour plus d'informations sur la création de répertoires.

3. Utilisez DBMS_CLOUD.GET_OBJECT pour charger le portefeuille dans le répertoire que vous avez créé à l'étape précédente, WALLET_DIR.

   Exemple :

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

   Dans cet exemple, namespace-string est l'espace de noms du stockage d'objets pour Oracle Cloud Infrastructure et bucketname est le nom du seau. Pour plus d'informations, voir Présentation des espaces de noms du stockage d'objets.

4. Exécutez les commandes pour configurer le programmateur afin d'envoyer un courriel SMTP pour les avis de tâche du programmateur.

   Exemple :

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

   Ces commandes définissent le serveur SMTP de courriel du programmateur, créent l'objet de données d'identification contenant les données d'identification SMTP et définissent l'attribut du programmateur pour les données d'identification SMTP, et spécifient d'utiliser TLS pour le courriel envoyé pour l'avis de tâche du programmateur.

   Pour plus d'informations, voir ProcédureSET_SCHEDULER_ATTRIBUTE.

5. Créez des données d'identification pour stocker le mot de passe du portefeuille géré par le client.

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

   Cela crée les données d'identification que vous utilisez à l'étape suivante pour fournir le mot de passe du portefeuille géré par le client.

6. Définissez le répertoire du portefeuille du programmateur et les données d'identification du portefeuille.

   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. Interrogez la vue DBA_SCHEDULER_GLOBAL_ATTRIBUTE pour vérifier les valeurs que vous avez définies dans les étapes précédentes.

   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"

Fournit des notes pour l'utilisation d'un portefeuille géré par le client avec des appels externes.

• Les demandes DBMS_CLOUD ne respectent pas le portefeuille personnalisé que vous avez défini avec UTL_HTTP.set_wallet. Cela inclut DBMS_CLOUD.SEND_REQUEST et tous les accès au stockage d'objets pour les tables externes DBMS_CLOUD que vous définissez avec DBMS_CLOUD.CREATE_EXTERNAL_TABLE, DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE ou DBMS_CLOUD.CREATE_HYBRID_PART_TABLE. Lorsque vous exécutez une interrogation sur une table externe que vous avez créée avec une procédure DBMS_CLOUD, les interrogations ne respectent pas le portefeuille personnalisé que vous avez défini avec UTL_HTTP.set_wallet.

• Les demandes APEX_WEB_SERVICE ne respectent pas le portefeuille personnalisé que vous avez défini avec UTL_HTTP.set_wallet.

  Pour utiliser un portefeuille géré par le client avec APEX, spécifiez le paramètre p_wallet_path dans les appels d'API APEX_WEB_SERVICE ou définissez le paramètre d'instance de chemin d'accès au portefeuille dans les services d'administration APEX.

  Pour plus d'informations, voir Accéder aux services d'administration d'Oracle APEX.

• Les portefeuilles à connexion automatique et les portefeuilles protégés par mot de passe sont pris en charge. Lorsque vous utilisez un portefeuille à connexion automatique, spécifiez NULL pour le paramètre wallet_password.

• L'utilisateur courant qui appelle l'API UTL_HTTP.set_wallet doit disposer des privilèges READ sur l'objet de répertoire ou se voir accorder le privilège système CREATE ANY DIRECTORY.

• L'API UTL_HTTP.SET_AUTHENTICATION_FROM_WALLET est autorisée. Pour plus d'informations, voir ProcédureSET_AUTHENTICATION_FROM_WALLET.

• Le préfixe file: est pris en charge avec UTL_HTTP.set_wallet tant que le chemin d'accès au fichier spécifié est conforme à PATH_PREFIX.

  Vous pouvez déterminer la conformité PATH_PREFIX pour un chemin fourni en entrée avec la procédure DBMS_PDB_IS_VALID_PATH (accordé à PUBLIC, y compris l'utilisateur ADMIN).

  Exemple :

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

• Pour assurer la compatibilité descendante lorsque vous utilisez UTL_HTTP.set_wallet, dans les cas où le chemin du portefeuille est ignoré, les valeurs d'entrée telles que file:, NULL, etc., sont acceptées. Ces valeurs sont ignorées et spécifiez d'utiliser le chemin d'accès au portefeuille SSL par défaut avec UTL_HTTP.set_wallet.

• Les API de liste de contrôle d'accès du portefeuille DBMS_NETWORK_ACL_ADMIN, telles que APPEND_WALLET_ACL, sont prises en charge. Ces procédures vous permettent d'accorder ou de révoquer des privilèges de liste de contrôle d'accès pour le portefeuille. Pour plus d'informations, voir DBMS_NETWORK_ACL_ADMIN.

• Pour prendre en charge l'utilisation des données d'identification de mot de passe dans un portefeuille SSL pour l'authentification, l'utilisateur courant qui appelle les API UTL_HTTP doit disposer du privilège de liste de contrôle d'accès "use-passwords" sur le chemin du portefeuille.

• Notes pour définir EMAIL_SERVER_WALLET_DIRECTORY et EMAIL_SERVER_WALLET_CREDENTIAL avec DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE :

  • Pour définir les valeurs d'attribut avec DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE, vous devez être un utilisateur administrateur ou un utilisateur doté des privilèges MANAGE SCHEDULER (l'utilisateur ADMIN dispose de ces privilèges).

  • En plus du privilège MANAGE SCHEDULER, l'utilisateur qui appelle DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE doit disposer du privilège READ sur l'objet de répertoire que vous avez défini avec EMAIL_SERVER_WALLET_DIRECTORY et du privilège EXECUTE sur l'objet de données d'identification que vous avez défini avec EMAIL_SERVER_WALLET_CREDENTIAL.