Deploying CONNECT to WebSphere Enterprise 8.5.5.3

Version History

WebSphere Enterprise Setup

Prerequisites

• An operational WebSphere Enterprise 8.5 Installation. You can see the CONNECT team's reference /wiki/spaces/CONNECT4/pages/10584186.
• A CONNECT EAR built for WebSphere Enterprise and CONNECT Properties set, or the means to build those artifacts. You can download the connect EAR binary from here, or you can follow the steps from here to build from source.  

Configuring for CONNECT

Java 

CONNECT 5.2.x requires IBM JDK version 1.8 or higher to run the application. The server JDK can be configured from Administrator Console > Server Configuration > Java SDKs, or using the managesdk command line tool.

JCE

If Direct will be deployed with CONNECT, the Java Cryptography Extension must be installed. Please see the IBM Documentation.

Config Directory

Create a folder to put configuration files in. For example:

mkdir /home/connect/nhinc

Make sure the folder you just created is reflected in -Dnhinc.properties.dir in the system properties.

Copy/transfer configuration files to the config folder. In the binary distribution, these files can be found in the Properties directory of the zip. If using the source code:

cp -pr Product/Production/Common/Properties/src/main/resources/* /home/connect/nhinc

If Admin GUI will be deployed, set the "directconfigwsclient" bean in AdminGUIProxyConfig.xml to "directconfigcontainerwsclient" (for release 4.7 and below):

<alias alias="directconfigwsclient" name="directconfigcontainerwsclient" />

Create the keystores in the /home/connect/nhinc directory or ${WAS_PROPS_DIR} as following:

Deploying CONNECT from Binaries#certkeystore

Java Properties

From WebSphere 8.5 Administrator Console > server1 > Process Definition > Java Virtual Machine:

Set the following under "Generic JVM Arguments":

-Xmx8000m -XX:PermSize=1024m -XX:+PrintGCTimeStamps -XX:NewRatio=3 -Dnhinc.properties.dir=/home/connect/nhinc -Djavax.net.ssl.keyStorePassword=changeit -Djavax.net.ssl.trustStorePassword=changeit -Djavax.net.ssl.keyStore=/home/connect/nhinc/gateway.jks -Djavax.net.ssl.keyStoreType=JKS -Djavax.net.ssl.trustStoreType=JKS -Djavax.net.ssl.trustStore=/home/connect/nhinc/cacerts.jks -DCLIENT_KEY_ALIAS=gateway -Dcom.ibm.websphere.webservices.DisableIBMJAXWSEngine=true

Additionally, set the Classpath to the value used previously for nhinc.properties.dir, e.g.:

/home/connect/nhinc

Data Sources

Set up the following data sources using the WebSphere Administration Console:

For example, when creating a data source for MySQL the following custom properties with the respective values should be set:

• databaseName
• port
• user
• password

Keystores and Truststores

CONNECT requires keystores and truststores for both SSL as well as SAML/Digital Signatures. Either add the keystore and truststore to the classpath or provide absolute paths in the signature and truststore properties files. See Exchange Certificate Configuration Details for more details.

From WebSphere 8.5 Administrator Console > server1 > Process Definition > Java Virtual Machine, prepend the folder containing the keystore and truststore to the classpath, using a colon as the separator.  For example:

/path/to/certs:<original classpath>

Update signature.properties and truststore.properties to contain absolute paths, as shown in the following two code blocks:

org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin
org.apache.ws.security.crypto.merlin.keystore.type=jks
org.apache.ws.security.crypto.merlin.keystore.password=changeit
org.apache.ws.security.crypto.merlin.keystore.alias=gateway
org.apache.ws.security.crypto.merlin.file=<absolute path to gateway.jks>
org.apache.ws.security.crypto.merlin.keystore.private.password=changeit

org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin
org.apache.ws.security.crypto.merlin.keystore.type=jks
org.apache.ws.security.crypto.merlin.keystore.password=changeit
org.apache.ws.security.crypto.merlin.truststore.file=<absolute path to cacerts.jks>

These keystores and truststores can be managed by the WebSphere Admin Console under Security > SSL certificate and key management > Key stores and certificates.

Configure SSL & Two-Way SSL

Using the WebSphere Administrator Console, configure the WebSphere server to require the client certificate during SSL handshakes.

1. Log in to the WebSphere Administrator Console from the browser.
2. Under Security, go to SSL certificate and key management > SSL configurations.
3. Click the default SSL configuration NodeDefaultSSLSettings and click Quality of protection (QoP) settings.
4. Change the Client Authentication to Required from the list and click Ok and Save. This will enable the two-way SSL authentication.

Deploy Connect

1. Log in to the WebSphere Administrator Console from the browser.
2. From Application > New Application > click Install New Enterprise Application.
3. Browse to select the file <binary-location>/CONNECT-<VERSION>/CONNECT/<VERSION>/CONNECT-WAS-<VERSION>.ear and continue through the last step. Click Finish and Save.
4. Now click the installed CONNECT application, then click Class loading and update detection, then from Class Loader order select Classes loaded with local class loader first (parent last), then click OK and Save.
5. Finally, select the installed CONNECT application and click Start to load the application.

Deploy Admin GUI

1. Create a shared library and add the  neethi & xmlschema libraries. Due to a CXF/XMLSchema class-loader issue in WebSphere, the following Shared Library needs to be created.
   1. Under CONNECT Config Directory, create a lib folder (for example D:\app\connect\nhinc\lib)
   2. Copy the libraries below to the lib folder. You can find these libraries from <binary-location>/CONNECT-<VERSION>/CONNECTAdminGUI/<VERSION>/CONNECTAdminGUI-<VERSION>.war\WEB-INF\lib.
      1. commons-beanutils-1.8.3.jar
      2. commons-codec-1.7.jar
      3. commons-collections-3.2.2.jar
      4. commons-configuration-1.9.jar
      5. commons-digester-1.8.jar
      6. commons-fileupload-1.3.2.jar
         1. For Release 4.7 and below, uses commons-fileupload-1.3.1.jar
      7. commons-io-2.1.jar
      8. commons-lang-2.6.jar
      9. commons-validator-1.4.0.jar
      10. el-api-2.2.jar
      11. el-impl-2.2.jar
      12. hibernate-jpa-2.1-api-1.0.0.Final.jar
      13. myfaces-bundle-2.1.15.jar
      14. neethi-3.0.3.jar
          1. For Release 4.7 and below, uses neethi-3.0.2.jar
      15. xmlschema-core-2.0.3.jar
      16. httpclient-4.5.2.jar (for release 5.1 and above)
      17. httpcore-4.4.5.jar (for release 5.1 and above)
2. Log in to the WebSphere Administrator Console from the browser.
3. From Environment > Shared libraries, create a new shared library ADMINGUI_COMP_LIB and enter the shared library lib folder location (created in Step 1) in the Classpath field.  Under Class Loading, check the box for Use an isolated class loader for this shared library.  Click OK and Save.
4. From Application > New Application > click Install New Enterprise Application.
5. Browse to select the file<binary-location>/CONNECT-<VERSION>/CONNECTAdminGUI/<VERSION>/CONNECTAdminGUI-<VERSION>.war and continue through the last step. Click Finish and Save.
6. Now click the installed CONNECTAdminGUI application, then click Class loading and update detection, then from Class Loader order make sure Classes loaded with parent class loader first, then click OK and Save.
7. Now click the installed CONNECTAdminGUI application, then click Shared library references, then from the table select the application and click  Reference Shared Libraries and select  ADMINGUI_COMP_LIB from the Pick List and then click OK and Save.
8. Under Web Module Properties, click on JSP and JSF options.  Select SunRI1.2 for the JSF Implementation.
9. Finally, select the installed CONNECTAdminGUI application and click Start to load the application.

Alternately, an adopter can also do the above steps using the WebSphere command line tool wsadmin. Please refer to the WebSphere 8.5 Admin Guide for more information.