4 Prerequisite Requirements and Preliminary Setup

This chapter describes prerequisite requirements and preliminary setup that you must satisfy before you begin installing Business Transaction Management. Business Transaction Management is composed of several types of components. Some of the following requirements pertain to all Business Transaction Management components while other requirements pertain to a subset of components.

Web Browser Requirements

The requirements in this section pertain to the web browser that you use to perform the initial configuration of Business Transaction Management and to access the Business Transaction Management Console.

  • The web browser requires the Adobe Flash plugin version 9 or higher.

  • If you are using Internet Explorer as your web browser, you must configure it to allow the Flash player's Active X control. Consult your Internet Explorer documentation for instructions on enabling this setting.

Configuring Secure Communications Between Business Transaction Management Components

Note:

If you choose to perform the configuration described in this section, then you must do so on each application server that hosts a Business Transaction Management central server, monitor, or observer. You must also perform this configuration for the execution environment in which you use the Business Transaction Management command line interface (CLI).

Communications between Business Transaction Management components are secured by way of trusted assertions. This means that for your Business Transaction Management components to communicate with each other, and for your Business Transaction Management installation to function properly, every Business Transaction Management component must be configured with an assertion secret of the same value.

Business Transaction Management also encrypts sensitive data contained in the communications between its components. It encrypts this data for both on-the-wire communications and storage in the Business Transaction Management databases.

These security mechanisms are enabled by default, and all Business Transaction Management components are preconfigured with a default value for both the assertion secret and the encryption key. This default security configuration fully enables the security mechanisms and, at the same time, simplifies the installation of Business Transaction Management.

However, because every Business Transaction Management installation uses the same default values, using the default values is a potential security threat. For demonstration purposes, and perhaps for development environments, using the default values might be adequate. But, in production environments, you should tighten security by providing your own unique values. You should also use your own values in your test environment before deploying Business Transaction Management into your production environment. If you intend to provide your own values for the assertion secret and encryption key, you should perform that configuration on each application server that hosts a Business Transaction Management component before you deploy the component.

For components deployed to WebLogic servers, you have a choice as to the method you use for configuring and storing these security settings—you can use either Oracle Wallet or Java system properties. (Oracle Wallet is an implementation of Oracle Credential Store Framework, or OCSF, and is a component of Java Platform Security, or JPS.) For all other Java application servers you use Java system properties. And, for observers deployed to .NET execution environments, you use environment variables.

You should use Oracle Wallet, if possible, because this method provides a tighter level of security. Oracle Wallet stores the assertion secret and encryption key in files that are protected by the operating system's file system security. Java system properties and environment variables, on the other hand, are visible to any user that has access to the machine. If necessary, you can mix these security configuration methods. For example, you could use Oracle Wallet on some application servers but use Java system properties (or environment variables for .NET observers) on other application servers.

Configuring Security Using Oracle Wallet

