1. Security Configuration Guide
  2. SSL-Enabling EPM System Components
  3. SSL for Essbase 21c
  4. Using Trusted Third-Party CA Certificates for Essbase

Using Trusted Third-Party CA Certificates for Essbase

Creating Certificate Requests and Obtaining Certificates

Generate a certificate request to obtain a certificate for the server that hosts Oracle Essbase Server and Essbase Agent. A certificate request contains encrypted information specific to your server’s Common Name (CN=). You submit the certificate request to a signing authority to obtain an SSL certificate.

You use a tool such as keytool or Oracle Wallet Manager to create a certificate request. For detailed information on creating a certificate request, see the documentation for the tool that you are using.

Examples using keytool:

Create a Java Keystore (JKS) and generate a private key:

keytool.exe -genkey -dname "cn=myserver, ou=EPM, o=Oracle, c=US" 
-alias essbase_ssl -keypass password -keystore 
C:\oracle\Middleware\EPMSystem11R1\ssl\EPM.JKS -storepass password 
-validity 365 -keyalg RSA -keysize 2048 -sigalg SHA256withRSA -noprompt

Generate a certificate request:

keytool -certreq -alias essbase_ssl -file C:\oracle\Middleware\EPMSystem11R1\ssl\essabse_server.csr -keypass password 
-keystore C:\oracle\Middleware\EPMSystem11R1\ssl\EPM.JKS -storepass password

Export your private key (you will need the openssl utility to perform these steps):

  1. openssl.exe pkcs12 -in C:\oracle\Middleware\EPMSystem11R1\ssl\EPM.JKS -passin pass:password -legacy -nocerts -out c:\Apache24\ssl\Apache24.key -passout pass:password
  2. Sign your newly generated Certificate Request using your CA (Certifying Authority) and paste it into the following file:

    C:\oracle\Middleware\EPMSystem11R1\ssl\essbase.cer.

Obtaining and Installing Root CA Certificate

The root CA certificate verifies the validity of the certificate that is used to support SSL. It contains the public key against which the private key that was used to sign the certificate is matched to verify the certificate. You can obtain the root CA certificate from the certificate authority that signed your SSL certificates.

Install the root certificate of the CA that signed the Essbase Server certificate on clients that connect to the Essbase Server or Agent. Ensure that the root certificate is installed in the keystore appropriate for the client. See Required Certificates and Their Location .

Note:

Multiple components can use a root CA certificate installed on a server machine.

Installing CA-Signed Certificates

For Installing CA-Signed Certificates, see the following links:

Update the tls.properties file under 

%EPM_HOME%\essbase\bin\tls_tools.properties:
certCA=c:\\ssl\\ca.crt;c:\\ssl\\intermediate.crt;c:\\ssl\\essbase.key;c:\\ssl\\essbase.cer;

Where:

C:\ssl\ca.crt – root CA certificate.
C:\ssl\intermediate.crt – intermediate CA certificate.
C:\ssl\essbase.key – your private key generated in the previous step.
C:\ssl\essbase.cer – your server’s signed certificate issued by your CA.

Execute the following to update Essbase server with the new certificates:

set ORACLE_HOME=c:\OracleSSL
set EPM_HOME=%ORACLE_HOME%
set WL_HOME=%ORACLE_HOME%\wlserver
set JAVA_HOME=%ORACLE_HOME%\jdk
set DOMAIN_HOME=%ORACLE_HOME%\user_projects\domains\essbase_domain
%EPM_HOME%\essbase\bin\tls_tools.properties:
%ORACLE_HOME%\\jdk\bin\java.exe -Xmx256m -jar %ORACLE_HOME%\essbase\lib\tlsTools.jar %EPM_HOME%\essbase\bin\tls_tools.properties

Updating Essbase SSL Settings

You customize the SSL settings for Essbase Server and clients by specifying values for the following in essbase.cfg.

  • Setting to enable secure mode
  • Setting to enable clear mode
  • Preferred mode to communicate with clients (used by clients only)
  • Secure port
  • Cipher suites
  • Oracle Wallet path

