Java Agents 2024.6

Secure connections

Secure communication between the agent and AM

After installation, consider securing communication between the agent and AM.

  1. Configure AM to send cookies only when the communication channel is secure:

    1. In the AM admin UI, select Realms > realm name > Applications > Agents > Java > agent name > SSO.

    2. Enable Transmit Cookies Securely.

  2. Import a CA certificate in the JDK truststore, usually at $JAVA_HOME/jre/lib/security/cacerts. The certificate should be the one configured for HTTPS connections in the AM container, or signed with the same CA root certificate. For example:

    $ keytool \
-import \
-trustcacerts \
-alias agentcert \
-file /path/to/cacert.pem \
-keystore $JAVA_HOME/jre/lib/security/cacerts

    Make sure that all containers where AM is installed trust the certificate stored in the JDK truststore, and that the JDK trusts the certificates stored on the containers where AM is installed.

  3. Add the following properties to the AgentBootstrap.properties file:

    • javax.net.ssl.trustStore, to specify the full path to the JDK truststore.

    • javax.net.ssl.trustStorePassword, to specify the password of the truststore.

      For example:

      javax.net.ssl.trustStore=/Library/Java/JavaVirtualMachines/jdk1.8.0_101.jdk/Contents/Home/jre/lib/security/cacerts
javax.net.ssl.trustStorePassword=changeit

      For backward-compatibility, you can also provide the truststore and the password to the agent by specifying them as Java properties in the container’s start-up sequence. For example, add them to Tomcat’s $CATALINA_OPS variable instead of specifying them in the AgentBootstrap.properties file:

      $ export CATALINA_OPTS="$CATALINA_OPTS \
-Djavax.net.ssl.trustStore=$JAVA_HOME/jre/lib/security/cacerts \
-Djavax.net.ssl.trustStorePassword=changeit"

  4. Restart the agent.

Integrate with Bouncy Castle FIPS provider

This section gives an example of how to use the Bouncy Castle FIPS provider. For more information, refer to JAVA FIPS RESOURCES. The example uses Tomcat Java Agent but you can adapt it for other agent types.

Perform this procedure before installing the agent and starting the container.

  1. Download the latest version of Bouncy Castle FIPS library from JAVA FIPS RESOURCES. This example uses bc-fips-1.0.2.3.jar.

  2. Copy the .jar file to the agent library:

    1. Using the .amAgentLocator file, find the directory in which the agent is installed. In this example, the agent is installed in /path/to/java_agents/tomcat_agent:

      • Unix

      • Windows

      $ cd /path/to/tomcat
$ cat .amAgentLocator; echo

/path/to/java_agents/tomcat_agent
      C:\opt\container> type .amAgentLocator

C:/path/to/java_agents/tomcat_agent

    2. Copy bc-fips-1.0.2.3.jar to the lib subdirectory:

      • Unix

      • Windows

      $ cd /path/to/java_agents/tomcat_agent/lib
$ cp /tmp/bc-fips-1.0.2.3.jar /path/to/java_agents/tomcat_agent/lib
      C:\opt\container> cd C:\path\to\java_agents\tomcat_agent\lib
C:\path\to\java_agents\tomcat_agent\lib> copy C:\temp{fips-jar} .

  3. Set up the security providers to use Bouncy Castle:

    1. Locate the java.security file for your Java instance. For example, in Java 17 and Ubuntu the file is /etc/java-17-openjdk/security/java.security.

    2. Edit the file to place the org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider line at the top of the list:

      security.provider.1=org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider
security.provider.2=SUN
security.provider.3=SunRsaSign
security.provider.4=SunEC
security.provider.5=SunJSSE
security.provider.6=SunJCE
security.provider.7=SunJGSS
security.provider.8=SunSASL
security.provider.9=XMLDSig
security.provider.10=SunPCSC
security.provider.11=JdkLDAP
security.provider.12=JdkSASL
security.provider.13=SunPKCS11

  4. In the agent configuration, set org.bouncycastle.fips.approved_only to true so that only algorithms approved by FIPS can be used:

    1. Locate the agentadmin file:

      • Unix

      • Windows

      $ cd /path/to/java_agents/tomcat_agent/bin 
      C:\> cd C:\path\to\java_agents\tomcat_agent\bin

    2. Change the following line:

      AGENT_OPTS="$AGENT_OPTS -Dagent.config.dir=$AGENT_HOME"

      to this line:

      AGENT_OPTS="$AGENT_OPTS -Dagent.config.dir=$AGENT_HOME -Dorg.bouncycastle.fips.approved_only=true"

  5. Configure the Tomcat container to use the BouncyCastle provider. There are many ways to configure the container; this example uses a setenv.sh file:

    1. Locate or create a setenv.sh file for your Tomcat container. When Tomcat installed in /path/to/tomcat/, the file can be /path/to/tomcat/bin/setenv.sh.

    2. Add the following line for the bc-fips-1.0.2.3.jar classpath:

      CLASSPATH=/path/to/bc-fips-1.0.2.3.jar

    3. Add the following line to run the FIPS module in approved mode:

      JAVA_OPTS="$JAVA_OPTS -Dorg.bouncycastle.fips.approved_only=true"

    4. (Optional) Add the following property to the JAVA_OPTS to enable logs:

      -Djava.security.debug=jca

  6. Install the agent and start the container, as described in Install Tomcat Java Agent.