Skip to main content

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.


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 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 so 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 configuration is provided to the JVM.

However, in some scenarios, (like requiring a proxy server that uses internal only or self-signed certificates) specific extra steps are necessary. You can either:

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

  2. Provide Java with the standard trust store system properties to change the trust store to be the same as the WebSphere trust store. This has the advantage of only requiring the certificate to be installed in one location: the WebSphere trust store. For example:

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:


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

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>" {
  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')