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.


  • 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 in a text editor. The contents, by default, are the following parameters with empty values:

  3. Provide values to the SAN parameter to indicate how Essbase should update the certificates. Leave the other parameters blank. If you leave the 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


  4. Save the 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

    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/

    On Windows:

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

    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:

  2. Start the WebLogic AdminServer on Host 1.

    On Linux:

    DOMAIN_HOME/esstools/bin/ -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.