Note:

In essbase.cfg, be sure to add any missing required parameters, specifically, EnableSecureMode, AgentSecurePort, and set their values.

To update essbase.cfg located under: 

ESSBASE_DOMAIN_HOME\config\fmwconfig\essconfig\essbase
  1. Enter settings as needed. Default Essbase settings are implied. If you need to change the default behavior, add the settings for the custom behavior in essbase.cfg. For example, EnableClearMode is enforced by default, by which Essbase Server is enabled to communicate over nonencrypted channel. To turn off Essbase Server's ability to communicate over unencrypted channel, you should specify EnableClearMode FALSE in essbase.cfg. See the following table:

    Table 2-5 Essbase SSL Settings

    Setting Description 1
    EnableClearMode2 Enables unencrypted communication between Essbase applications and Essbase Agent. If this property is set to FALSE, Essbase does not handle non-SSL requests.

    Default: EnableClearMode TRUE

    Example: EnableClearMode FALSE
    EnableSecureMode Enables SSL encrypted communication between Essbase clients and Essbase Agent. This property must be set to TRUE to support SSL.

    Default: FALSE

    Example: EnableSecureMode TRUE
    SSLCipherSuites A list of cipher suites, in order of preference, to use for SSL communication. Essbase Agent uses one of these cipher suites for SSL communication. The first cipher suite in the list is accorded the highest priority when the agent chooses a cipher suit.

    Default: SSL_RSA_WITH_RC4_128_MD5

    Example: SSLCipherSuites SSL_RSA_WITH_AES_256_CBC_SHA256,SSL_RSA_WITH_AES_256_GCM_SHA384
    APSRESOLVER URL of Oracle Hyperion Provider Services. If you are using several Provider Services servers, separate each URL using a semicolon.

    Example: https://exampleAPShost1:PORT/essbase;https://exampleAPShost2:PORT/essbase
    AgentSecurePort

    The secure port at which the agent listens.

    Default: 6423

    Example: AgentSecurePort 16001
    WalletPath Location of the Oracle Wallet (fewer than 1,024 characters) that stores the root CA certificate and signed certificate.

    Default: ARBORPATH/bin/wallet

    Example: WalletPath/usr/local/wallet
    ClientPreferredMode 3 The mode (Secure or Clear) for the client session. If this property is set to Secure, SSL mode is used for all sessions.

    If this property is set to Clear, transport is chosen based on whether the client login request contains the secure transport keyword. See Establishing a Per-Session SSL Connection.

    Default: CLEAR

    Example: ClientPreferredMode SECURE
    • 1 The default value is enforced if these properties are not available in essbase.cfg.
    • 2 Essbase becomes nonoperational if EnableClearMode and EnableSecureMode are both set to FALSE.
    • 3 Clients use this setting to determine whether they should establish a secure or nonsecure connection with Essbase.
  2. Save and close essbase.cfg.

Updating Distributed Essbase Nodes for SSL

Note:

This section applies only to distributed deployment of Essbase

Ensure that the Wallet folder (for example, WalletPath/usr/local/wallet) containing the root CA certificate and signed certificate is in the required location on each distributed node.

  1. Import all the new CA certificate using TLS tools.

    For further information, see the following links:

  2. Go the source location: ESSBASE_DOMAIN_HOME\config\fmwconfig\essconfig\essbase and modify the following properties in the essbase.properties file:
    • essbase.ssleverywhere=true
    • olap.server.ssl.alwaysSecure=true
    • APSRESOLVER=APS_URL

      Replace APS_URL with Provider Services URL. If you are using several Provider Services servers, separate each URL using a semicolon.

      https://exampleAPShost1:PORT/essbase;https://exampleAPShost2:PORT/essbase.

  3. Copy Wallet folder, Walletssl folder, essbase.cfg file and essbase.properties file to the following destination paths.

    Table 2-6 Destination Paths

    Destination Paths Wallet Walletssl essbase.cfg essbase. properties

    EPM_ORACLE_HOME\common\EssbaseRTC-21C\11.1.2.0\bin

    		 Yes Yes Yes Yes

    EPM_ORACLE_HOME\common\EssbaseJavaAPI-21C\11.1.2.0\bin

    		 Yes Yes Yes Yes

    ESSBASE_DOMAIN_HOME\config\fmwconfig\essconfig\aps

    		 Yes Yes Yes Yes

    ESSBASE_DOMAIN_HOME\config\fmwconfig\essconfig\essbase

    		 Yes Yes Yes Yes

    MIDDLEWARE_HOME\essbase\products\Essbase\template_files\essbase

    		 Yes Yes Yes Yes

    MIDDLEWARE_HOME\essbase\products\Essbase\EssbaseServer\bin

    		 Yes Yes Yes Yes

    MIDDLEWARE_HOME\essbase\products\Essbase\aps\bin

    		 Yes Yes Yes Yes

    MIDDLEWARE_HOME\essbase\products\Essbase\eas

    		 Yes Yes Yes Yes

    MIDDLEWARE_HOME\essbase\common\EssbaseJavaAPI\bin

    		 Yes Yes Yes Yes
    For Oracle Hyperion Financial Reporting Only

    EPM_ORACLE_HOME/products/financialreporting/bin/EssbaseJAPI/bin/

    Note: In full SSL environments, Financial Reporting requires the Essbase Cluster Name to establish a connection. Connections fail if the hostname is used to connect.

    		Yes Yes Yes Yes
    For Oracle Hyperion Planning Only

    EPM_ORACLE_HOME/products/Planning/config/

    EPM_ORACLE_HOME/products/Planning/lib/

    		 Yes Yes Yes Yes

  4. Set the environment variables:

    • Windows: Create a new system variable named API_DISABLE_PEER_VERIFICATION and set its value to 1.
    • Linux: Add the directive API_DISABLE_PEER_VERIFICATION=1 in setCustomParamsPlanning.sh.

Customizing SSL Properties of JAPI Clients

Several default properties are predefined for the Essbase components that rely on JAPI. The default properties can be overridden by including properties in essbase.properties.

Note:

Only a few of the SSL properties identified in the following table are externalized in essbase.properties. You should add the properties that are not externalized.

To update SSL properties of JAPI clients:

  1. Using a text editor, open EPM_ORACLE_HOME/common/EssbaseJavaAPI-21C/11.2.0/bin/essbase.properties.
  2. Update properties as needed. See the following table for description of customizable JAPI client properties.

    If a desired property is not included in essbase.properties, add it.

    Table 2-7 Default SSL properties for JAPI Clients

    Property Description
    olap.server.ssl.alwaysSecure Sets the mode that clients should use against all Essbase instances. Change this property value to true to enforce SSL mode.

    Default: false
    olap.server.ssl.securityHandler Package name for handling the protocol. You can change this value to indicate another handler.

    Default: java.protocol.handler.pkgs
    olap.server.ssl.securityProvider Oracle uses the Sun SSL protocol implementation. You can change this value to indicate another provider.

    Default: com.sun.net.ssl.internal.www.protocol
    olap.server.ssl.supportedCiphers A comma-separated list of additional ciphers to be enabled for secure communication. You must specify only ciphers that Essbase supports.

    Example: SSL_RSA_WITH_AES_256_CBC_SHA256,SSL_RSA_WITH_AES_256_GCM_SHA384
    olap.server.ssl.trustManagerClass The TrustManager class to use to validate the SSL certificate by verifying the signature and checking the certificate expiration date.

    By default, this property is not set to enforce all verification checks.

    To not enforce verification checks, set the value of this parameter to com.essbase.services.olap.security.EssDefaultTrustManager, which is the default TrustManager class that allows all validation checks to succeed.

    To implement a custom TrustManager, specify a fully qualified class name of the TrustManager class that implements javax.net.ssl.X509TrustManager interface.

    Example:com.essbase.services.olap.security.EssDefaultTrustManager
  3. Save and close essbase.properties.
  4. Restart all Essbase components.