32.6 Post-Installation Steps for WebSphere

This section provides information about updating your WebSphere environment after you install the identity applications.

32.6.1 Configuring a WebSphere Cluster after Installing the Identity Applications

This section outlines the process for configuring a WebSphere cluster for use with the identity applications. This section assumes that you are an experienced user of the WebSphere Application Server (WAS). For more information on Configuring see,Section 27.3, Configuring OSP and SSPR for Clustering.

32.6.2 Adding User Application Configuration Files and JVM System Properties

This section helps you create new JVM system properties that the identity applications require to function on a WebSphere application server.

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

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

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

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

  5. Expand the link and select Process Definition.

  6. In the list under Additional Properties, click Java Virtual Machine.

  7. Under the Additional Properties heading for the JVM page, click Custom Properties.

  8. To add the extend.local.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 full path of the directory that contains the hibernate.cfg.xml file. For example, /opt/netiq/idm/apps/UserApplication/.

    4. For Description, specify a description for the property.

      For example, path to the identity applications configuration files.

    5. Click OK to save the property.

  9. 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 full path of the directory that contains the idmuserapp_logging.xml file.

      For example, /opt/netiq/idm/apps/UserApplication/.

    4. For Description, specify a description for the property.

      For example, path to the identity applications logging configuration files.

    5. Click OK to save the property.

  10. To add the com.netiq.ism.config JVM system property, complete the following steps:

    1. Click New.

    2. For Name, specify com.netiq.ism.config.

    3. For Value, specify the full path including the filename for the ism-configuation.properties file.

      For example, /opt/netiq/idm/apps/UserApplication/ism-configuation.properties.

    4. For Description, specify a description for the property.

      For example, the identity applications ism properties file.

    5. Click OK to save the property.

  11. (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.

32.6.3 Creating and Applying a Shared Library

You might need to configure a shared library for the identity applications. When you create a shared library you must also apply the library to a new class loader to ensure that WebSphere uses the Identity Manager versions of the 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 in 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. For Classpath, add the following required JAR files:

    • log4j.jar

    • commons-logging-1.1.1.jar

    • IDMselector.jar

    These files are located by default in the installation directory for the identity applications. For example, /opt/netiq/idm/apps/UserApplication.

  7. De-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 in 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.

32.6.4 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.

    Identity Manager imports the certificates in the following locations of the IBM JRE for WebSphere:

    • cacerts file

    • /lib/security directory, such as /opt/IBM/WebSphere/AppServer/java_1.7_64/jre/lib/security

  2. Log in 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, click Key stores and certificates under Related Items.

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

  6. Under Additional Properties, click 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.

32.6.5 Applying the Unrestricted Policy Files for the IBM JDK

To run effectively, the identity applications require that you run unrestricted policy files to the supported IBM JDK on the server where you installed the applications. 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.

32.6.6 Passing the preferIPv4Stack Property to JVM

For more information see, Section 32.5.2, Passing the preferIPv4Stack Property to JVM

32.6.7 Setting up JMS in WebSphere

The identity applications rely on a Java Message Service (JMS) persistent store to persist email messages. If JMS is not properly configured, any email messages in the memory queue will be lost if the application server is shut down.

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

  2. To create a new bus, complete the following steps:

    1. Click Service integration > Buses.

    2. Click New.

    3. Specify a name for the bus. For example, IDMProvBus.

    4. De-select Bus Security.

    5. Click Next, and then confirm the changes.

    6. Click Finish, and then click Save.

  3. To configure the bus, complete the following steps:

    1. In Service integration > Buses, select the bus that you created in Step 2.

    2. Click Configuration > General Properties.

    3. Specify a description for the bus. For example, Bus to be used with the IDM Applications.

    4. Click Apply, and then click Save.

    5. On the Configuration tab, click Topology > Bus Members.

    6. Click Add.

    7. Specify whether the IDMProv.war file is deployed on a server, cluster, or WebSphere MQ server, and then click Next.

    8. For File Store, specify the type of message store, and then click Next.

    9. Review the default values for the file store, and then click Next.

    10. (Optional) Tune the performance parameters for the bus.

    11. Click Next, and then click Finish.

  4. To create a topic connection for the bus, complete the following steps:

    1. Navigate to Resources > JMS > Topic connection factories.

    2. In the Scopes menu, select the correct scope. For example, Node=MyNode01, Server=server1.

    3. Click New.

    4. Select Default messaging provider, and then click OK.

    5. ClickConfiguration.

    6. Specify a name for the topic connection. For example, ConnectionFactory.

    7. For JNDI name, specify the same value as the name. For example, ConnectionFactory.

    8. Specify a brief description for the topic connection. For example, Topic Connection Factory to be used with the IDM Applications.

    9. For Bus Name, select the bus that you created in Step 2.

    10. Click Durable Subscription > Client, and then specify IDMNotificationDurableTopic.

    11. Click Quality of Service > Persistent message reliability, and then select Reliability persistent.

    12. Click Share durable subscriptions > Advanced Messaging, and then select Never shares.

    13. Click Apply, and then click Finish.

  5. To create a topic, complete the following steps:

    1. Navigate to Resources > JMS > Topics.

    2. Select the scope that you want to use. For example, Node=MyNode01, Server=server1.

    3. Click New.

    4. Select Default messaging provider, and then click OK.

    5. ClickConfiguration.

    6. Specify a name for the topic. For example, IDMNotificationDurableTopic.

    7. For JNDI name, use the following syntax: topic/name. For example, topic/IDMNotificationDurableTopic.

    8. Specify a brief description for the topic connection. For example, Topic to be used with the IDM Applications.

    9. For Bus Name, select the bus that you created in Step 2.

    10. Click Topic space, and then select Default. Topic.Space.

    11. Click JMS delivery mode, and then select Persistent.

    12. Click Apply, and then click Save.

  6. Log out of the WebSphere console.

  7. Restart WebSphere on the server where you deployed the WAR for the identity applications.

  8. To verify whether the JMS server is set up correctly, check the SystemOut.log file.

    Incorrect setup

    If the JMS server is not set up correctly, the SystemOut.log file includes the following lines in sequence:

    INFO  [JMSConnectionMediator] Starting JMS notification system
WARN  [NotificationEngine] Could not properly initialize JMS persistence for the notification system. Will revert back to non-persistent asynchronous notification system. 
INFO  [NotificationThread] Starting asynchronous notification system
    Correct setup

    In a successful configuration, the SystemOut.log file includes the following type of information in sequence:

    INFO  [JMSConnectionMediator] Starting JMS notification system
%connection information%
INFO  [NotificationThread] Starting asynchronous notification system

    ========

[9/7/14 14:39:52:167 EDT] 00000000 SibMessage    I   [:] CWSID0021I: Configuration reload is enabled for bus IDMProvBus. 
[9/7/14 14:39:52:372 EDT] 00000000 SibMessage    I   [:] CWSIS1569I: Messaging engine N35020Node02.server1-IDMProvBus is using a file store. 

========

[9/7/14 14:41:32:613 EDT] 0000000c SystemOut     O 14:41:32,608 INFO  [JMSConnectionMediator] Starting JMS notification system 

[9/7/14 14:41:32:841 EDT] 0000000c SharedPool    I   J2CA0086W: Shareable connection MCWrapper id 5c175c17  Managed connection [com.ibm.ws.sib.api.jmsra.impl.JmsJcaManagedConnection@490f490f <managedConnectionFactory=[com.ibm.ws.sib.api.jmsra.impl.JmsJcaManagedTopicConnectionFactoryImpl@1f9c1f9c <logWriter=null> <busName=IDMProvBus> <clientID=IDMNotificationDurableTopic> <userName=null> <password=null> <xaRecoveryAlias=> <nonPersistentMapping=ExpressNonPersistent> <persistentMapping=ReliablePersistent> <durableSubscriptionHome=N35020Node02.server1-IDMProvBus> <readAhead=Default> <temporaryQueueNamePrefix=null> <temporaryTopicNamePrefix=null> <target=null> <targetSignificance=Preferred> <targetTransportChain=null> <targetType=BusMember> <providerEndpoints=null> <connectionProximity=Bus> <shareDataSourceWithCMP=false> <shareDurableSubscriptions=NeverShared> <cachedFactory=com.ibm.ws.sib.api.jms.impl.JmsFactoryFactoryImpl@4fb24fb2> <producerDoesNotModifyPayloadAfterSet=false> <consumerDoesNotModifyPayloadAfterGet=false>]> <coreConnection=com.ibm.ws.sib.processor.impl.ConnectionImpl@b0b0b0b> <localTransaction=[com.ibm.ws.sib.api.jmsra.impl.JmsJcaManagedConnection$JmsJcaLocalTransaction@78ce78ce <localSITransaction=null>]> <xaResource=null> <metaData=null> <userDetails=[com.ibm.ws.sib.api.jmsra.impl.JmsJcaUserDetails@5b4d5b4d <userName=null> <password=null>]> <subject=null> <logWriter=null> <sessions=[[com.ibm.ws.sib.api.jmsra.impl.JmsJcaSessionImpl@21ff21ff <managedConnection=1225738511> <connection=828453217> <transacted=false> <applicationLocalTransaction=null> <reqInfo=[com.ibm.ws.sib.api.jmsra.impl.JmsJcaConnectionRequestInfo@219a219a> <userDetails=null> <coreConnection=com.ibm.ws.sib.processor.impl.ConnectionImpl@b0b0b0b> <request counter=0>]> <sessionClosed=false> <sessionInvalidated=false>]]> <connectionListeners=[com.ibm.ejs.j2c.ConnectionEventListener@1572625852]>]  State:STATE_TRAN_WRAPPER_INUSE 
 from resource ConnectionFactory was used within a local transaction containment boundary. 

[9/7/14 14:41:32:938 EDT] 0000001a SystemOut     O 14:41:32,938 INFO  [NotificationThread] Starting asynchronous notification system