Deploy Java Agent with Docker

The example in this section provides a Dockerfile and instructions to deploy Tomcat Java Agent on Linux to extend and protect an application. Adapt the information for other agent containers and platforms.

Consider the following limitations:

The Dockerfile doesn’t manage logs, so agent logs are lost when the Docker container is killed. Manage logs independently of the Dockerfile in the following ways, according to your environment:
- Store logs persistently to a volume
- Store logs to a host machine
- Tail logs into STDOUT or STDERR so that Docker can collect the data
The Dockerfile isn’t suitable for local configuration mode and doesn’t update bootstrap properties. The agent must be configured to operate in the default remote configuration mode. For more information, refer to Location of Agent Configuration Repository.

In Identity Cloud or AM, set up an agent profile and policy. For more information, refer to Identity Cloud’s Prepare for installation or AM’s Prepare for installation.

This example uses the following configuration:
- AM URL: https://am.example.com:8443/am
- AM realm: top-level
- Agent URL: http://agent.example.com:8080/app
- Agent profile name: java-agent
- Agent profile password: password
- Policy set and policy: Allow HTTP GET and POST for all authenticated users.
Create a local folder for your application’s web.xml file, the agent .zip file, the Dockerfile, and the agent profile password—they must be in the same folder. This example uses /path/to/docker.
Build a Docker image of your web application. This example uses a sample application called fr-sample-app:1.0.

Configure the agent filter in your application’s web.xml file and save it to /path/to/docker/web.xml. For more information, refer to Configure the agent filter for a web application.

This example uses the following web.xml file:

