28.3 Installing on a WebSphere Application Server

This section describes how to install the User Application for RBPM on a WebSphere Application Server by using the graphical user interface version of the installation program.

For more information about ...

See ...

Prerequisites for installing on a WebSphere Application Server

Section 6.7, Prerequisites and Requirements for Installing the User Application and Roles Based Provisioning Module

Hardware and software requirements for installing on a WebSphere Application Server

Section 6.7.6, System Requirements for Installing the User Application and Roles Based Provisioning Module

Using the console to install the User Application

Section 29.1, Performing a Guided Installation from the Command Line

Using a single command to install the User Application

Section 29.2, Installing the User Application with a Single Command

28.3.1 Checklist for Installing the User Application on WebSphere

Use the following checklist to guide you through the process of installing the User Application on a WebSphere application server.

 

Checklist Items

  1. Prepare the DB2 database to support the User Application. For more information, seeConfiguring a DB2 Database.

  1. Configure a data source file and JDBC provider for the database. For more information, see Section 28.3.2, Configuring a Data Source for the User Application Database on WebSphere.

  1. Install a supported version of WebSphere application server and Java development kit or runtime environment. For more information, see Section 6.7.6, System Requirements for Installing the User Application and Roles Based Provisioning Module.

  1. Create a WebSphere-enabled WAR for the User Application. For more information, see Section 28.2.3, Installing the User Application with the Installation Wizard.

  1. Prepare the WebSphere application server environment for running the User Application. For more information, see the following sections:

  1. Deploy and log on to the User Application. For more information, see Section 28.3.9, Starting the User Application on the WebSphere Server.

28.3.2 Configuring a Data Source for the User Application Database on WebSphere

Before installing the User Application, you must have an existing data source file that points to the database. For WebSphere environments, you must manually create a JDBC Provider and a data source file.

  1. Open the Integrated Solutions Console, which allows you to configure and administer WebSphere Application Server (WAS). By default, http://host_name:9060/ibm/console.

  2. In the left pane of the console, expand Resources > JDBC.

  3. To create the JDBC provider, complete the following steps:

    1. Click JDBC providers.

    2. In the content pane, expand Scope.

    3. Select Node=yourservername, Server=server1.

    4. Click New.

    5. For Database Type, specify the type of database you plan to use. For example, DB2.

    6. Click Next.

    7. Specify the classpath for the JDBC provider.

    8. Click Next.

    9. Click Finish.

    10. Click Save to save the changes directly to the master configuration.

  4. To create the data source file, complete the following steps:

    1. Click Data sources (in the left pane under JDBC).

    2. In the content pane, expand Scope.

    3. Select Node=yourservername, Server=server1.

    4. Click New.

    5. Specify the name of the data source file and the JNDI. For example, IDMUADatasource for both fields.

    6. Click Next.

    7. Click Select an existing JDBC provider.

    8. Select the JDBC Provider that you created in Step 3.

    9. Click Next.

    10. Specify the name, server name, port, username, and password for the database.

    11. Click Next.

    12. (Optional) Specify information for the Security Alias.

    13. Click Next.

    14. Click Finish.

    15. Click Save.

    16. In the Data Sources pane, click the box to the left of your new data source file.

    17. To verify the settings, click Test Connection.

28.3.3 Installing the User Application on a WebSphere Server

This section explains how to use the User Application installation wizard. The following considerations apply to this process:

  • You must install a supported version of WebSphere Application Server before installing the User Application.

  • The installation program does not save the values that you enter as you progress through the windows in the wizard. If you click Previous to return to an earlier window, you must re-enter the configuration values.

  • The installation program creates the novlua user account and sets the permissions in the JBoss files to this user. The jboss_init script uses this user account to run JBoss.

