Deploying CONNECT to WebLogic 12.2

Version History

Preface

The CONNECT Product team's approach is to provide instructions that focus on the setting or configuration that is required and less on exactly how to set that configuration. For example, the CONNECT Product team's instructions are more likely to say, "set a given environment variable to a given value" as opposed to "execute this command on windows," and again, "execute this command on *nix." Another example, specific to WebLogic, is that the CONNECT Product team's instructions will not reference exactly how to start a managed server because there are too many ways to start a managed server that may differ from site to site, such as command line, node manager, python or shell scripts, etc.

Prerequisites

• Java 1.8 or higher version
• Database (MySQL is CONNECT default).
• WebLogic Server

WebLogic Setup

The CONNECT Product Team testing included the use of one Admin Server and one Managed Server with the CONNECT application and datasources deployed directly to the managed server. Our approach was to maximize the configurations and settings that can be done in the CONNECT application and minimize modifications that must be made to the WebLogic instance. To this end, the only modifications made to the WebLogic install were changing to Oracle JDK 1.8, adding the keystore/truststore java options, adding the keystore/truststore to the classpath, and deploying the datasources. The CONNECT Product Team is very interested in working with community members to reduce the modifications to the WebLogic instance in order to support CONNECT.

Change WebLogic to Use JDK 

WebLogic start-up scripts will pick up java from the JAVA_HOME environment variable. Adopters should set their JAVA_HOME environment variable to point to Oracle JDK version 1.x.0_yy (where x is the version number and yy is the update).

Create Key Store

How Do I Set Up the Certs? 

Deploying CONNECT from Binaries#certkeystore

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

(1) Add the folder containing the keystore and truststore to the classpath. Be sure to add the path to the beginning of the existing path so that the existing path is preserved. For example:

CLASSPATH=<path to certs>:$CLASSPATH

(2) Alternatively, 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>

Create Config Directory

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

mkdir /home/connect/nhinc

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

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

Set Up Environment Variables

What Java Options Do I Need to Deploy CONNECT?

JAVA_OPTIONS=-Xmx8g -Dnhinc.properties.dir=/home/connect/nhinc -Djavax.net.ssl.keyStorePassword=changeit -Djavax.net.ssl.trustStorePassword=changeit -Djavax.net.ssl.keyStore=<path to keystore>/gateway.jks -Djavax.net.ssl.keyStoreType=JKS -Djavax.net.ssl.trustStoreType=JKS -Djavax.net.ssl.trustStore=<path to truststore>/cacerts.jks -DCLIENT_KEY_ALIAS=gateway -Djava.security.egd=file:/dev/./urandom -DUseSunHttpHandler=true

Note: The JVM option "-Dweblogic.management.clearTextCredentialAccessEnabled=true" should be added only for WebLogic 12.1.3 Install.

Set Up Datasources

Set up the following datasources using the WebLogic Administration Console. "Name" can be any value an implementer chooses. The CONNECT Product team recommends using meaningful names.

1. Browse to the WebLogic Administration Console (typically http://<localhost or IP Address>:7001/console) and log in
2. In the left Domain Structure panel, go to Services -> Datasources
3. Click New -> Generic Data Source
4. Enter Name, jndi name, and database type. Default CONNECT database is MySQL. Click Next
5. Select the appropriate driver for the environment and click Next
6. Configure transaction setting -- for CONNECT Product team testing Support Global Transactions was unchecked. Click Next
7. Enter User Name, Password, Server Name, Database Name, and Port Number. Click Next. Username and password for default CONNECT database is nhincuser/nhincpass
8. Test the configuration using the "Test Connection" button. If successful, click Next or review changes and fix
9. Select Targets -- Check the box next to the managed server created for CONNECT
10. Click Finish

Configure Keystore & Truststore

1. Under "Environment," go to "Servers," then go to the adopter's managed server
2. Navigate to "Keystores"
   1. Keystores: "Custom Identity and Custom Trust"
3. Under "Keystores" --> "Identity"
   1. "Custom Identity Keystore:" = <path to certs>/gateway.jks
   2. "Custom Identity Keystore Type:" = JKS (or leave blank)
   3. Enter the passphrase and confirm
4. Under "Keystores" --> "Trust"
   1. "Custom Trust Keystore:" = <path to certs>/cacerts.jks
   2. "Custom Trust Keystore Type:" = JKS (or leave blank)
   3. Enter the passphrase and confirm

Configure SSL & Two-Way SSL

Using the WebLogic Console, configure the WebLogic instance to require the client certificate during SSL handshakes.

1. Login to the WebLogic Console, typically at http://localhost:7001/console
2. Under "Environment," go to "Servers," then go to the adopter's managed server
3. Navigate to the "SSL" tab
   1. Identity and Trust Locations: "Keystores"
   2. Private Key Alias: "gateway"
   3. Enter passphrase and confirm
   4. Certificate Location: "from Custom Identity Keystore"
   5. Trusted Certificate Authorities: "from Custom Trust Keystore"
4. Navigate to the "SSL" tab and then the Advanced section
5. Ensure the drop down for "Two Way Client Cert Behavior" is set to "Client Certs Requested and Enforced"
6. Check JSSE-SSL flag (for weblogic 12.1.x)

Deploy CONNECT

1. Browse to the WebLogic Administration Console (typically http://<localhost or IP Address>:7001/console) and log in
2. In the left Domain Structure panel, go to Deployments. Click Install
3. Browse to the <binary-location>/CONNECT-<VERSION>/CONNECT/<VERSION>/CONNECT-WL-<VERSION>.ear file. Click Next
4. Ensure "Install this deployment as an application" is checked. Click Next
5. Check the Check Box next to the target managed server. Click Next
6. Click Finish
7. Optional: For deploying CONNECT Admin GUI, repeat the steps 2-6 using  <binary-location>/CONNECT-<VERSION>/CONNECTAdminGUI/<VERSION>/CONNECTAdminGUI-<VERSION>.war.