This section pertains to central servers, monitors, and observers that will be deployed to WebLogic application servers, only. It explains how to configure the assertion secret and encryption key for your Business Transaction Management components using Oracle Wallet. You must repeat this procedure for each central server, monitor, and observer for which you want to configure the assertion secret and encryption key using Oracle Wallet.

  1. Ensure that the WebLogic domain in which the Business Transaction Management component will be installed includes the Java Runtime Files (JRF) template.

    If the domain does not yet exist, be sure to add the JRF template when you create the domain. If the domain already exists but doesn't include the JRF template, extend the domain and add the template.

    The JRF template includes the JPS JAR files that are referred to in later steps. (JPS is a component of Oracle Platform Security Services.)

  2. Decide on names for the credentials that will hold your shared secret and encryption key.

    You are free to choose any name you want, but each of the two credentials must have a different name, and you must use the same two credential names for all of your Business Transaction Management components.

  3. Decide on values for your issuer name and issuer assertion secret.

    You are free to choose any values you want for these strings, but you must use the same values for all of your Business Transaction Management components.

  4. Locate the distribution archive for the Business Transaction Management central servers and expand it into a directory on the machine that hosts the central server, monitor, or observer for which you want to configure security (this directory is henceforth referred to as BTM_Central_Expanded).

    The distribution archive is named BTM_MonitorServices*.zip, where * represents the version number.

  5. Configure the setBtmOverriderEnv_via_CredStore script file by completing the following substeps.

    Configuring the setBtmOverriderEnv_via_CredStore script file accomplishes these tasks: adds the JPS JAR files to your application server's classpath; overrides the default credential store; and specifies the names of the credentials that hold the shared secret and encryption key (note that you will create the credentials in a later step).

    1. Locate the setBtmOverriderEnv_via_CredStore script file in BTM_Central_Expanded/security_add_ons.

      For Windows systems, use setBtmOverriderEnv_via_CredStore.cmd; for UNIX-like systems, use setBtmOverriderEnv_via_CredStore.sh.

    2. Copy the script file to your WebLogic server:

      If you want to configure security for all domains, copy the script file to your WebLogic server's home directory. The home directory is the weblogic92 or wlserver_10.3 directory located in your WebLogic installation directory, for example, C:\bea\wlserver_10.3.

      If you want to configure security for a particular domain, copy the script file to the top level of that domain's directory.

    3. Open the script file in a text editor.

    4. Specify the name of the credential that holds the assertion secret by replacing the string >>> YOUR_ISSUER_SECRET_CREDENTIAL_NAME_HERE <<< with the credential name you chose for your assertion secret.

    5. Specify the name of the credential that holds the encryption key by replacing the string >>> YOUR_ENCRYPT_KEY_CREDENTIAL_NAME_HERE <<< with the credential name you chose for your encryption key.

    6. Save and close the script file.

  6. Configure your WebLogic domain startup scripts to call the setBtmOverriderEnv_via_CredStore script file:

    Note:

    This step assumes that you haven't modified your startWebLogic scripts. If you have modified your scripts, you might also have to modify the installation procedure accordingly.
    1. Navigate to the bin directory of one of the WebLogic domains for which you want to configure security and open the startup script in a text editor (open bin\startWebLogic.cmd for Windows systems or bin/startWebLogic.sh for UNIX-like systems; do not edit the startup script located directly within the domain directory).

    2. Locate the following line (the first line is for Windows and the second for UNIX-like systems):

      call "%DOMAIN_HOME%\bin\setDomainEnv.cmd"
      
      . ${DOMAIN_HOME}/bin/setDomainEnv.sh
      
    3. Directly after that line, add a line that calls the setBtmOverriderEnv_via_CredStore script file:

      If you are configuring security for all domains on a Windows system, add this line:

      call "%WL_HOME%\setBtmOverriderEnv_via_CredStore.cmd"
      

      If you are configuring security for all domains on a UNIX-like system, add this line (note the initial period and space):

      . ${WL_HOME}/setBtmOverriderEnv_via_CredStore.sh   
      

      If you are configuring security for a particular domain on a Windows system, add this line:

      call "%DOMAIN_HOME%\setBtmOverriderEnv_via_CredStore.cmd"
      

      If you are configuring security for a particular domain on a UNIX-like system, add this line (note the initial period and space):

      . ${DOMAIN_HOME}/setBtmOverriderEnv_via_CredStore.sh
      
    4. Repeat this step for each domain for which you want to configure security.

  7. Add permission grants for Business Transaction Management components to the policy store:

    1. Navigate to the config\fmwconfig directory of one of the WebLogic domains for which you are configuring security.

      This directory was created when you extended the domain to include the JRF template and is the default location where the oracle.security.jps.config property looks.

    2. Open the file system-jazn-data.xml in a text editor.

    3. For each deployment in the domain for which you want to configure security, add a <grant> element as a child of the <jazn-data>/<jazn-policy> element, replacing the string Your Deployment Name Here with the name of the deployment, as shown in the following example:

      <jazn-data>
       <jazn-policy>
       (... other <grant> elements, etc. ...)
       
        <!-- Begin of Business Transaction Management grants -->
        <grant>
         <grantee>
          <codesource>
           <url>file:${domain.home}/servers/${weblogic.Name}/tmp/_WL_user/Your Deployment Name Here/-</url>
          </codesource>
         </grantee>
         <permissions>
          <permission>
           <class>
            oracle.security.jps.service.credstore.CredentialAccessPermission
           </class>
           <name>context=SYSTEM,mapName=BTM,keyName=*</name>
           <actions>read,write</actions>
          </permission>
         </permissions>
        </grant>
        <!-- End of Business Transaction Management grants -->
       
       (... other <grant> elements, etc. ...)
       </jazn-policy>
      </jazn-data>
      

      Table 1-1 lists the deployment names for the central servers and monitors. For observers, use the name of the deployment that contains the business application you want to monitor.

    4. Save and close the file.

    5. Repeat this step for each domain for which you want to configure security.

  8. Use the Business Transaction Management command line interface (CLI) to create a “Trusted Issuer and Secret” credential that contains your assertion secret and add it to the Oracle Wallet credential store associated with the policy store that you just configured:

    In the following substeps, you will first set up the environment for the CLI, then point the CLI to the Oracle Wallet credential store, and finally use the CLI to create the credential for your assertion secret and add it to the store.

    1. Open a command shell or window and ensure that its JAVA_HOME and JPS_11_HOME environment variables are set properly.

      These variables can be set at the system or the shell/window level. The JAVA_HOME variable must point to a JDK that is version 6 or higher. The JPS_11_HOME variable must point to your oracle.jps file, for example, to:

      oracle\Middleware\oracle_common\modules\oracle.jps_11.1.1
      
    2. Open the file BTM_Central_Expanded/security_add_ons/jps_config_dir/jps-config.xml in a text editor and locate the following line:

      <serviceInstance name="credstore" provider="credstoressp" location="./">
      
    3. Change the value of the location attribute from ./ to the /config/fmwconfig/ directory under the WebLogic domain directory, for example:

      <serviceInstance name="credstore" provider="credstoressp" location="C:/Oracle/Middleware/user_projects/domains/my_domain/config/fmwconfig/">
      

      The value of the location attribute must match the location of the %DOMAIN_HOME%\config\fmwconfig directory where you configured the policy store for your domain, in step 7.

    4. In your command shell/window, navigate to the BTM_Central_Expanded/tools directory and issue the following command (replacing my_credential_name with the name you chose for this credential in step 5d):

      btmcli credStoreTool -createCred my_credential_name -credType is
      

      The CLI then prompts you for the Trusted Assertion Issuer and the Trusted Assertion Secret. The latter is masked with asterisks as you type.

    5. Input the values for the Trusted Assertion Issuer and the Trusted Assertion Secret (and keep the command shell/window open for the next step).

      Use the values you chose in step 3.

      Note:

      If you prefer not to use the interactive mode, you can provide the issuer name and assertion secret by appending -credValue my_issuer:my_secret to the command line. However, using interactive mode is more secure because of the masking.

    The credential for your assertion secret has now been created and added to the Oracle Wallet credential store.

  9. In the same command shell/window, use the CLI to create a credential for your encryption key by issuing the following command (replacing my_credential_name with the name you chose for this credential in step 5e):

    btmcli credStoreTool -createCred my_credential_name -credType bin -genKey AES:128
    

    This command creates a credential with the given name, generates an AES, 128-bit, random encryption key, and adds it to the Oracle Wallet credential store.

  10. Retrieve the encryption key for use in configuring the other machines in your system by issuing the following command (replacing my_credential_name with the name of your credential):

    btmcli credStoreTool -getCred my_credential_name -credType bin -showSecret
    

    This command returns the string value of your encryption key. You will need to copy this string to the other machines in your system as your configure them.

  11. Repeat the pertinent steps of this procedure for each central server, monitor, and observer for which you want to configure the assertion secret and encryption key using Oracle Wallet, but replace steps 9 and 10 with the following step:

    On repetition, skip steps 2 and 3 (you will use the same credential names and issuer name and issuer assertion secret values that you used on the first machine). Also, issue the following CLI command instead of the commands shown in steps 9 and 10 (replacing my_credential_name with the name of your credential, and my_encryption_key_string with the string you retrieved in step 10.):

    btmcli credStoreTool -createCred my_credential_name -credType bin -credValue my_encryption_key_string
    

    This command creates a credential with the given name and encryption key, and adds it to the Oracle Wallet credential store.

