Effettua chiamate esterne utilizzando un wallet gestito dal cliente

Quando l'istanza di Autonomous Database si trova su un endpoint privato, è possibile utilizzare un wallet gestito dal cliente per gestire le chiamate esterne o con lo scheduler quando lo scheduler invia messaggi di posta elettronica per vari eventi correlati ai job dello scheduler.

In Autonomous Database è possibile effettuare chiamate esterne per uno degli scopi seguenti:

• Per utilizzare i servizi Web con UTL_HTTP.

• Per accedere ai dati dai server LDAP utilizzando DBMS_LDAP.

• Per inviare e-mail a UTL_SMTP.

• Per comunicare con i server esterni basati su TCP/IP utilizzando TCP/IP con UTL_TCP.

• Per le notifiche e-mail del job di Oracle Scheduler.

Per impostazione predefinita, quando si utilizzano le procedure in questi package, Autonomous Database gestisce un wallet interno e utilizza sempre connessioni sicure (il wallet gestito da Oracle contiene più di 90 dei certificati SSL radice e intermedi sicuri più comuni). Quando Autonomous Database risiede su un endpoint privato, è possibile utilizzare il wallet gestito da Oracle predefinito con le certificazioni SLL sicure e intermedie oppure fornire un wallet gestito dal cliente.

Quando Autonomous Database risiede in un endpoint privato, è possibile specificare un wallet gestito dal cliente per UTL_HTTP, UTL_SMTP, DBMS_LDAP e DBMS_NETWORK_ACL_ADMIN utilizzando le procedure PL/SQL riportate di seguito.

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

In queste chiamate, a seconda della procedura, utilizzare il parametro path o wallet_path per specificare un wallet gestito dal cliente. Si imposta la directory del wallet con il prefisso DIR: e si include un percorso del wallet. Ad esempio:

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

L'utente corrente che richiama l'API deve disporre dei privilegi READ sull'oggetto directory o ottenere il privilegio di sistema CREATE ANY DIRECTORY.

Il prefisso DIR: è il form preferito da utilizzare per specificare un wallet gestito dal cliente. Inoltre, il prefisso file: è supportato. Ad esempio:

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

Per ulteriori informazioni, vedere Utilizzare un wallet gestito dal cliente per le chiamate esterne con UTL_HTTP.

Mostra i passi dei prerequisiti per utilizzare un wallet gestito dal cliente con chiamate esterne o con notifiche di posta elettronica SMTP dello scheduler.

1. Verificare che l'istanza di Autonomous Database sia configurata con un endpoint privato.

   Per ulteriori informazioni, vedere Configura accesso di rete con endpoint privati.

2. Impostare il parametro private_target sul valore TRUE quando si concedono le ACL richieste con dbms_network_acl_admin.append_wallet_ace oppure impostare ROUTE_OUTBOUND_CONNECTIONS sul valore PRIVATE_ENDPOINT.

   Per ulteriori informazioni, vedere Utilizzare un wallet gestito dal cliente per le chiamate esterne con UTL_HTTP e Sicurezza avanzata per le connessioni in uscita con endpoint privati.

3. Ottenere o creare un wallet gestito dal cliente.

   Ad esempio, per creare un wallet 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: ********

   Per ulteriori informazioni, vedere Gestione degli elementi PKI (Public Key Infrastructure).

4. Memorizza il wallet in un bucket nello storage degli oggetti cloud.

   Dopo aver ottenuto o creato il wallet gestito dal cliente contenente i certificati autofirmati, memorizzare il wallet in una posizione nello storage degli oggetti cloud.

Quando l'istanza di Autonomous Database si trova su un endpoint privato, è possibile utilizzare un wallet gestito dal cliente per gestire le chiamate esterne.

1. Creare una credenziale utilizzando DBMS_CLOUD.CREATE_CREDENTIAL per accedere allo storage degli oggetti cloud.

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

   I valori forniti per username e password dipendono dal servizio di storage degli oggetti cloud in uso.

   In questo modo, viene creata la credenziale utilizzata per accedere allo storage degli oggetti cloud in cui risiede il wallet gestito dal cliente.

   La creazione di una credenziale per accedere all'area di memorizzazione degli oggetti di Oracle Cloud Infrastructure non è necessaria se si abilitano le credenziali del principal risorsa. Per ulteriori informazioni, consulta la sezione Usa principal risorsa per accedere alle risorse di Oracle Cloud Infrastructure.

2. Usare una directory esistente o crearne una nuova per il file wallet.

   Ad esempio:

   CREATE DIRECTORY wallet_dir AS 'directory_path_of_your_choice';
               

   Per informazioni sulla creazione di directory, vedere Crea directory in Autonomous Database.

3. Utilizzare DBMS_CLOUD.GET_OBJECT per caricare il wallet gestito dal cliente nella directory creata nel passo precedente, WALLET_DIR.

   Ad esempio:

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

   In questo esempio, namespace-string è lo spazio di nomi dello storage degli oggetti Oracle Cloud Infrastructure e bucketname è il nome del bucket. Per ulteriori informazioni, vedere Informazioni sugli spazi di nomi dello storage degli oggetti.

4. Concedere le ACL richieste per consentire di leggere le credenziali dalla directory specificata.

   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. Impostare il percorso del wallet da utilizzare con le procedure UTL_HTTP.

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

   Per specificare la directory del wallet con UTL_HTTP.set_wallet è possibile utilizzare il prefisso dir: o il prefisso file:.

   Il prefisso dir: è disponibile solo su Autonomous Database. Per informazioni sul prefisso file:, vedere UTL_HTTP.

6. Ora è possibile eseguire le procedure UTL_HTTP per accedere a un endpoint utilizzando il wallet gestito dal cliente con un certificato autofirmato.

   Ad esempio:

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

Descrive i passi per utilizzare il server di posta elettronica SMTP dello scheduler con un wallet gestito dal cliente.

1. Creare una credenziale utilizzando DBMS_CLOUD.CREATE_CREDENTIAL per accedere allo storage degli oggetti cloud.

   Ad esempio:

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

   I valori forniti per username e password dipendono dal servizio di storage degli oggetti cloud in uso.

   In questo modo, viene creata la credenziale utilizzata per accedere allo storage degli oggetti cloud in cui risiede il wallet gestito dal cliente.

   La creazione di una credenziale per accedere all'area di memorizzazione degli oggetti di Oracle Cloud Infrastructure non è necessaria se si abilitano le credenziali del principal risorsa. Per ulteriori informazioni, consulta la sezione Usa principal risorsa per accedere alle risorse di Oracle Cloud Infrastructure.

2. Usare una directory esistente o crearne una nuova per il file wallet.

   Ad esempio:

   CREATE DIRECTORY wallet_dir AS 'directory_path_of_your_choice';
               

   Per informazioni sulla creazione di directory, vedere Crea directory in Autonomous Database.

3. Utilizzare DBMS_CLOUD.GET_OBJECT per caricare il wallet nella directory creata nel passo precedente, WALLET_DIR.

   Ad esempio:

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

   In questo esempio, namespace-string è lo spazio di nomi dello storage degli oggetti Oracle Cloud Infrastructure e bucketname è il nome del bucket. Per ulteriori informazioni, vedere Informazioni sugli spazi di nomi dello storage degli oggetti.

4. Eseguire i comandi per impostare lo scheduler per inviare e-mail SMTP per le notifiche del job scheduler.

   Ad esempio:

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

   Questi comandi impostano il server SMTP di posta elettronica dello scheduler, creano l'oggetto delle credenziali contenente le credenziali SMTP e impostano l'attributo dello scheduler per le credenziali SMTP e specificano di utilizzare TLS per l'e-mail inviata per la notifica del job dello scheduler.

   Per ulteriori informazioni, vedere SET_SCHEDULER_ATTRIBUTE Procedure.

5. Creare una credenziale per memorizzare la password per il wallet gestito dal cliente.

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

   In questo modo, viene creata la credenziale utilizzata nel passo successivo per fornire la password per il wallet gestito dal cliente.