To install the User Application with the installation wizard:

  1. Log on as a root user to the computer where you want to install the User Application.

  2. Apply the unrestricted policy files to the supported IBM JDK. Refer to your documentation for a link to these files from IBM and instructions for applying them. The JAR file for unrestricted policy files must be located in JAVA_HOME\jre\lib\security.

    Without these unrestricted policy files, an error will occur that says Illegal key size. The root cause of this problem is the lack of unrestricted policy files, so be sure to use the correct IBM JDK.

  3. In the IBM Java environment, enter one of the following commands to start the .jar file, by default in the products/RBPM/user_app/install folder within the .iso image file for Identity Manager. For example:

    Linux

    $ /opt/WS/IBM/WebSphere/AppServer/java/bin/java -jar IdmUserApp.jar

    Windows

    C:\WS\IBM\WebSphere\AppServer\java\bin\java -jar IdmUserApp.jar

  4. In the Welcome page of the User Application installation program, specify the language that you want to use for installation, and then click OK.

  5. In the License Agreement window, click I accept the terms of the License Agreement and then click Next.

  6. In the Application Server Platform window, click WebSphere and then click Next.

  7. In the Install Folder window, specify the folder where you want to place the installation files and then click Next.

  8. In the Database Platform window, specify the platform of the User Application database. For example, Oracle. Click Next.

  9. In the Database Host and Port window, specify the hostname or IP address of the server hosting the User Application database.

    For a cluster, you must specify the same name or IP addreess for each member of the cluster.

  10. For Port, specify the number of the listener port for the database.

    For a cluster, you must specify the same port for each member of the cluster.

  11. Click Next.

  12. In the Database Username and Password window, specify the name of the database according to the database platform. By default, the database name is idmuserappdb.

    • For a PostgreSQL, DB2, or SQL Server database, specify the name or Security Identifier (SID).

    • For an Oracle database, specify the SID that you created with the database instance.

    • For a cluster, you must specify the same database name or SID for each member in the cluster.

  13. Specify the name for the database user account to use with the User Application and the password associated with the user account.

    In a cluster environment, you must use the same user account and password for each member in the cluster.

  14. (Conditional) For a DB2 database, specify the two JAR files for the database server: db2jcc.jar and db2jcc_license_cu.jar.

    To separate the names, use the correct file separator for the operating system on which you want to install the database.

    For example, on Windows computers, enter:

    c:\db2jars\db2jcc.jar;c:\db2jars\db2jcc_license_cu.jar

    On Linux computers, enter:

    /home/lab/db2jars/db2jcc.jar:/home/lab/db2jcc_license_cu.jar

  15. (Conditional) For SQL Server, PostgreSQL, and Oracle databases, specify the JAR file for the database server.

    The database vendor provides the driver JAR file, which represents the Thin Client JAR for the database server. For example, for PostgreSQL, specify postgresql-8.4-701.jdbc4.jar, by default in the novell\idm\Postgres folder. NetIQ does not support driver JAR files from third-party vendors.

  16. Click Next.

  17. (Optional) In the Database Administrator window, specify the name and password for the database administrator.

    This field automatically lists the same user account and password that you specified in Step 14. To use that account, do not make any changes.

  18. Click Next.

  19. In the Create Database Tables window, select one of the following options:

    Create Tables Now

    The installation program creates the database tables as part of the installation process.

    Create Tables at Application Startup

    The installation program leaves instructions to create the tables when the User Application starts for the first time.

    Write SQL to File

    Create a schema file at installation time for the database administrator to use later to create the tables. When selecting this option, you must also specify a name for the file in the Schema Output File window.

  20. Click Next.

  21. (Conditional) If you chose Create Tables Now or Write SQL to File in Step 19, specify whether the database is a new or empty database or it already exists from a previous installation. Click Next.

  22. To verify that the User Application can connect to the specified database, click Test Database Connection and then click Next.

    This step enables the installer to connect to the database for creating tables directly or for creating the .sql file.

    NOTE:You can continue with installation if the database connection fails. However, after installation, you must manually create the tables and connect to the database. For more information, see “Recreating the Database after Installation” in the User Application Administration Guide.

  23. In the Java Install window, specify the path to the Java root installation folder and then click Next.

  24. For Application Context in the IDM Configuration window, specify a name that represents the application server configuration, the application WAR file, and the name in the URL context.

    The installation script creates a server configuration, then names the configuration according to the name that you created when installing the application server. For example, IDMProv.

    IMPORTANT: NetIQ recommends that you make a note of the specified Application Context. You will use this application name in the URL when you start the User Application from a browser.

  25. Click Next.

  26. (Optional) To send log events to an auditing server, complete the following steps in the Select Audit Logging Type window:

    1. Click Yes and then click Next.

    2. In the Audit Logging window, specify the type(s) of logging that you want to enable:

      Novell Identity Audit or NetIQ Sentinel

      Enables logging through a Novell client for the User Application.

      OpenXDAS

      Enables the User Application to send events to your OpenXDAS logging server.

    3. Click Next.

    4. (Conditional) If you chose in Step 26.b to send log events through a Novell or NetIQ client, in the Novell Identity Audit or NetIQ Sentinel window, specify the hostname or IP address for the client server and the path to the log cache.

      For more information about setting up logging, see the User Application Administration Guide.

  27. Click Next.

  28. (Optional) To import an existing master key, complete the following steps in the Security - Master Key window:

    NOTE:

    • The User Application uses the master key to access encrypted data.

    • You must complete these steps after installing the first instance of the User Application in a cluster. Every instance of the User Application in a cluster must use the same master key. For more information, see Section 27.2.4, Using the Same Master Key for Each User Application in the Cluster.

    • Complete these steps if you are moving your installation from a staging system to a production system and want to keep access to the database you used with the staging system.

    • Complete these steps also if you are restoring your User Application and you want to access the encrypted data stored by your previous version of the User Application.

    • By default, the installation procedure writes the encrypted master key to the master-key.txt file in the installation directory.

    1. Click Yes and then click Next.

    2. In the Import Master Key window, copy and paste the master key from the master-key.txt file.

  29. Click Next.

  30. (Conditional) If, at this time, you do not want to specify the settings for the User Application to interact with RBPM, click No in the Configure IDM window.

    NOTE:After installing the User Application, you can modify most of the settings in the configureupdate.sh or configureupdate.bat files. For more information about specifying the values for the settings, see the tables in Section 30.2, Configuring the User Application. The tables also explain which settings are required, and whether you can edit them with the configuration update files.

  31. (Conditional) To immediately configure the User Application to interact with RBPM, complete the following steps in the Configure IDM window:

    1. Click Yes and then click Next.

    2. In the Roles Based Provisioning Module Configuration window, click Show Advanced Options.

    3. Modify the settings as needed.

      NOTE:

      • For more information about specifying the values, see the tables in Section 30.2, Configuring the User Application. The tables also explain which settings are required, and whether you can edit them with the configuration update files.

      • In production environments, all administrator assignments are restricted by licensing. NetIQ collects monitoring data in the audit database to ensure that production environments comply. Also, NetIQ recommends that only one user be given the permissions of the Security Administrator.

    4. Click OK.

  32. Click Next.

  33. In the Pre-Installation Summary window, click Install.

  34. (Optional) Review the installation log files. For results of the basic installation, see the Identity_Manager_User_Application_InstallLog.log file. For information about the User Application configuration performed in Step 31, see the Novell-Custom-Install.log file.

