Documentation Oracle Cloud Infrastructure

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

Lorsque votre instance de base de données Autonomous AI se trouve sur une adresse privée, vous pouvez utiliser un portefeuille géré par le client avec des procédures dans UTL_HTTP, DBMS_LDAP, UTL_SMTP ou UTL_TCP. Vous pouvez également utiliser un portefeuille géré par le client lorsque le planificateur envoie des notifications par e-mail SMTP pour divers événements liés aux travaux du planificateur.

Rubrique parent : Développement

A propos de l'utilisation d'un portefeuille géré par le client avec des appels externes

Lorsque votre instance de base de données Autonomous AI se trouve sur une adresse privée, vous pouvez utiliser un portefeuille géré par le client pour gérer les appels externes, ou avec le planificateur lorsque le planificateur envoie des courriels pour divers événements liés aux travaux du planificateur.

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 à partir de 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 notifications par courriel de travail 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édiaires sécurisés les plus courants). Lorsque votre base de données Autonomous AI réside sur une adresse privée, vous pouvez utiliser le portefeuille géré par Oracle par défaut avec les certifications SLL sécurisées et intermédiaires, ou vous pouvez fournir un portefeuille géré par le client.

Lorsque votre base de données Autonomous AI réside sur une adresse privée, vous pouvez indiquer 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 indiquer un portefeuille géré par le client. Vous définissez le répertoire de portefeuille avec le préfixe DIR: et incluez un chemin de portefeuille. Par exemple : 

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

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

Le préfixe DIR: est le formulaire préféré pour indiquer un portefeuille géré par le client. En outre, le préfixe file: est pris en charge. Par exemple : 

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

Pour plus d'informations, reportez-vous à Utilisation d'un portefeuille géré par le client pour les appels externes avec UTL_HTTP :

A propos de l'utilisation d'un portefeuille géré par le client avec le serveur de messagerie du planificateur

Le serveur de messagerie du planificateur est disponible pour envoyer des notifications par courriel pour divers événements liés au planificateur, tels que la notification des travaux démarrés, en échec ou terminés. Par défaut, le serveur de messagerie SMTP du planificateur utilise le portefeuille défini dans la propriété SSL_WALLET pour les communications SSL/TLS. Vous pouvez éventuellement utiliser un portefeuille géré par le client avec le serveur de messagerie SMTP du planificateur.

Les attributs globaux suivants prennent en charge l'utilisation d'un portefeuille géré par le client :

  • EMAIL_SERVER_WALLET_DIRECTORY : est défini sur un objet répertoire qui indique le chemin où réside le portefeuille SSL.

  • EMAIL_SERVER_WALLET_CREDENTIAL : est défini sur un objet d'informations d'identification avec une paire nom utilisateur/mot de passe, où nom utilisateur est une valeur quelconque et mot de passe est le mot de passe du portefeuille SSL.

Vous définissez des valeurs pour ces attributs à l'aide de DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE.

Pour plus d'informations, reportez-vous à :

Prérequis pour l'utilisation d'un portefeuille géré par le client avec des appels externes

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

Effectuez les étapes de prérequis suivantes :

  1. Vérifiez que l'instance de base de données Autonomous AI est configurée avec une adresse privée.

    Pour plus d'informations, reportez-vous à la section Configure Network Access with Private Endpoints.

  2. Définissez le paramètre private_target sur la valeur TRUE lorsque vous accordez les listes de contrôle d'accès requises avec dbms_network_acl_admin.append_wallet_ace ou définissez ROUTE_OUTBOUND_CONNECTIONS sur la valeur PRIVATE_ENDPOINT.
  3. Obtenez ou créez un portefeuille géré par le client.

    Par exemple, pour créer un portefeuille avec orapki, procédez comme suit : 

    -- 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, reportez-vous à Gestion des éléments PK I (Public Key Infrastructure).

  4. Stockez le portefeuille dans un bucket sur Cloud Object Storage.

    Une fois que vous avez obtenu ou créé le portefeuille géré par le client contenant des certificats auto-signés, stockez-le à un emplacement sur le stockage d'objets cloud.

Utiliser un portefeuille géré par le client pour les appels externes avec UTL_HTTP

Lorsque votre instance de base de données Autonomous AI se trouve sur une adresse privée, vous pouvez utiliser un portefeuille géré par le client pour gérer les appels externes.

Ces étapes décrivent l'utilisation d'un portefeuille géré par le client avec UTL_HTTP. Les étapes sont les mêmes pour les autres packages pris en charge, notamment : DMBS_LDAP, UTL_SMTP et UTL_TCP.

Effectuez les étapes prérequises pour utiliser un portefeuille géré par le client. Pour plus d'informations, voir Prérequis pour l'utilisation d'un portefeuille géré par le client avec des appels externes.

Pour configurer une base de données Autonomous AI afin d'utiliser un portefeuille géré par le client, procédez comme suit :

  1. Créez des informations d'identification à l'aide de DBMS_CLOUD.CREATE_CREDENTIAL pour accéder à Cloud Object Storage.
    BEGIN
  DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'DEF_CRED_NAME',
    username => 'user1@example.com',
    password => 'password'
  );
END;
/

    Les valeurs fournies pour username et password dépendent du service Cloud Object Storage que vous utilisez .

    Vous créez ainsi les informations d'identification que vous utilisez pour accéder au stockage d'objet cloud où réside le portefeuille géré par le client.

    La création d'informations d'identification pour accéder à la banque d'objets Oracle Cloud Infrastructure n'est pas requise si vous activez les informations d'identification de principal de ressource. Pour plus d'informations, reportez-vous à Utilisation du principal de ressource pour accéder à des ressources Oracle Cloud Infrastructure.

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

    Par exemple :

    CREATE DIRECTORY wallet_dir AS 'directory_path_of_your_choice';

    Pour plus d'informations sur la création de répertoires, reportez-vous à Création d'un répertoire dans la base de données Autonomous AI.

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

    Par 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 d'objet Oracle Cloud Infrastructure et bucketname est le nom du bucket. Pour plus d'informations, reportez-vous à Présentation des espaces de noms Object Storage.

  4. Accordez les listes de contrôle d'accès requises pour vous permettre de lire les informations d'identification à partir du répertoire indiqué.
    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 de portefeuille à utiliser avec les procédures UTL_HTTP.
    BEGIN
    UTL_HTTP.set_wallet('DIR:WALLET_DIR', 'password');
END;
/

    Pour indiquer 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: est uniquement disponible sur la base de données Autonomous AI. Pour plus d'informations sur le préfixe file:, reportez-vous à UTL_HTTP.

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

    Par exemple :

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

Utiliser un portefeuille géré par le client avec des notifications par e-mail du planificateur

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

Effectuez les étapes prérequises pour utiliser un portefeuille géré par le client. Pour plus d'informations, voir Prérequis pour l'utilisation d'un portefeuille géré par le client avec des appels externes.

Pour utiliser un portefeuille géré par le client avec le serveur de messagerie du planificateur, procédez comme suit :

  1. Créez des informations d'identification à l'aide de DBMS_CLOUD.CREATE_CREDENTIAL pour accéder à Cloud Object Storage.

    Par exemple :

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

    Les valeurs fournies pour username et password dépendent du service Cloud Object Storage que vous utilisez .

    Vous créez ainsi les informations d'identification que vous utilisez pour accéder à Cloud Object Storage où réside le portefeuille géré par le client.

    La création d'informations d'identification pour accéder à la banque d'objets Oracle Cloud Infrastructure n'est pas requise si vous activez les informations d'identification de principal de ressource. Pour plus d'informations, reportez-vous à Utilisation du principal de ressource pour accéder à des ressources Oracle Cloud Infrastructure.

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

    Par exemple :

    CREATE DIRECTORY wallet_dir AS 'directory_path_of_your_choice';

    Pour plus d'informations sur la création de répertoires, reportez-vous à Création d'un répertoire dans la base de données Autonomous AI.

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

    Par 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 d'objet Oracle Cloud Infrastructure et bucketname est le nom du bucket. Pour plus d'informations, reportez-vous à Présentation des espaces de noms Object Storage.

  4. Exécutez les commandes pour configurer le planificateur afin qu'il envoie un courriel SMTP pour les notifications de travail du planificateur.

    Par 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 messagerie du planificateur, créent l'objet d'informations d'identification contenant les informations d'identification SMTP et définissent l'attribut de planificateur pour les informations d'identification SMTP, et indiquent d'utiliser TLS pour les courriels envoyés pour la notification de travail du planificateur.

    Pour plus d'informations, reportez-vous à Procédure SET_SCHEDULER_ATTRIBUTE.

  5. Créez des informations 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;
/

    Les informations d'identification que vous utilisez à l'étape suivante sont ainsi créées pour fournir le mot de passe du portefeuille géré par le client.

  6. Définissez le répertoire du portefeuille du planificateur et les informations 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"

Remarques concernant l'utilisation d'un portefeuille géré par le client avec des appels externes

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

  • Les demandes DBMS_CLOUD ne respectent pas le portefeuille personnalisé 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 requête sur une table externe que vous avez créée avec une procédure DBMS_CLOUD, les requêtes 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é défini avec UTL_HTTP.set_wallet.

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

    Pour plus d'informations, reportez-vous à Accès aux services d'administration Oracle APEX.

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

  • L'utilisateur en cours appelant l'API UTL_HTTP.set_wallet doit disposer des privilèges READ sur l'objet 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, reportez-vous à Procédure SET_AUTHENTICATION_FROM_WALLET.

  • Le préfixe file: est pris en charge avec UTL_HTTP.set_wallet tant que le chemin de fichier indiqué est compatible avec 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ée à PUBLIC, y compris l'utilisateur ADMIN).

    Par 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 garantir la compatibilité descendante lorsque vous utilisez UTL_HTTP.set_wallet, dans les cas où le chemin de portefeuille est ignoré, les valeurs d'entrée telles que file:, NULL, etc. sont acceptées. Ces valeurs sont ignorées et indiquent d'utiliser le chemin de portefeuille SSL par défaut avec UTL_HTTP.set_wallet.

  • Les API d'ACL de portefeuille DBMS_NETWORK_ACL_ADMIN, telles que APPEND_WALLET_ACL, sont prises en charge. Ces procédures vous permettent d'accorder/de révoquer des privilèges d'ACL de portefeuille. Pour plus d'informations, reportez-vous à DBMS_NETWORK_ACL_ADMIN.

  • Pour prendre en charge l'utilisation des informations d'identification de mot de passe dans un portefeuille SSL pour l'authentification, l'utilisateur en cours appelant les API UTL_HTTP doit disposer du privilège d'ACL "use-passwords" sur le chemin du portefeuille.

  • Remarques concernant la définition de 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 administrateur ou un utilisateur disposant 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 défini avec EMAIL_SERVER_WALLET_DIRECTORY et du privilège EXECUTE sur l'objet d'informations d'identification que vous définissez avec EMAIL_SERVER_WALLET_CREDENTIAL.