6. Impostare la directory del wallet dello scheduler e la credenziale del 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. Eseguire una query sulla vista DBA_SCHEDULER_GLOBAL_ATTRIBUTE per verificare i valori impostati nei passi precedenti.

   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"

Fornisce note per l'utilizzo di un wallet gestito dal cliente con chiamate esterne.

• Le richieste DBMS_CLOUD non rispettano il wallet personalizzato impostato con UTL_HTTP.set_wallet. Sono inclusi DBMS_CLOUD.SEND_REQUEST e tutti gli accessi allo storage degli oggetti per le tabelle esterne DBMS_CLOUD definite con DBMS_CLOUD.CREATE_EXTERNAL_TABLE, DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE o DBMS_CLOUD.CREATE_HYBRID_PART_TABLE. Quando si esegue una query su una tabella esterna creata con una procedura DBMS_CLOUD, le query non rispettano il wallet personalizzato impostato con UTL_HTTP.set_wallet.

• Le richieste APEX_WEB_SERVICE non rispettano il wallet personalizzato impostato con UTL_HTTP.set_wallet.

  Per utilizzare un wallet gestito dal cliente con APEX, specificare il parametro p_wallet_path nelle chiamate API APEX_WEB_SERVICE o impostare l'impostazione dell'istanza del percorso del wallet in APEX Administration Services.

  Per ulteriori informazioni, vedere Accedere a Oracle APEX Administration Services.

• Sono supportati sia i wallet con login automatico che i wallet protetti da password. Quando si utilizza un wallet di login automatico, specificare NULL per il parametro wallet_password.

• L'utente corrente che richiama l'API UTL_HTTP.set_wallet deve disporre dei privilegi READ sull'oggetto directory o ottenere il privilegio di sistema CREATE ANY DIRECTORY.

• L'API UTL_HTTP.SET_AUTHENTICATION_FROM_WALLET è consentita. Per ulteriori informazioni, vedere SET_AUTHENTICATION_FROM_WALLET Procedure.

• Il prefisso file: è supportato con UTL_HTTP.set_wallet purché il percorso del file specificato sia conforme a PATH_PREFIX.

  È possibile determinare la conformità PATH_PREFIX per un percorso fornito come input con la procedura DBMS_PDB_IS_VALID_PATH (concessa a PUBLIC, incluso l'utente ADMIN).

  Ad esempio:

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

• Per garantire la compatibilità con le versioni precedenti quando si utilizza UTL_HTTP.set_wallet, nei casi in cui il percorso del wallet viene ignorato, vengono accettati valori di input quali file:, NULL e così via. Questi valori vengono ignorati e specificano di utilizzare il percorso predefinito del wallet SSL con UTL_HTTP.set_wallet.

• Le API ACL del wallet DBMS_NETWORK_ACL_ADMIN, ad esempio APPEND_WALLET_ACL, sono supportate. Queste procedure consentono di concedere/revocare i privilegi ACL del wallet. Per ulteriori informazioni, vedere DBMS_NETWORK_ACL_ADMIN.

• Per supportare l'uso delle credenziali della password in un wallet SSL per l'autenticazione, l'utente corrente che richiama le API UTL_HTTP deve disporre del privilegio ACL "use-passwords" nel percorso del wallet.

• Note per l'impostazione di EMAIL_SERVER_WALLET_DIRECTORY e EMAIL_SERVER_WALLET_CREDENTIAL con DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE:

  • Per impostare i valori degli attributi con DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE, è necessario essere un utente amministrativo o un utente con privilegi MANAGE SCHEDULER (l'utente ADMIN dispone di questi privilegi).

  • Oltre al privilegio MANAGE SCHEDULER, l'utente che richiama DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE deve disporre del privilegio READ sull'oggetto directory impostato con EMAIL_SERVER_WALLET_DIRECTORY e del privilegio EXECUTE sull'oggetto credenziale impostato con EMAIL_SERVER_WALLET_CREDENTIAL.