28.3.4 Adding User Application Configuration Files and JVM System Properties

This section helps you create new JVM system properties that the User Application requires to function on a WebSphere application server.

  1. Copy the sys-configuration-xmldata.xml file from the User Application installation directory to a directory on the computer that hosts the WebSphere server. For example /UserAppConfigFiles. For more information about the file, see Section 27.4, Preparing a WebSphere Cluster for the User Application.

    IMPORTANT:Configupdate.sh will update the local version of this file. In the future, if you run Configupdate.sh, you must update WebSphere's version of this file by copying it again. As a precaution, you should also make backup copies of all of the versions of this file.

  2. Log on to the WebSphere admin console as an admin user.

  3. Set the path to the sys-configuration-xmldata.xml file in the JVM system properties.

  4. In the left pane, click Servers > Application Servers.

  5. In the list of servers, click the server name. For example, server1.

  6. In the list of settings in the content pane, click Java and Process Management under Server Infrastructure.

  7. Expand the link and select Process Definition.

  8. Under the list of Additional Properties, select Java Virtual Machine.

  9. Select Custom Properties under the Additional Properties heading for the JVM page.

  10. To add the idmuserapp.logging.config.dir JVM system property, complete the following steps:

    1. Click New.

    2. For Name, specify extend.local.config.dir.

    3. For Value, specify the name of the install folder (directory) that you specified during installation.

      The installer wrote the sys-configuration-xmldata.xml file to this folder.

    4. For Description, specify a description for the property, for example path to sys-configuration-xmldata.xml.

    5. Click OK to save the property.

  11. To add the idmuserapp.logging.config.dir JVM system property, complete the following steps:

    1. Click New.

    2. For Name, specify idmuserapp.logging.config.dir.

    3. For Value, specify the name of the install folder (directory) that you specified during installation.

    4. For Description, specify a description for the property, for example path to idmuserapp_logging.xml.

    5. Click OK to save the property.

      The idmuserapp-logging.xml file does not exist until you persist the changes through User Application > Administration > Application Configuration > Logging.

  12. (Conditional) To specify the workflow engine ID for a clustered environment, complete the following steps:

    1. Click New.

    2. For Name, specify com.novell.afw.wf.engine-id.

    3. For Value, specify the ID for the workflow engine.

    4. For Description, specify a description for the property, for example workflow engine ID.

    5. Click OK to save the property.

