--- title: Secure connections description: After installation, consider securing communication between the agent and AM. component: java-agents version: 2025.11 page_id: java-agents:installation-guide:secure-connections canonical_url: https://docs.pingidentity.com/java-agents/2025.11/installation-guide/secure-connections.html section_ids: configure-HTTPS: Secure communication between the agent and AM fips: Integrate with the Bouncy Castle FIPS provider verify_the_bouncy_castle_fips_configuration: Verify the Bouncy Castle FIPS configuration --- # 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](../properties-reference/org.forgerock.agents.secure.cookies.enabled.html). 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: ```bash $ 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: ```xml 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: ```bash $ 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](https://www.bouncycastle.org/fips-java). 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](https://www.bouncycastle.org/download/bouncy-castle-java-fips/#latest). 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 ```bash $ cd /path/to/tomcat $ cat .amAgentLocator; echo /path/to/java_agents/tomcat_agent ``` ```bash 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: ```text 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](https://downloads.bouncycastle.org/fips-java/docs/BC-FJA-UserGuide-2.0.0.pdf). 2. Save and close the file. 4. Install the agent as described in [Install Tomcat Java Agent](install.html#install-tomcat-agent). Make sure you include the FIPS install options when running the [agentadmin](agentadmin.html) command. For example: ```bash $ 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: ```bash 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: ```bash 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: ```text 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: ```bash 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.