Configure utilities to authenticate users with a client and server SSL certificate

(Oracle)
Configure utilities to authenticate users with a client and server SSL certificate

We can configure the AllDBConnector class to use Oracle Wallet SSL certificates to authenticate a user to establish a database connection for WebSphere Commerce utilities.

Task info
When you set up this configuration, the Oracle database server authenticates itself to the client over an encrypted channel with an SSL certificate. The client also authenticates itself to the server over an encrypted channel with an SSL certificate. Once both the client and server are authenticated, the database connection for the utility is established. By configuring the database connection for utilities to authenticate users with SSL certificates, the AllDBConnector class no longer needs the user name and password combination that a user specifies in a command to run a utility. Since the class no longer needs the database password to authenticate a user, the database password is not sent between the client and server to authenticate a user.
To complete the following steps, we must run the Oracle orapki and Listener Control utilities, and update Oracle configuration files. For more information about configuring the Oracle files, running these Oracle utilities, including any updated usage syntax, see Oracle Technology Network.
If you need to share certificates across multiple server tiers, we can copy the Oracle Wallet from one server tier into the other server tiers. For example, to configure utilities like the stagingprop utility to use an Oracle Wallet to authenticate users, we can create the Wallet in your staging environment and then copy the Wallet into your production environment. We must create the override configuration in the alldbconnector.xml file for both environments. For your production environment override configuration, use the path to the copied Wallet as the wallet_directory value for the oracle.net.wallet_location property.

Procedure

Configure the database server to use an Oracle Wallet that includes an SSL certificate for authentication.
Modify the Oracle database user so that the user can be identified by an SSL certificate. Run the following command from Oracle bin directory:
sqlplus / as sysdba
alter user wcs identified externally as 'CN=oracleuser';
quit;
Note: If your server tier is the same as your client tier, ensure that your user DN is the same as your server tier. For example,
alter user wcs identified externally as 'CN=server';
Create an Oracle Wallet with the Oracle orapki utility. In a command-line utility, run the following command from Oracle bin directory:
orapki wallet create -wallet wallet_directory -auto_login -pwd wallet_password
Where

wallet_directory is the directory where to create the Wallet. For example, c:\server.wallet.
Note: Ensure that the directory that you set as the wallet_directory is readable and executable by the appropriate users.
wallet_password is the password to set for the Wallet. For example, s3rv3rp45s.
For example,
orapki wallet create -wallet c:\server.wallet -auto_login -pwd s3rv3rp45s
Install the certificate that is issued by the certificate authority. For more information about creating a certificate request and installing the certificate, see
Oracle Technology Network. As an example for testing purposes, add a self-signed certificate to your Oracle Wallet for use as the database server certificate. In a command-line utility, run the following command from Oracle bin directory:
orapki wallet add -wallet wallet_directory -dn "dn_name" -keysize 1024 
-self_signed -validity 365 -user_cert -trusted_cert -pwd wallet_password
Where

wallet_directory is the directory where to create the Wallet. For example, c:\server.wallet.
dn_name is the distinguished name of the certificate owner, which is the database server name. For example, CN=server.
wallet_password is the password to set for the Wallet. For example, s3rv3rp45s.
For example,
orapki wallet add -wallet c:\server.wallet -dn "CN=server" -keysize 1024 -self_signed -validity 365 -user_cert -trusted_cert -pwd s3rv3rp45s
Export the SSL certificate for the database server tier. In a command-line utility, run the following command from Oracle bin directory:
orapki wallet export -wallet wallet_directory -dn "dn_name" 
-cert certificate_file -pwd wallet_password
Where

wallet_directory is the directory where to create the Wallet. For example, c:\server.wallet.
dn_name is the distinguished name of the certificate owner, which is the database server name. For example, CN=server.
certificate_file is the path and name of the file that is to include the certificate that we are exporting. For example, c:\server.cert.
wallet_password is the password to set for the Wallet. For example, s3rv3rp45s.
For example,
orapki wallet export -wallet c:\server.wallet -dn "CN=server" -cert c:\server.cert -pwd s3rv3rp45s
Configure your client tier to create an Oracle Wallet that includes the database server SSL certificate and an SSL certificate for authenticating users.
Note: If the client tier where users run WebSphere Commerce utilities is the same as the database server tier, skip to step 12.
Create an Oracle Wallet with the orapki utility in your client environment. In a command-line utility, run the following command from Oracle bin directory:
orapki wallet create -wallet c:\client.wallet -auto_login -pwd cl13ntp45s
Import the SSL certificate from your server tier. In a command-line utility, run the following command from Oracle bin directory:
orapki wallet add -wallet wallet_directory -trusted_cert 
-cert certificate_file -pwd wallet_password
Where

wallet_directory is the directory where to create the Wallet. For example, c:\client.wallet.
certificate_file is the path and name of the file that is to include the certificate that we are exporting. For example, c:\server.cert.
wallet_password is the password to set for the Wallet. For example, cl13ntp45s.
For example,
orapki wallet add -wallet c:\client.wallet -dn "CN=server" -cert c:\server.cert -pwd cl13ntp45s
Update the Oracle sqlnet.ora configuration file for our client.
Go to the following directory and open the sqlnet.ora file for editing:

(Linux) ORACLE_HOME/network/admin

(Developer) ORACLE_HOME\network\admin
Where ORACLE_HOME is the root directory for our Oracle database. For example, C:\ORACLE\ORA92.
Update the configuration parameters to match the settings for our system. When we are updating the file, ensure that you update the following parameters:

SQLNET.AUTHENTICATION_SERVICES
SSL_CLIENT_AUTHENTICATION
SSL_VERSION
NAMES.DIRECTORY_PATH
WALLET_LOCATION
For example, your parameters can resemble the following code snippet:
SQLNET.AUTHENTICATION_SERVICES = (TCPS, BEQ, NTS)
SSL_VERSION = 3.0
NAMES.DIRECTORY_PATH = (TNSNAMES, EZCONNECT)
WALLET_LOCATION =
(SOURCE =
  (METHOD = FILE)
  (METHOD_DATA =
    (DIRECTORY = c:\client.wallet)
  )
)
SSL_CLIENT_AUTHENTICATION = TRUE
Update the Oracle tnsnames.ora configuration file.
Go to the following directory and open the tnsnames.ora file for editing:

(Linux) ORACLE_HOME/network/admin

(Developer) ORACLE_HOME\network\admin
Where ORACLE_HOME is the root directory for our Oracle database. For example, C:\ORACLE\ORA92.
Add a TNS entry that points to the database server. For example, your configuration can resemble the following code snippet:
   WCS =
      (DESCRIPTION =
        (ADDRESS_LIST =
          (ADDRESS = (PROTOCOL = TCPS)(HOST = fahadjwcs.canlab.ibm.com)(PORT = 2484))
        )
        (CONNECT_DATA =
          (SERVER = DEDICATED)
          (SERVICE_NAME = WCS)
        )
      )
Install the certificate that is issued by the certificate authority. For more information about creating a certificate request and installing the certificate, see
Oracle Technology Network. As an example for testing purposes, add a self-signed certificate to the client tier Wallet for use as the user certificate. If your client is the same as your server, add the certificate to your server tier Wallet. In a command-line utility, run the following command from Oracle bin directory:
orapki wallet add -wallet wallet_directory -dn "dn_name" -keysize 1024 -self_signed 
 -validity 365 -user_cert -trusted_cert -pwd wallet_password
Where

wallet_directory is the directory where to create the Wallet. For example, c:\client.wallet.
dn_name is the distinguished name of the certificate owner, which is the database server name. For example, CN=server.
wallet_password is the password to set for the Wallet. For example, cl13ntp45s.
For example,
orapki wallet add -wallet c:\client.wallet -dn "CN=oracleuser" -keysize 1024 -self_signed 
-validity 365 -user_cert -trusted_cert -pwd cl13ntp45s
Export the user SSL certificate from the client tier Oracle Wallet. In a command-line utility, run the following command from Oracle bin directory:
orapki wallet export -wallet c:\client.wallet -dn "CN=oracleuser" -cert c:\user.cert -pwd cl13ntp45s
Continue the configuration for the database server tier.
Import the user SSL certificate from your client tier Oracle Wallet into the server tier Oracle Wallet. In a command-line utility, run the following command from Oracle bin directory:
 orapki wallet add -wallet c:\server.wallet -trusted_cert -cert c:\user.cert -pwd s3rv3rp45s
Shut down your Oracle database.from Oracle bin directory:
sqlplus / as sysdba
shutdown immediate;
quit;
Stop the Oracle listener with the Oracle Listener Control utility.from Oracle bin directory:
lsnrctl stop
Update the Oracle listener listener.ora configuration file.
Go to the following directory and open the listener.ora file for editing:

(Linux) ORACLE_HOME/network/admin

(Developer) ORACLE_HOME\network\admin
Where ORACLE_HOME is the root directory for our Oracle database. For example, C:\ORACLE\ORA92
Update the listener parameters to match the settings for our system. When we are updating the file, ensure that you update the parameters in the following sections:

SID_LIST_LISTENER
LISTENER
WALLET_LOCATION
SSL_CLIENT_AUTHENTICATION
For example, your updated keys can resemble the following code snippet:
SID_LIST_LISTENER =
(SID_LIST =
  (SID_DESC =
    (GLOBAL_DBNAME = WCS)
    (SID_NAME = WCS)
    (ORACLE_HOME = Oracle_installdir\dbhome_1)
  )
)
LISTENER =
(DESCRIPTION_LIST =
  (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCPS)(HOST = myhostname.mycompany.com)(PORT = 2484))
  )
)
WALLET_LOCATION =
(SOURCE =
  (METHOD = FILE)
  (METHOD_DATA =
    (DIRECTORY = C:\server.wallet)
  )
)
SSL_CLIENT_AUTHENTICATION = TRUE
Update the Oracle sqlnet.ora configuration file.
Go to the following directory and open the sqlnet.ora file for editing:

(Linux) ORACLE_HOME/network/admin

(Developer) ORACLE_HOME\network\admin
Where ORACLE_HOME is the root directory for our Oracle database. For example, C:\ORACLE\ORA92.
Update the configuration parameters to match the settings for our system. When we are updating the file, ensure that you update the following parameters:

SQLNET.AUTHENTICATION_SERVICES
SSL_CLIENT_AUTHENTICATION
SSL_VERSION
NAMES.DIRECTORY_PATH
WALLET_LOCATION
For example, your parameters can resemble the following code snippet:
SQLNET.AUTHENTICATION_SERVICES = (BEQ, TCPS, NTS)
SSL_CLIENT_AUTHENTICATION = FALSE
SSL_VERSION = 3.0
NAMES.DIRECTORY_PATH = (TNSNAMES, EZCONNECT)
WALLET_LOCATION =
(SOURCE =
  (METHOD = FILE)
  (METHOD_DATA =
    (DIRECTORY = C:\server.wallet)
  )
)
Restart the Oracle listener.from Oracle bin directory:
lsnrctl start
Start your Oracle database.from Oracle bin directory:
sqlplus / as sysdba
startup;
quit;
Configure the AllDBConnector class configuration for establishing a database connection for WebSphere Commerce utilities to use the certificate in the Oracle Wallet.
Update the database connection acquisition configuration file to ensure that the WebSphere Commerce utilities can authenticate users through the Oracle Wallet.
Go to the following directory and open the alldbconnector.xml configuration file for editing.

(Developer) WCDE_installdir\WC\xml\config
Update the alldbconnector.xml file to include two overrides to configure how utilities authenticate users. In the first override configuration, configure the override for our local client database. In the second override configuration, configure the connection override properties for your production environment database. This second override configuration ensures that utilities can use the SSL certificates to authenticate users when a utility, such as the stagingprop utility, must connect to multiple databases.
Note: For the override property identifier, oradestwallet, a corresponding TNS entry, WCSDEST, must exist in the tnsnames.ora configuration file for our utility client environment.
For more information about the properties that we can include in your override configuration in the alldbconnector.xml file, see Database connection acquisition for utilities and Ant tasks.
If your Oracle database driver type is a thin driver, your updated AllDBConnector class configuration in the alldbconnector.xml file can resemble the following code snippet:
<oracle>
  <override identifier="orasrcwallet">
    <property name="oracle.jdbc.J2EE13Compliant" type="java.lang.Boolean" value="true"/>
    <property name="oracle.net.tns_admin" 
     value="Oracle_installdir\dbhome_1\network\admin" scope="system" />
    <property name="oracle.net.wallet_location" 
     value="(SOURCE=(METHOD=file)(METHOD_DATA=(DIRECTORY=wallet_directory)))" />
    <property name="oracle.net.ssl_version" value="3.0" />
    <property name="oracle.net.authentication_services" value="(TCPS)" />
    <jdbcurl value="jdbc:oracle:thin:@wcs" />
    <security providername="oracle.security.pki.OraclePKIProvider" />
    <jar path="Oracle_installdir\dbhome_1\jlib\oraclepki.jar" />
    <jar path="Oracle_installdir\dbhome_1\jlib\osdt_cert.jar" />
    <jar path="Oracle_installdir\dbhome_1\jlib\osdt_core.jar" />
    <ignoreUserPass />
  </override>
  <override identifier="oradestwallet">
    <property name="oracle.jdbc.J2EE13Compliant" type="java.lang.Boolean" value="true"/>
    <property name="oracle.net.tns_admin" 
     value="Oracle_installdir\dbhome_1\network\admin" scope="system" />
    <property name="oracle.net.wallet_location" 
     value="(SOURCE=(METHOD=file)(METHOD_DATA=(DIRECTORY=wallet_directory)))" />
    <property name="oracle.net.ssl_version" value="3.0" />
    <property name="oracle.net.authentication_services" value="(TCPS)" />
    <jdbcurl value="jdbc:oracle:thin:@wcsdest" />
    <security providername="oracle.security.pki.OraclePKIProvider" />
    <jar path="Oracle_installdir\dbhome_1\jlib\oraclepki.jar" />
    <jar path="Oracle_installdir\dbhome_1\jlib\osdt_cert.jar" />
    <jar path="Oracle_installdir\dbhome_1\jlib\osdt_core.jar" />
    <ignoreUserPass />
  </override>
