1. Security Configuration Guide
  2. SSL-Enabling EPM System Components
  3. SSL for Essbase 11.1.2.4
  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 Distinguished Name (DN). 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.

If you are using keytool, use a command such as the following to create a certificate request:

keytool -certreq -alias essbase_ssl -file C:/certs/essabse_server_csr -keypass password -storetype jks -keystore C:\oracle\Middleware\EPMSystem11R1\Essbase_ssl\keystore -storepass password

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.

Oracle Wallet

Refer to Required Certificates and Their Location for a list of components that require the CA root certificate in an Oracle Wallet. You can create a wallet or install the certificate in the demo wallet where the default self-signed certificate is installed.

See Oracle Wallet Manager documentation for detailed procedures to create wallets and to import the root CA certificate.

Java Keystore

Refer to Required Certificates and Their Location for a list of components that require the root CA certificate in an Java keystore. You can add the certificate into the keystore where the default self-signed certificate is installed or create a keystore for storing the certificate.

Note:

The root CA certificates of many well-known third-party CAs are already installed in the Java keystore.

Refer to the documentation of the tool that you are using for detailed instructions. If you are using keytool, use a command, such as the following, to import the root certificate:

keytool -import -alias blister_CA -file c:/certs/CA.crt -keypass
password -trustcacerts -keystore C:\Oracle\Middleware\EPMSystem11R1\Essbase_ssl
\keystore -storepass password

Installing Signed Certificates

You install the signed SSL certificates on the server that hosts Essbase Server and Essbase Agent. Components that use Essbase RTC (C APIs) to establish a connection to Essbase Server or Agent require that the certificate be stored in an Oracle Wallet with the root CA certificate. Components that use JAPI to establish a connection to Essbase Server or Agent require that the root CA certificate and signed SSL certificate be stored in a Java keystore. For detailed procedures, see these information sources:

  • Oracle Wallet Manager documentation
  • Documentation or online help for the tool; for example, keytool, that you use to import the certificate

If you are using keytool, use a command, such as the following, to import the certificate:

keytool -import -alias essbase_ssl -file C:/certs/essbase_ssl_crt -keypass password -keystore
 C:\Oracle\Middleware\EPMSystem11R1\Essbase_ssl\keystore -storepass password

Update Essbase Server Registry Values

Windows

  1. In a command prompt, change directory to EPM_ORACLE_INSTANCE/epmsystem1/bin.
  2. Run these commands to update Windows Registry:

    epmsys_registry.bat updateproperty "#<Object ID>/@EnableSecureMode" true

    epmsys_registry.bat updateproperty "#<Object ID>/@EnableClearMode" false

    Be sure to replace <Object ID> with the Essbase Server component ID, which is available in the Registry Report that is generated after you complete the Essbase Server configuration process.

Linux

  1. In a console, change directory to EPM_ORACLE_INSTANCE/epmsystem1/bin.
  2. Run these commands to update registry:

    epmsys_registry.sh updateproperty "#<Object ID>/@EnableSecureMode" true

    epmsys_registry.sh updateproperty "#<Object ID>/@EnableClearMode" false

    Be sure to replace <Object ID> with the Essbase Server component ID, which is available in the Registry Report that is generated after you complete the Essbase Server configuration process.

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:

  1. Copy Oracle wallet with certificates for Essbase Server to EPM_ORACLE_INSTANCE/EssbaseServer/essbaseserver1/bin/wallet.

    This is the only Oracle Wallet location acceptable to the Essbase Server.

  2. Using a text editor, open EPM_ORACLE_INSTANCE/EssbaseServer/essbaseserver1/bin/essbase.cfg.
  3. 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-2 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: APSRESOLVER https://exampleAPShost1:PORT/aps;https://exampleAPShost2:PORT/aps
    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
    ClientPreferredMode3 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.

  4. 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. Copy the Wallet folder to these locations in each distributed node:
    • EPM_ORACLE_HOME/common/EssbaseRTC/11.1.2.0/bin
    • EPM_ORACLE_HOME/common/EssbaseRTC-64/11.1.2.0/bin
  2. Copy the Wallet folder to these locations, if present, in each distributed node:
    • EPM_ORACLE_HOME/products/Essbase/EssbaseServer/bin
    • EPM_ORACLE_HOME/products/Essbase/EssbaseServer-32/bin
    • EPM_ORACLE_INSTANCE/EssbaseServer/essbaseserver1/bin
  3. Copy EPM_ORACLE_INSTANCE/EssbaseServer/essbaseserver1/bin/essbase.cfg to these locations on each distributed node:
    • EPM_ORACLE_HOME/common/EssbaseRTC/11.1.2.0/bin
    • EPM_ORACLE_HOME/common/EssbaseRTC-64/11.1.2.0/bin
  4. Copy EPM_ORACLE_INSTANCE/EssbaseServer/essbaseserver1/bin/essbase.cfg to these locations, if present, on each distributed node:
    • EPM_ORACLE_HOME/products/Essbase/EssbaseServer/bin
    • EPM_ORACLE_HOME/products/Essbase/EssbaseServer-32/bin
    • EPM_ORACLE_INSTANCE/EssbaseServer/essbaseserver1/bin
  5. Copy the Wallet folder to these Essbase client installation locations on each distributed node:
    • EPM_ORACLE_HOME/products/Essbase/EssbaseClient/bin
    • EPM_ORACLE_HOME/products/Essbase/EssbaseClient-32/bin
  6. Copy EPM_ORACLE_INSTANCE/EssbaseServer/essbaseserver1/bin/essbase.cfg to these Essbase client installation locations on each distributed node:
    • EPM_ORACLE_HOME/products/Essbase/EssbaseClient/bin
    • EPM_ORACLE_HOME/products/Essbase/EssbaseClient-32/bin
  7. Add these properties to the essbase.properties file:
    • essbase.ssleverywhere=true
    • olap.server.ssl.alwaysSecure=true
    • APSRESOLVER=http[s]://host:httpsPort/aps

      Be sure to replace this value with the appropriate URL.

    You must update essbase.properties file at these locations, if present, in each distributed node:

    • EPM_ORACLE_HOME/common/EssbaseJavaAPI/11.2.0/bin/essbase.properties
    • EPM_ORACLE_HOME/products/Essbase/aps/bin/essbase.properties
    • EPM_ORACLE_INSTANCE/aps/bin/essbase.properties
  8. Copy EPM_ORACLE_HOME/products/Essbase/aps/bin/essbase.properties to EPM_ORACLE_HOME/products/Essbase/eas directory, if available, on each distributed node.
  9. For Oracle Hyperion Planning Only: Add these three properties to 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. For example, https://exampleAPShost1:PORT/aps;https://exampleAPShost2:PORT/aps.

      You must update essbase.properties file at these locations in each distributed node:

      • EPM_ORACLE_HOME/products/Planning/config/essbase.properties
      • EPM_ORACLE_HOME/products/Planning/lib/essbase.properties
  10. For Oracle Hyperion Financial Reporting Only: Add these three properties to the EPM_ORACLE_HOME/products/financialreporting/bin/EssbaseJAPI/bin/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. For example, https://exampleAPShost1:PORT/aps;https://exampleAPShost2:PORT/aps.

    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.
    1. 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.
    2. Add the directive API_DISABLE_PEER_VERIFICATION=1 in EPM_ORACLE_INSTANCE/EssbaseServer/essbaseserver1/bin/setEssbaseenv.bat or EPM_ORACLE_INSTANCE/EssbaseServer/essbaseserver1/bin/setEssbaseenv.sh.
    Set environment variables:

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/11.1.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-3 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.