Make External Calls Using a Customer-Managed Wallet
When your
Autonomous Database instance is on a private endpoint you
can use a customer-managed wallet with procedures in
UTL_HTTP
,
DBMS_LDAP
,
UTL_SMTP
, or
UTL_TCP
. You can also use a
customer-managed wallet when the scheduler sends SMTP email
notifications for various events related to scheduler
jobs.
- About Using a Customer-Managed Wallet with External Calls
When your Autonomous Database instance is on a private endpoint you can use a customer-managed wallet to handle external calls, or with the scheduler when the scheduler sends email for various events related to scheduler jobs. - Prerequisites to Use a Customer-Managed Wallet with External Calls
Shows the prerequisite steps to use a customer-managed wallet with external calls or with scheduler SMTP email notifications. - Use a Customer-Managed Wallet for External Calls with UTL_HTTP
When your Autonomous Database instance is on a private endpoint you can use a customer-managed wallet to handle external calls. - Use a Customer-Managed Wallet with Scheduler Email Notifications
Describes the steps to use the scheduler SMTP email server with a customer-managed wallet. - Notes for Using a Customer-Managed Wallet with External Calls
Provides notes for using a customer-managed wallet with external calls.
Parent topic: Develop
About Using a Customer-Managed Wallet with External Calls
When your Autonomous Database instance is on a private endpoint you can use a customer-managed wallet to handle external calls, or with the scheduler when the scheduler sends email for various events related to scheduler jobs.
On Autonomous Database you can make external calls for any of the of the following purposes:
-
To use web services with
UTL_HTTP
. -
To access data from LDAP servers using
DBMS_LDAP
. -
To send email with
UTL_SMTP
. -
To communicate with external TCP/IP-based servers using TCP/IP with
UTL_TCP
. -
For Oracle Scheduler job email notifications.
By default when you use procedures in these packages Autonomous Database maintains an internal wallet and always uses secure connections (the Oracle managed wallet contains more than 90 of the most common trusted root and intermediate SSL certificates). When your Autonomous Database resides on a private endpoint you have the option to use the default Oracle managed wallet with the trusted and intermediate SLL certifications, or you can supply a customer-managed wallet.
When your Autonomous Database
resides on a private endpoint you can specify a customer-managed wallet for
UTL_HTTP
, UTL_SMTP
, DBMS_LDAP
,
and DBMS_NETWORK_ACL_ADMIN
using the following PL/SQL procedures:
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 these calls, depending on the procedure, use either the
path
or wallet_path
parameter to specify a
customer-managed wallet. You set the wallet directory with the DIR:
prefix and include a wallet path. For example:
UTL_HTTP.set_wallet('DIR:WALLET_DIR', 'password');
The current user invoking the API must have READ
privileges
on the directory object or be granted the CREATE ANY DIRECTORY
system
privilege.
The DIR:
prefix is the preferred form to use to specify a
customer-managed wallet. In addition, the file:
prefix is supported.
For example:
UTL_HTTP.set_wallet('file:WALLET_DIR/wallet.sso', 'password');
See Use a Customer-Managed Wallet for External Calls with UTL_HTTP for more information:
About Using a Customer-Managed Wallet with Scheduler Email Server
The scheduler email server is available to send email notifications for
various events related to the scheduler, such as notification of started, failed, or
completed jobs. By default, the scheduler SMTP email server uses the wallet defined
in the SSL_WALLET
property for SSL/TLS communications. Optionally,
you can use a customer-managed wallet with the scheduler SMTP email server.
The following global attributes support using a customer-managed wallet:
-
EMAIL_SERVER_WALLET_DIRECTORY
: is set to a directory object that specifies the path where the SSL wallet resides. EMAIL_SERVER_WALLET_CREDENTIAL
: is set to a credential object with a username/password pair, where the username is any value and the password is the SSL wallet password.
You set values for these attributes using
DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE
.
See the following for more information:
Parent topic: Make External Calls Using a Customer-Managed Wallet
Prerequisites to Use a Customer-Managed Wallet with External Calls
Shows the prerequisite steps to use a customer-managed wallet with external calls or with scheduler SMTP email notifications.
Perform the prerequisite steps:
Parent topic: Make External Calls Using a Customer-Managed Wallet
Use a Customer-Managed Wallet for External Calls with UTL_HTTP
When your Autonomous Database instance is on a private endpoint you can use a customer-managed wallet to handle external calls.
These steps describe using a customer-managed wallet with
UTL_HTTP
. The steps are the same for the other supported packages,
including: DMBS_LDAP
, UTL_SMTP
, and
UTL_TCP
.
Perform the prerequisite steps to use a customer-managed wallet. See Prerequisites to Use a Customer-Managed Wallet with External Calls for more information.
To configure an Autonomous Database to use a customer-managed wallet:
Parent topic: Make External Calls Using a Customer-Managed Wallet
Use a Customer-Managed Wallet with Scheduler Email Notifications
Describes the steps to use the scheduler SMTP email server with a customer-managed wallet.
Perform the prerequisite steps to use a customer-managed wallet. See Prerequisites to Use a Customer-Managed Wallet with External Calls for more information.
To use a customer-managed wallet with the scheduler email server:
Parent topic: Make External Calls Using a Customer-Managed Wallet
Notes for Using a Customer-Managed Wallet with External Calls
Provides notes for using a customer-managed wallet with external calls.
-
DBMS_CLOUD
requests do not honor the custom wallet you set withUTL_HTTP.set_wallet
. This includesDBMS_CLOUD.SEND_REQUEST
and all object storage access forDBMS_CLOUD
external tables that you define withDBMS_CLOUD.CREATE_EXTERNAL_TABLE
,DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE
, orDBMS_CLOUD.CREATE_HYBRID_PART_TABLE
. When you perform a query on an external table that you created with aDBMS_CLOUD
procedure, the queries do not honor the custom wallet you set withUTL_HTTP.set_wallet
. -
APEX_WEB_SERVICE
requests do not honor the custom wallet you set withUTL_HTTP.set_wallet
. -
Both auto-login wallets and password protected wallets are supported. When you use an auto-login wallet, specify
NULL
for thewallet_password
parameter. -
The current user invoking the
UTL_HTTP.set_wallet
API must haveREAD
privileges on the directory object or be granted theCREATE ANY DIRECTORY
system privilege. -
The
UTL_HTTP.SET_AUTHENTICATION_FROM_WALLET
API is allowed. See SET_AUTHENTICATION_FROM_WALLET Procedure for more information. -
The
file:
prefix is supported withUTL_HTTP.set_wallet
as long as the specified file path isPATH_PREFIX
compliant.You can determine the
PATH_PREFIX
compliance for a path provided as input with theDBMS_PDB_IS_VALID_PATH
procedure (granted toPUBLIC
including theADMIN
user).For example:
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; /
-
To ensure backward compatibility when you use
UTL_HTTP.set_wallet
, in cases where the wallet path is ignored, input values such asfile:
,NULL
, and so on, are accepted. These values are ignored and specify to use the default SSL wallet path withUTL_HTTP.set_wallet
. -
The
DBMS_NETWORK_ACL_ADMIN
wallet ACL APIs, such asAPPEND_WALLET_ACL
are supported. These procedures allow you to grant/revoke wallet ACL privileges. See DBMS_NETWORK_ACL_ADMIN for more information. -
To support using the password credentials in an SSL wallet for authentication, the current user invoking
UTL_HTTP
APIs must have the "use-passwords
" ACL privilege on the wallet path. -
Notes for setting
EMAIL_SERVER_WALLET_DIRECTORY
andEMAIL_SERVER_WALLET_CREDENTIAL
withDBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE
:-
To set the attribute values with
DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE
you must be an administrative user or a user withMANAGE SCHEDULER
privileges (the ADMIN user has these privileges). - In addition to
MANAGE SCHEDULER
privilege, the user invokingDBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE
must have ofREAD
privilege on the directory object you set withEMAIL_SERVER_WALLET_DIRECTORY
, andEXECUTE
privilege on the credential object you set withEMAIL_SERVER_WALLET_CREDENTIAL
.
-
Parent topic: Make External Calls Using a Customer-Managed Wallet