</oracle>
If your Oracle database driver type is a thick driver, your updated AllDBConnector class configuration in the alldbconnector.xml file can resemble the following code snippet:
<oracle>
  <override identifier="orasrcwallet">
    <property name="oracle.jdbc.J2EE13Compliant" type="java.lang.Boolean" value="true"/>
    <property name="oracle.net.wallet_location" 
     value="(SOURCE=(METHOD=file)(METHOD_DATA=(DIRECTORY=wallet_directory)))" />
    <property name="oracle.net.ssl_version" value="3.0" />
    <jdbcurl value="jdbc:oracle:oci:@wcs" />
    <security providername="oracle.security.pki.OraclePKIProvider" />
    <jar path="Oracle_installdir\dbhome_1\jlib\oraclepki.jar" />
    <jar path="Oracle_installdir\dbhome_1\jlib\osdt_cert.jar" />
    <jar path="Oracle_installdir\dbhome_1\jlib\osdt_core.jar" />
    <ignoreUserPass />
  </override>
  <override identifier="oradestwallet">
    <property name="oracle.jdbc.J2EE13Compliant" type="java.lang.Boolean" value="true"/>
    <property name="oracle.net.wallet_location" 
     value="(SOURCE=(METHOD=file)(METHOD_DATA=(DIRECTORY=wallet_directory)))" />
    <property name="oracle.net.ssl_version" value="3.0" />
    <jdbcurl value="jdbc:oracle:oci:@wcsdest" />
    <security providername="oracle.security.pki.OraclePKIProvider" />
    <jar path="Oracle_installdir\dbhome_1\jlib\oraclepki.jar" />
    <jar path="Oracle_installdir\dbhome_1\jlib\osdt_cert.jar" />
    <jar path="Oracle_installdir\dbhome_1\jlib\osdt_core.jar" />
    <ignoreUserPass />
  </override>
</oracle>
Where

orasrcwallet is the identifier of the override configuration for the authoring or staging environment.
oradestwallet is the identifier of the override configuration for ythe production environment.
wallet_directory is the directory that includes the Wallet. For example, c:\server.wallet.
Results
Your WebSphere Commerce utilities are configured to authenticate users through an Oracle Wallet. To use this authentication, a user can use a modified command when they run a WebSphere Commerce utility. Instead of including database connection passwords, a user only needs to identify the Wallet that includes the appropriate SSL certificate. For example, to run the stagingprop utility, a user can run the following command from the WebSphere Commerce bin directory in a command-line utility:

(Linux) stagingprop.sh -sourcedb orasrcwallet -destdb oradestwallet -sourcedb_user randomValue -sourcedb_passwd randomValue -destdb_user randomValue -destdb_passwd randomValue
Where

orasrcwallet is the identifier of the override configuration for the authoring or staging environment.
oradestwallet is the identifier of the override configuration for ythe production environment.
randomValue is any value for the specified parameter. With this Oracle Wallet configuration, the value is ignored by the AllDBConnector class and is not used to authenticate the user.

Related tasks
Configure utilities to authenticate users with an SSL certificate and client password
Configure utilities to authenticate users with an Oracle Wallet encrypted passwords
Configure the Oracle database connection for utilities to authenticate users with Oracle Wallet

Related reference
Utilities