Java Agents 2025.3

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 the Bouncy Castle FIPS provider

This section provides an example of how to use the Bouncy Castle FIPS 140-3 compliant security provider. Learn more in Bouncy Castle for Java FIPS. The example uses the Tomcat Java Agent but you can adapt it for other agent types.

Perform these steps before installing the agent and starting the container.

You can choose whether to update the default $JAVA_HOME/conf/security/java.security file for your Java version or update a custom version instead.

The following steps assume you are updating a custom java.security file located in the /opt/fips directory.

  1. Download the latest version of the Bouncy Castle FIPS 2.0 .jar file from Bouncy Castle for Java FIPS.

    This example uses the bc-fips-2.0.0.jar file.

  2. Copy the .jar file to your container’s lib directory and to a central location for installation:

    1. Using the .amAgentLocator file, find the directory where 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 the bc-fips-2.0.0.jar file to the lib subdirectory:

      • Unix

      • Windows

      $ cd /path/to/downloaded_jar_file
$ cp bc-fips-2.0.0.jar /path/to/java_agents/tomcat_agent/lib
      C:> cd C:\path\to\downloaded_jar_file
C:\path\to\downloaded_jar_file> copy bc-fips-2.0.0.jar C:\path\to\java_agents\tomcat_agent\lib

    3. Copy the bc-fips-2.0.0.jar file to a central location, such as /opt/fips:

      • Unix

      • Windows

      $ cd /path/to/downloaded_jar_file
$ cp bc-fips-2.0.0.jar /opt/fips
      C:> cd C:\path\to\downloaded_jar_file
C:\path\to\downloaded_jar_file> copy bc-fips-2.0.0.jar C:\opt\fips

  3. Configure the security provider in the /opt/fips/java.security file to use Bouncy Castle.

    1. Edit the java.security file and replace all the security.provider lines with the following:

      security.provider.1=org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider
security.provider.2=org.bouncycastle.jsse.provider.BouncyCastleJsseProvider fips:BCFIPS
security.provider.3=sun.security.provider.Sun

      You should only have these three providers listed to make sure only FIPS-compliant algorithms are used. Including other providers in the list risks the use of a non-compliant algorithm.

      Learn more in the Bouncy Castle FIPS Java API User Guide.

    2. Save and close the file.

  4. Install the agent as described in Install Tomcat Java Agent.

    Make sure you include the FIPS install options when running the agentadmin command.

    For example:

    $ agentadmin --fips-only --fips-jar-dir=/opt/fips --security-properties=/opt/fips/java.security --key-digest=SHA512 --install

  5. Configure the Tomcat container to use the Bouncy Castle 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 is installed in /path/to/tomcat/, the file can be /path/to/tomcat/bin/setenv.sh.

    2. Add the following lines to the setenv.sh file:

      export JAVA_OPTS="$JAVA_OPTS -Dorg.forgerock.openam.encryption.key.digest=SHA512"
export JAVA_OPTS="$JAVA_OPTS -Djava.security.properties==/opt/fips/java.security"
export JAVA_OPTS="$JAVA_OPTS -Dsecurity.overridePropertiesFile=true"
export JAVA_OPTS="$JAVA_OPTS -Dorg.bouncycastle.fips.approved_only=true"
      The == shown for the -Djava.security.properties property is necessary.

    3. Add the FIPS bc-fips-2.0.0.jar file to the classpath:

      export CLASSPATH="/opt/fips/bc-fips-2.0.0.jar"

      This step isn’t necessary if your container automatically adds every jar in the lib directory to its classpath on startup.

  6. Restart the Tomcat container where the agent is installed.

Verify the Bouncy Castle FIPS configuration

If you want to confirm that the Bouncy Castle FIPS security provider is being used, you have two options:

Start the container with the Java Agent in TRACE mode

When Java Agent is set to TRACE mode on startup, it outputs a list of providers. If the Bouncy Castle FIPS security provider is being used, you’ll see the following information written to the debug logs:

TRACE Provider 1: org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider
TRACE Provider 2: org.bouncycastle.jsse.provider.BouncyCastleJsseProvider
TRACE Provider 3: sun.security.provider.Sun
Enable the container to output security provider information

Add the following lines to the setenv.sh file and restart the container:

export JAVA_OPTS="$JAVA_OPTS -XshowSettings:security:providers"
export JAVA_OPTS="$JAVA_OPTS -Djava.security.debug=properties,provider"

The security provider information is written to the standard output for the container.

Remove these lines from the setenv.sh file once you have verified the configuration.