Adding a Client Certificate to an Oracle Wallet

Some Brazilian banks, such as Santander and Itaú, require a client digital certificate when calling their REST APIs. Doing this directly via Oracle can be a bit annoying, as it requires creating a specific wallet to call these services using MAKE_REST_REQUEST. Because of this, many developers give up and end up making these calls through intermediary applications. In this article, we’ll cover how to make these REST connections directly from the database using APEX’s MAKE_REST_REQUEST.

To create the wallet, you need to have the full version of Oracle Client installed, since we’ll need orapki. Having only the Instant Client is not enough, orapki is also included in Oracle Database installations. In my opinion, it's not worth downloading and installing the full client or full database just to use OraPKI, but that’s up to you.

You can learn more about using orapki without downloading the full client in this article of mine:

Creating and Configuring Wallets with OraPKI (Without Needing the Full Oracle Client)

From this point on, you should already have access to orapki.

The first thing you need to do—if you don't already have a wallet—is to create one. You can run the following command, replacing the folder with one of your choice:

orapki wallet create -wallet "C:\Users\valter\Downloads\adu" -pwd 123456xx

After running this command, you’ll see that it has created the wallet on your operating system, as shown below:

Next, import the client certificate using the command below. First, specify the wallet directory, then the path to the client's .pfx certificate file and its password:

orapki wallet import_pkcs12 -wallet "C:\Users\valter\Downloads\adu" -pwd 123456xx -pkcs12file "C:\Users\valter\OneDrive\Desktop\certificado_a_importar\user_cert.pfx" -pkcs12pwd 123456

After executing, you should receive the following success message:

orapki command import_pkcs12 executed successfully.

Usually, you will also need to add the server certificates of the service you're trying to connect to the wallet's trusted certificates:

orapki wallet add -wallet "C:\Users\valter\Downloads\adu" -trusted_cert -cert "G:\Meu Drive\Aplicativos\OraPKI\certs\ICP-BR\AC_VALID_RFB_v5.crt" -pwd 123456xx

You can verify the contents of your wallet with:

orapki wallet display -wallet "C:\Users\valter\Downloads\adu" -pwd 123456xx

It should display the client and trusted certificates, as shown below:

Now you need to upload this wallet to a directory accessible by your database. In my example: file:/opt/oracle/wallets/adu/. In some cases, I had to include a trailing slash (/) at the end, and in others, it worked without it. I tested this in two different environments. Try without the trailing slash first—it should work.

We must grant privileges for the required owners using SYS or ADMIN. Below is the command used to assign these privileges. Remember to replace YOUR_OWNER with your actual schema name and APEX_230200 with the version of your APEX schema:

BEGIN

-- APEX
 DBMS_NETWORK_ACL_ADMIN.APPEND_WALLET_ACE(       
  wallet_path => 'file:/opt/oracle/wallets/adu/',
  ace     => xs$ace_type(
           privilege_list => xs$name_list('use_client_certificates', 'use_passwords'),
           principal_name => 'APEX_230200',
           principal_type => xs_acl.ptype_db
          )

 );

-- OWNER
DBMS_NETWORK_ACL_ADMIN.APPEND_WALLET_ACE(       
  wallet_path => 'file:/opt/oracle/wallets/adu/',
  ace     => xs$ace_type(
           privilege_list => xs$name_list('use_client_certificates', 'use_passwords'),
           principal_name => 'YOUR_OWNER',
           principal_type => xs_acl.ptype_db
          )
 );

end;

From this point on, just reference the wallet when calling the service using MAKE_REST_REQUEST.