28.3.5 Creating and Applying a Shared Library

If you are using WebSphere 7.0 with Version 4.0.2 of the RBPM, you must configure a shared library for RBPM. You must also apply the shared library to a new class loader. This will ensure that WebSphere uses the RBPM versions of these JAR files. Otherwise, you will encounter class loading problems with JAR files that have shipped with WebSphere. WebSphere class loading problems can manifest as the following kinds of exceptions:

  • ClassCastException

  • ClassNotFoundException

  • NoClassDefFoundException

  • UnsatisfiedLinkError

  • LinkageError

This process includes the following activities:

Configuring the Shared Library

  1. Log on to the WebSphere admin console as an admin user.

  2. In the left pane, expand Environment.

  3. Click Shared Libraries.

  4. In the content pane, click New.

  5. Specify a name, such as IDMUA Classpath.

  6. In the Classpath field, add the following required JAR files:

    • antlr.jar

    • log4j.jar

    • commons-logging.jar

      NOTE:You need to download this JAR file from the Apache site.

    • xalan.jar

    • xercesImpl.jar

    • xsltc.jar

    • jaxb-impl.jar

  7. Select Use an isolated class loader for this shared library.

  8. Click OK.

  9. Click Save to save the changes to the master configuration.

Applying the Shared Library to a New Class Loader

  1. Log on to the WebSphere admin console as an admin user.

  2. Expand Application servers > server-name > Class loader.

    NOTE:By default, this option is collapsed under the Java and Process Management section.

  3. In the content pane, click New to create a new class loader.

  4. Select Classes loaded with local class loader first (parent last).

  5. Click Apply.

  6. Select Shared library references.

  7. Click Add and then select the shared library that you created in Configuring the Shared Library.

  8. Click Apply.

  9. Click OK.

  10. Click Save to save the changes to the master configuration.

28.3.6 Importing the eDirectory Trusted Root to the WebSphere Keystore

