Web Agents 2024.11

Deploy Web Agent with Docker

The example in this section provides a Dockerfile and instructions to deploy Apache Web Agent to extend and protect an application. Adapt the information for other agent containers.

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 Centralized configuration mode. Learn more in Location of Agent Configuration Repository.

Deploy Apache Web Agent example

  1. Build a Docker image of your application. This example uses a sample application called fr-sample-app:1.0.

  2. In Advanced Identity Cloud or AM, set up an agent profile and policy. For more information, refer to Advanced 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: https://agent.example.com:443

    • Agent profile name: web-agent

    • Agent profile password: password

    • Policy set and policy: Allow HTTP GET and POST for all authenticated users.

  3. Create a local folder for the agent .zip file, the Dockerfile, and the agent profile password—they must be in the same folder. This example uses /path/to/docker.

  4. Download the agent .zip file to the local folder.

  5. 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, by using a password manager.

  6. 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=web-agent-${AGENT_VERSION}-Apache_v24_Linux_64bit.zip
ARG AGENT_HOME=/opt
ARG AM_URL
ARG APACHE_CONF=/usr/local/apache2/conf/httpd.conf
ARG AGENT_URL=http://agent.dummy.url:80
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}

# Install the agent and mount the file containing the agent password
RUN --mount=type=secret,id=agent_secret,required=true \
	"${AGENT_HOME}"/web_agents/apache24_agent/bin/agentadmin --s \
	"${APACHE_CONF}" \
	"${AM_URL}" \
	"${AGENT_URL}" \
	"${AGENT_REALM}" \
	"${AGENT_PROFILE}" \
	"/run/secrets/agent_secret" \
	--changeOwner \
	--forceInstall

  7. Find values for the following arguments that correspond to your application and environment:

    • agent_secret: The name of the file containing the agent profile password.

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

    • AGENT_HOME: Docker directory where the agent is installed. Default: /opt.

    • AM_URL: Advanced Identity Cloud or AM server URL including port number.

    • AGENT_URL: Agent URL. Default: `http://agent.dummy.url:80`.

    • APACHE_CONF: Path to the Apache server configuration. Default: /usr/local/apache2/conf/httpd.conf.

    • AGENT_REALM: Advanced Identity Cloud or AM realm containing the agent profile.

    • AGENT_PROFILE: Agent profile name. Default /.

  8. 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.11 \
  --build-arg AGENT_ZIP_FILE=web-agent-2024.11-Apache_v24_Linux_64bit.zip \
  --build-arg AGENT_HOME=/opt \
  --build-arg AM_URL=https://am.example.com:8443/am \
  --build-arg AGENT_URL=https://agent.example.com:443 \
  --build-arg APACHE_CONF=/etc/httpd/conf/httpd.conf \
  --build-arg AGENT_REALM=/ \
  --build-arg AGENT_PROFILE=web-agent \
  --tag agent-image:2024.11 .

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

  9. Run the container:

    /path/to/docker$ docker run -it --name apache24-agent -p 80:80 web-agent:2024.11

... Apache/2.4.58 (Unix) AM Web Agent/2024.11 configured -- resuming normal operations
... Command line: 'httpd -D FOREGROUND'

  10. Access your application through the agent at https://agent.example.com:443. Access is managed by Advanced Identity Cloud or AM according to the policy configured for the agent profile.

    This example displays the Advanced Identity Cloud or AM login in 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:

  1. Build a new Docker container with the different agent version, using a tag name that corresponds to the version.

  2. Replace the Docker image tag in your environment.