<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
 <filter>
  <filter-name>Agent</filter-name>
  <display-name>AM Agent</display-name>
  <description>AM Agent Filter</description>
  <filter-class>com.sun.identity.agents.filter.AmAgentFilter</filter-class>
 </filter>
 <filter-mapping>
  <filter-name>Agent</filter-name>
  <url-pattern>/*</url-pattern>
  <dispatcher>REQUEST</dispatcher>
  <dispatcher>INCLUDE</dispatcher>
  <dispatcher>FORWARD</dispatcher>
  <dispatcher>ERROR</dispatcher>
 </filter-mapping>
 <servlet>
  <servlet-name>ServletInfo</servlet-name>
  <servlet-class>org.forgerock.ServletInfo</servlet-class>
 </servlet>
</web-app>

Download the agent .zip file to /path/to/docker/. The .zip in this example is tomcat_agent_2024.3.zip.

Create a file containing the agent profile password. The filename in this example is agent_secret and the password is password.

/path/to/docker$ cat > agent_secret
password
CTRL+D

Although the agent accepts any password length and content, you are strongly encouraged to generate secure passwords. This can be achieved in various ways, for example using a password manager or by using the command line tool agentadmin --key.

Create the following Dockerfile in /path/to/docker/Dockerfile. Arguments are provided by the build command.

# Application Docker image
ARG BASE_DOCKER_IMAGE
FROM ${BASE_DOCKER_IMAGE}

# Install and unzip the application, required for unpacking the agent build.
# Not required if the base image is already unzipped.
# For non-Debian Linux distributions, use the appropriate package manager.
RUN apt-get update && \
	apt-get install unzip --no-install-recommends -y && \
	apt-get clean

# Define the build arguments.
# Arguments without default values must be specified in the build command.
ARG AGENT_VERSION
ARG AGENT_ZIP_FILE=tomcat_agent_2024.3.zip
ARG APP_NAME
ARG AGENT_HOME=/opt
ARG AM_URL
ARG SERVER_HOME=/usr/local/tomcat
ARG AGENT_URL=http://agent.dummy.url:8080/app
ARG AGENT_REALM=/
ARG AGENT_PROFILE

# Copy the agent .zip file to the Docker directory where the agent is installed.
COPY ${AGENT_ZIP_FILE} ${AGENT_HOME}/${AGENT_ZIP_FILE}

# Unzip the agent and delete the .zip file
RUN cd ${AGENT_HOME} && \
	unzip ./${AGENT_ZIP_FILE} && \
	rm -rf ./${AGENT_ZIP_FILE}

# Create an agent installation file called install_file
RUN echo "CONFIG_DIR= ${SERVER_HOME}/conf" > ${AGENT_HOME}/install_file && \
	echo "AM_SERVER_URL= ${AM_URL}" >> ${AGENT_HOME}/install_file && \
	echo "CATALINA_HOME= ${SERVER_HOME}" >> ${AGENT_HOME}/install_file && \
	echo "INSTALL_GLOBAL_WEB_XML= false" >> ${AGENT_HOME}/install_file && \
	echo "AGENT_URL= ${AGENT_URL}" >> ${AGENT_HOME}/install_file && \
	echo "AGENT_PROFILE_NAME= ${AGENT_PROFILE}" >> ${AGENT_HOME}/install_file && \
	echo "AGENT_PROFILE_REALM= ${AGENT_REALM}" >> ${AGENT_HOME}/install_file && \
	echo "AGENT_PASSWORD_FILE= /run/secrets/agent_secret" >> ${AGENT_HOME}/install_file

# Install the agent and mount the file containing the agent password
# This command uses silent installation with a provided install_file
RUN --mount=type=secret,id=agent_secret,required=true \
	"${AGENT_HOME}"/java_agents/tomcat_agent/bin/agentadmin \
	--forceInstall \
	--useResponse ${AGENT_HOME}/install_file && \
	rm -rf ${AGENT_HOME}/install_file

# Copy the new web.xml file, which includes agent filter
COPY web.xml ${AGENT_HOME}/

# Replace the original web.xml with the new web.xml file, which includes agent filter
RUN mkdir /tmp/app && \
	cd /tmp/app/ && \
	mv ${SERVER_HOME}/webapps/${APP_NAME} ./ && \
	jar -xf ./${APP_NAME} && \
	rm -rf ./${APP_NAME} && \
	mv ${AGENT_HOME}/web.xml ./WEB-INF/web.xml && \
	jar -cf ${SERVER_HOME}/webapps/${APP_NAME} * && rm -rf /tmp/app

Find values for the following arguments that correspond to your application and environment:
- BASE_DOCKER_IMAGE: The name and path to the base image of your application.
- AGENT_VERSION: The agent version in the Docker image.
- AGENT_ZIP_FILE: Name of the agent .zip file. Default: Derived from AGENT_VERSION. Define this property for Jakarta builds.
- APP_NAME: Application name including the extension. For example, app.war
- AGENT_HOME: Docker directory where the agent is installed. Default: /opt.
- AM_URL: Identity Cloud or AM server URL including port number.
- SERVER_HOME: Path to the Tomcat server configuration. Default: /usr/local/tomcat.
- AGENT_URL: Agent URL.
- AGENT_REALM: Identity Cloud or AM realm containing the agent profile.
- AGENT_PROFILE: Agent profile name. Default /.

With a Docker daemon running, build the Docker image with the following command, replacing the example values with your own values:

/path/to/docker$ docker build --secret id=agent_secret \
  --build-arg BASE_DOCKER_IMAGE=fr-sample-app:1.0 \
  --build-arg AGENT_VERSION=2024.3 \
  --build-arg AGENT_ZIP_FILE=tomcat_agent_2024.3.zip \
  --build-arg APP_NAME=app.war \
  --build-arg AGENT_HOME=/opt \
  --build-arg AM_URL=https://am.example.com:8443/am \
  --build-arg AGENT_URL=http://agent.example.com:8080/app \
  --build-arg SERVER_HOME=/usr/local/tomcat \
  --build-arg AGENT_REALM=/ \
  --build-arg AGENT_PROFILE=java-agent \
  --tag agent-image:2024.3 .

...
 => => writing image sha256:803...ada  0.0s
 => => naming to docker.io/library/java-agent:2023.11

Run the container:

/path/to/docker$ docker run -it --name java-agent -p 8080:8080 agent-image:2023.11

...INFO [main] org.apache.coyote.AbstractProtocol.start Starting ProtocolHandler...
...INFO [main] org.apache.catalina.startup.Catalina.start Server startup ...

Access your application through the agent at http://agent.example.com:8080/app. Access is managed by Identity Cloud or AM according to the policy configured for the agent profile.

This example displays the Identity Cloud or AM login page. When you log in as a user, you access the sample application.

Upgrade and rollback

To upgrade or roll back an agent Docker container to a different agent version:

Build a new Docker container with the different agent version, using a tag that corresponds to the version.
Replace the image tag in your environment.

Java Agents 2024.3

Deploy Java Agent with Docker

Upgrade and rollback