Configuring Security Using Java System Properties

This section pertains to the central servers and monitors, and to observers deployed in Java environments. It explains how to configure the assertion secret and encryption key using Java system properties.

Configuring the Assertion Secret Using Java System Properties

You must configure the assertion secret on each application server that hosts a Business Transaction Management component. To configure the assertion secret, you must set two Java system properties and, optionally, a third Java system property. You set these system properties in the server hosting the Business Transaction Management component.

This example shows how to set the first required system property:

-Dcom.amberpoint.SimpleIdentityAssertion.TrustedIssuerOverriderClassName=com.amberpoint.wsclient.TrustedIssuerOverriderByExtProp

This example shows how to set the second required system property:

-Dcom.amberpoint.SimpleIdentityAssertion.TrustedIssuerSecretOverride=MySecret

where MySecret is your own secret string.

By default, the name of the issuer of the security assertion is AmberPoint. You can override the default issuer's name by creating a third system property. This example shows how to set this property:

-Dcom.amberpoint.SimpleIdentityAssertion.TrustedIssuerNameOverride=MyIssuerName

where MyIssuerName is the name of the issuer of the security assertion.

Configuring the Encryption Key Using Java System Properties

You must configure the encryption key on each application server that hosts a Business Transaction Management component. To configure the encryption key, create a Java system property named com.amberpoint.security.encryption.aes.defaultKey in the server and set its value to your encryption key, for example:

-Dcom.amberpoint.security.encryption.aes.defaultKey=MyEncryptionKey

where MyEncryptionKey is a base 64-encoded, AES, 128-bit key.

After generating your encryption key, you can copy and paste it in order to set the value of your com.amberpoint.security.encryption.aes.defaultKey property. If your key includes special characters, you should enclose it in double quotes, for example:

-Dcom.amberpoint.security.encryption.aes.defaultKey="oylJKoTGXTHasOYwtjwA7g=="

Configuring Security for Observers Deployed in .NET Environments

This section pertains only to observers deployed in .NET environments. It explains how to configure the assertion secret and encryption key using environment variables. You must perform these configurations for each .NET environment that hosts an observer.

Configuring the Assertion Secret

To configure the assertion secret, you must set two environment variables and, optionally, a third environment variable as follows:

  1. Create an environment variable named:

    com.amberpoint.SimpleIdentityAssertion.TrustedIssuerOverriderClassName
    

    and set its value to:

    AmberPoint.Wsutility.Wsclient.TrustedIssuerOverriderByExtProp
    
  2. Create an environment variable named:

    com.amberpoint.SimpleIdentityAssertion.TrustedIssuerSecretOverride
    

    and set its value to your assertion secret string.

  3. Optional – By default, the name of the issuer of the security assertion is AmberPoint. You can override the default issuer's name by creating an environment variable named:

    com.amberpoint.SimpleIdentityAssertion.TrustedIssuerNameOverride
    

    and setting its value to the issuer name.

Configuring the Encryption Key

Configure the encryption key as follows:

  1. Generate a base 64-encoded, AES, 128-bit encryption key.

  2. On on the machine hosting the observer, create an environment variable named:

    com.amberpoint.security.encryption.aes.defaultKey
    

    and set its value to your generated encryption key.

Configuring HTTPS

This section pertains to the central servers.

