Configure the Java agent for WebSphere

First, download the Java agent JAR from one of these repositories:

Use the guidelines below to configure the Java agent, depending on how you run Contrast with WebSphere.

Note

IBM J9 doesn't allow the Java Instrumentation API to alter core Java classes when using the Shared Classes feature. You must disable this feature by specifying -Xshareclasses:none in your JVM parameters, as shown above.

Similarly, if -Dcom.ibm.oti.shared.enabled=true is set, you may also run into problems in older J9 JREs.

Websphere trust and key store

WebSphere maintains its own trust and key store, separate from the trust store included as part of the Java JRE. The agent starts before WebSphere is initialized and hence the WebSphere specific trust store is not configured. Therefore, the agent uses the default trust store located in the Java JRE/lib/security/cacerts file unless extra config is provided to the JVM.

However, in some scenarios, for instance requiring a proxy server that uses internal only or self-signed certificates, specific extra steps are necessary. The options available are:

  • Install the required certs into both the JRE cacerts trust store and also the WebSphere specific trust store. This means the certificate chain can be validated by both the agent and also your web application.

  • Provide Java with the standard trust store system properties to change the trust store to be the same as the WebSphere trust store. An example is listed below. This has the advantage of only requiring the certificate to be installed in one location, i.e. the WebSphere trust store.

Example configuration for the agent to use the WebSphere specific trust store (i.e. option 2 above):

-Djavax.net.ssl.trustStore=opt/IBM/WebSphere/AppServer/profiles/AppSrv01/config/cells/DefaultCell01/nodes/DefaultNode01/trust.p12
-Djavax.net.ssl.trustStoreType=PKCS12
-Djavax.net.ssl.trustStorePassword=secret

WebSphere itself supports methods of encoding the password but these are not available when setting the trust store password for the agent, as it is executing before WebSphere starts.

Add Contrast with Websphere

If you launch WebSphere yourself, add Contrast's JVM parameter to the server.xml file in your cell directory. Replace <CellName> and <NodeName> with the name of the cell and node. Replace <YourContrastJarPath> with the path to your Contrast JAR file. For example:

<WebsphereDirectory>\AppServer\profiles\AppSrv01\config\cells\<CellName>\nodes\<NodeName>\servers\server1\server.xml

<jvmEntries genericJvmArguments="-javaagent:<YourContrastJarPath> -Xshareclasses:none">
   ...
</jvmEntries>

Add Contrast with the WebSphere Administration Console

You can also add Contrast through the WebSphere administration console by following instructions from the Websphere support site.

Use Java 2 with WebSphere

  1. Create a contrast.policy file that contains this code (or append it to the server.policy file). Replace <YourContrastJarPath> with the path to your Contrast JAR file. For example:

    grant codeBase "file:<YourContrastJarPath>" {
  permission java.security.AllPermission;
};

  2. Append the contrast.policy file to the $WEBSPHERE_HOME/AppServer/profiles/AppSrv01/properties/server.policy.

  3. Enable the security manager with the wsadmin tool:

    • Jacl: $AdminTask setAdminActiveSecuritySettings {-enforceJava2Security true}

    • Jython: $AdminTask.setAdminActiveSecuritySettings('-enforceJava2Security true')

    Tip

    Learn more about Java security manager and enabling and disabling Java 2 security manager using scripting.

In this section: