Configure TLS for Essbase Failover

Configuring Essbase failover to work with secure mode involves ensuring the keystore configuration matches on both Essbase domains.

You can use the TLS Configuration Utility to update the security certificates for all Essbase nodes and WebLogic managed servers. Beginning with Release 21.4, this utility is available so that you do not need to manually duplicate the identity and trust store configurations on all clients and servers.

To use the utility, follow the instructions in TLS Configuration Utility; otherwise, to configure manually, see Manual TLS Configuration.

TLS Configuration Utility

The following steps are applicable only if you are using the default self-signed certificates. For failover to work, you must update the TLS certificates for all Essbase nodes and WebLogic managed servers.

The command-line steps are for example purposes only. Details of your environment will vary.

Prerequisites

• Essbase was configured for Secure Connection Mode during the WebLogic Server Ports Configuration phase of the deployment.

• Essbase servers are stopped (see Stop, Start, and Check Servers).

1. On the machine where the primary Essbase node and Fusion Middleware are installed, navigate to <ORACLE_HOME>/essbase/bin.

   cd /scratch/username/oracle_home/essbase/bin

2. Open tls_tools.properties in a text editor. The contents, by default, are the following parameters with empty values:

   certFile=
   certCA=
   SAN=

3. Provide values to the SAN parameter to indicate how Essbase should update the certificates. Leave the other parameters blank. If you leave the tls_tools.properties file unconfigured, then when you run tlsTools.jar, the utility updates all existing certificates in the Essbase environment. However, if you need to enable Essbase for failover, you need more than the default configuration, because you need to include all the nodes needed for the failover environment.

   The SAN (Subject Alternative Name) parameter lets you specify all the IP addresses and domain names that need to be secured by the certificate update. If you are configuring Essbase for failover, provide information to this parameter about all of the following server locations:

   • Each Essbase host in the failover environment

   • The load balancer (for example, if Oracle HTTP Server is used for the load balancer, include that IP address)

   • The EPM Shared Services server, if you are using EPM security mode

   Example:

   SAN=IP:10.x.x.11,IP:10.x.x.13,IP:10.x.x.17,DNS:myhost,DNS:myhost.example.com
   certCA=
   certFile=

4. Save the tls_tools.properties file.

5. Navigate to the location of the TLS Configuration Utility, <ORACLE_HOME>/essbase/lib.

   cd /scratch/username/oracle_home/essbase/lib

6. Set the following variables in your current terminal session or shell script (where you will invoke tlsTools.jar):

   • JAVA_HOME and PATH
   • ORACLE_HOME
   • DOMAIN_HOME

   Linux Example:

   export JAVA_HOME=/scratch/jdk1.8.0_311
   export PATH=$JAVA_HOME/bin:$PATH
   export ORACLE_HOME=/scratch/username/oracle_home
   export DOMAIN_HOME=/scratch/username/oracle_home/user_projects/domains/essbase_domain

   Windows Example:

   set JAVA_HOME=C:\Program Files(x86)\Java\jdk1.8\
   set PATH=%JAVA_HOME%\bin;%PATH%
   set ORACLE_HOME=C:\oracle_home
   set DOMAIN_HOME=C:\oracle_home\user_projects\domains\essbase_domain

7. Run the TLS Configuration Utility, providing as an argument the path to the TLS properties file.

   On Linux:

   java -jar $ORACLE_HOME/essbase/lib/tlsTools.jar $ORACLE_HOME/essbase/bin/tls_tools.properties

   On Windows:

   java -jar %ORACLE_HOME%\essbase\lib\tlsTools.jar %ORACLE_HOME%\essbase\bin\tls_tools.properties

   The utility prompts you for your private key password.

   The utility replaces the certificates in the identity and trust stores, depending on how you configured the properties file.

Manual TLS Configuration

The following steps are applicable only if you are using the default self-signed certificates. If you updated certificates using the TLS Configuration Utility (tlsTools.jar), then you can skip these steps.

For Host 1 and Host 2 SSL/TLS configuration, see About Securing Your Communication and Network.

1. If WebLogic managed server is configured for SSL/TLS, then you need to copy the following files from Host 1 to the same directories on Host 2:

   DOMAIN_HOME/config/fmwconfig/essconfig/essbase/walletssl/keystore.jks

   DOMAIN_HOME/config/fmwconfig/ovd/default/keystores/adapters.jks

2. Start the WebLogic AdminServer on Host 1.

   On Linux:

   DOMAIN_HOME/esstools/bin/start.sh -i AdminServer

   On Windows:

   DOMAIN_HOME\esstools\bin\start.cmd -i AdminServer

3. Log in to the WebLogic administration console on Host 1. In the Domain Structure tree on the left, navigate to domain name -> Environment ->Servers -> essbase_server1 ->Configuration tab ->Keystores tab.

4. Record the configuration values for Custom Identity Keystore and Custom Trust Keystore.

5. From the Configuration->SSL tab, record the value of the Private Key alias for essbase_server1.

6. Lock and edit the configuration.

7. Set the same values for essbase_server2 in corresponding Keystores and SSL tabs, after changing keystores to ‘Custom Identity and Custom Trust.’

   1. Navigate to Environment ->Servers -> essbase_server2 ->Configuration tab ->Keystores tab.
   2. Click the Change button next to Demo Identity and Demo Trust.
   3. In the Keystores drop-down menu, select Custom Identity and Custom Trust, and click Save.
   4. For Custom Identity Keystore, paste the configuration path to keystore.jks that you recorded from essbase_server1 configuration.
   5. For Custom Trust Keystore, paste the configuration path to adapters.jks that you recorded from essbase_server1 configuration.
   6. Click Save.
   7. Click the SSL tab.
   8. For Private Key Alias, paste the alias that you recorded, and click Save.

8. Save and activate the changes.

9. Make sure both of the managed server certificates are imported into the trust store of the load balancer.