If you are installing the central servers into an HTTPS-only environment (that is, an environment in which there is no HTTP traffic between components), you must do one of the following:

  • Ensure that the application servers hosting the central servers are listening only on HTTPS ports.

    Or

  • Modify each web.xml file packaged in each of the central server WAR files so as to specify that only HTTPS access is allowed. You can do this by simply uncommenting the <security-constraint> element that is provided in those files. The element looks like this:

    <security-constraint>
      <display-name>Require SSL communication</display-name>
      <web-resource-collection>
        <web-resource-name>All AmberPoint system services</web-resource-name>
        <url-pattern>/*</url-pattern>
      </web-resource-collection>
      <user-data-constraint>
        <transport-guarantee>CONFIDENTIAL</transport-guarantee>
      </user-data-constraint>
    </security-constraint>
    

Configuring Firewalls

This section pertains the central servers, monitors, and observers.

If you are using a firewall, you must configure it to allow access to each port on which a Business Transaction Management component receives communications. These are the ports on which the hosting application servers listen and the sockets on which the monitors receive observation messages from the observers.

Setting up your WebLogic Environment

Note:

If you are using WebLogic Node Manager, you will use the WebLogic Administrative Console to adjust settings rather than edit scripts.
  1. Ensure that the appropriate database driver for your Oracle RDBMS is in the WebLogic server's classpath for each central server and monitor.

    Drivers are supplied in the jdbc directory of BTM_MonitorServices_*.zip. Use ojdbc5.jar with JDK 1.5 and ojdbc6.jar with JDK 1.6.

  2. Ensure that each WebLogic server in which you install a Business Transaction Management central server or monitor is uniquely identified so that the central servers and monitors can reliably connect to each other. You can perform this task in either of the following ways:

    • Ensure that any and all IP addresses assigned to the host machine uniquely identify that machine.

    • Ensure that the WebLogic server's Listen Address property is set to a hostname or IP address that uniquely identifies the server.

      To set this property, navigate in the WebLogic Administration Console to Environment > Servers, then click your server and display the Configuration/General tab.

    Note:

    If the machine has an IP address that is shared with another machine on the network, or the machine has multiple IP addresses that are treated as separate virtual machines, you must set the domain's Listen Address property as described above.
  3. For central servers and monitors, ensure that memory allocation for your WebLogic server is set appropriately. Two methods of setting the Java options that control memory allocation are described below. Use the method that is appropriate for how you start and stop your managed servers:

    If you use the Node Manager to remotely start and stop your managed servers, set the Java memory options for your server using this method:

    1. Open the WebLogic Administration Console.

    2. Select your managed server.

    3. Select the Configuration > Server Start tab.

    4. Enter the following Java options in the Arguments field, making sure to separate all entries in the field with a space:

      -Xms256m -Xmx768m -XX:MaxPermSize=256m
      

      These are the minimum recommended settings. Depending on your environment, you might have to set them higher.

    If you start and stop your managed servers by executing local script files, set the Java memory options for your server using this method:

    1. Open the setDomainEnv script file for your domain in a text editor.

      On Windows systems, open setDomainEnv.cmd; on UNIX-like systems, open setDomainEnv.sh. These script files are located in the user_projects\domains\domain_name\bin directory of your WebLogic installation.

    2. Locate the following settings and ensure that they are set to at least the values indicated (depending on your environment, you might have to set them higher.):

      MEM_ARGS=-Xms256m -Xmx768m
      
      -XX:MaxPermSize=256m
      

      There are several of these entries; set them all.

      Depending on your version of WebLogic, you might also see separate 32-bit and 64-bit settings like these:

      set WLS_MEM_ARGS_64BIT=-Xms256m -Xmx512m
      set WLS_MEM_ARGS_32BIT=-Xms256m -Xmx512m
      set MEM_MAX_PERM_SIZE_64BIT=-XX:MaxPermSize=256m
      set MEM_MAX_PERM_SIZE_32BIT=-XX:MaxPermSize=128m 
      

      In this case, set them all to at least the minimum recommended settings.

  4. Set up an administrative user on the WebLogic server in which you will install the Main server (btmMain.ear).

    Business Transaction Management maps roles defined in WebLogic to its own application roles. See Mapping WebLogic Users to Business Transaction Management Roles for more information.

Setting up your WebSphere Environment

  1. Ensure that the appropriate database driver for your Oracle RDBMS is in your WebSphere server's classpath for each central server and monitor.

    If you edit the classpath while the server is running, be sure to restart WebSphere before configuring Business Transaction Management.

    Drivers are supplied in the jdbc directory of BTM_MonitorServices_*.zip. Use ojdbc5.jar with JDK 1.5 and ojdbc6.jar with JDK 1.6.

  2. Use the WebSphere Administrative Console to specify Initial Heap Size of no less than 256, and Maximum Heap Size of no less than 1024.

    Perform this task on each WebSphere instance in which you install Business Transaction Management components.

  3. Enable global security on WAS, including application and Java 2 security.

    Perform this task on each WebSphere instance in which you install Business Transaction Management components.

  4. Set up an administrative user on the WebSphere server on which you will install the Main server (btmMain.ear).

    Business Transaction Management maps roles defined in WebSphere to its own application roles. See Mapping WebSphere Users to Business Transaction Management Roles for more information.

Setting up Business Transaction Management Databases

Several Business Transaction Management system services use a database to store persistent information and log messages. You must use an Oracle 10g or 11g RDBMS for these databases, and it must be configured to support SQL authentication mode and TCP/IP connections.

Before you configure Business Transaction Management, create the following database users (these are suggested names):

  • sphereDB

  • measurementDB

  • transactionDB

  • messageLogDB

You can create the database users in the same Oracle instance or in separate instances. You must create these users before starting configuration of Business Transaction Management. When you configure Business Transaction Management (see Initial Configuration of Business Transaction Management), the system will automatically create the appropriate database tables.

If you prefer to create the schemas manually for the first three of these databases (sphereDB, measurementDB, and transactionDB), your DBA can create them beforehand (see the following note). If you intend to let the system automatically create these tables and indexes, the database users must have create table, create index, create view, and analyze privileges. You cannot create the fourth schema (messageLogDB) beforehand because the system must be able to create and drop tables dynamically in response to changes in your monitored applications. For this database, the user must have create table, drop table, create index, create view, and analyze privileges. (Note: It is not sufficient to assign the privileges to the roles associated with the user. You must explicitly assign the privileges to the user.)

Note:

Your DBA can manually create the tables and indexes for the sphereDB, measurementDB, and transactionDB databases using the datastoreUtil utility. This utility generates the appropriate schema definitions. Documentation on using this utility to generate the schema definitions is provided in Chapter 16, "The datastoreUtil Utility."