This section helps you import the eDirectory trusted root certificates to the keystore on the computer hosting the WebSphere server. You can perform this process in one of the following ways:

Importing Certificates with the WebSphere Administrator’s Console

  1. Copy the eDirectory trusted root certificates to the computer hosting the WebSphere server.

    The User Application installation procedure exports the certificates to the directory in which you install the User Application.

  2. Log on to the WebSphere administration console as an admin user.

  3. In the left pane, expand Security > SSL Certificate and Key Management.

  4. In the content pane, select Key stores and certificates under Related Items.

  5. Select NodeDefaultTrustStore (or the trust store that you are using).

  6. Under Additional Properties, select Signer Certificates.

  7. Click Add.

  8. Type the Alias name and full path to the certificate file.

  9. Change the Data type in the drop-down list to Binary DER data.

  10. Click OK.

    You should now see the certificate in the list of signer certificates.

  11. Click Save to save the changes to the master configuration.

Importing Certificates with the Command Line

You must use the WebSphere keytool to import the certificate into the WebSphere keystore. By default, the WebSphere keytool is located in /IBM/WebSphere/AppServer/java/bin. The store type is PKCS12.

  1. Copy the eDirectory trusted root certificates to the computer hosting the WebSphere server.

    The User Application installation procedure exports the certificates to the directory in which you install the User Application.

  2. From the command line on the machine hosting the WebSphere server, run the WebSphere keytool.

    For example:

    keytool -import -trustcacerts -file servercert.der -alias myserveralias 
-keystore trust.p12 -storetype PKCS12

    NOTE:If you have more than one trust.p12 file on your system, you might need to specify the full path to the file.

28.3.7 Applying the Unrestricted Policy Files for the IBM JDK

In Step 2 for installing the User Application WAR file, you applied the unrestricted policy files to the supported IBM JDK on the server where you installed the User Application. You must also apply these unrestricted policy files for each WebSphere IBM JDK server that is running RBPM.

Review each WebSphere server IBM JDK to ensure that you have applied the unrestricted policy files. Without these unrestricted policy files, the error Illegal key size will occur during startup of RBPM.

28.3.8 Passing the preferIPv4Stack Property to JVM

The User Application uses JGroups for the caching implementation. In some configurations, JGroups requires that the preferIPv4Stack property be set to true to ensure that the mcast_addr binding is successful.

Without this option, the following error might occur:

[10/1/09 16:11:22:147 EDT] 0000000d UDP           W org.jgroups.util.Util
createMulticastSocket could not bind to /228.8.8.8 (IPv4 address); make sure
your mcast_addr is of the same type as the IP stack (IPv4 or IPv6).

You might also see this error:

[3/21/12 10:04:32:470 EDT] 00000024 UDP      E org.jgroups.protocols.TP down
failed sending message to null (131 bytes)
        java.lang.Exception: dest=/228.8.8.8:45654 (134 bytes)
    at org.jgroups.protocols.UDP._send(UDP.java:353)

The parameter java.net.preferIPv4Stack=true is a system property that can be set in the same manner as other system properties such as extend.local.config.dir. For instructions on setting system properties, see Section 28.3.4, Adding User Application Configuration Files and JVM System Properties.

28.3.9 Starting the User Application on the WebSphere Server

Your User Application should be installed and ready for deployment. For more information about post-installation tasks, see Section 30.0, Completing the Roles Based Provisioning Module / User Application Installation.

  1. Log on to the WebSphere application server that hosts the User Application.

  2. Using the standard WebSphere deployment procedure, deploy the User Application WAR file.

  3. Log on to the WebSphere administrator’s console as an admin user.

  4. In the left navigation pane, expand Applications > Enterprise Applications.

  5. Select the check box beside the User Application context that you want to start, and then click Start.

  6. Log out of the console.

  7. To access the User Application portal, enter the following URL in a supported Web browser:

    http://application-server-host:port/application-context

    For example:

    http://localhost:9080/IDMProv