ForgeRock Identity Platform
ForgeRock Identity Cloud

FAQ: Installing Agents in Identity Cloud and AM

Last updated Jan 11, 2023

The purpose of this FAQ is to provide answers to commonly asked questions regarding installing Agents (Web or Java) in ForgeRock Identity Cloud and AM.

Frequently asked questions

Q. What is the difference between Web and Java Agents?

A. Web Agents protect services and web resources hosted on a web or proxy server, whereas Java Agents protect resources hosted on application or portal servers. Although the primary role of the two types of agents is to enforce authentication and authorization to a protected resource, they differ in the way policy decisions are enforced.

The following chapters provide detailed interactions for both Agent types.

Q. Are any of the Agents compatible with Oracle Java Development Kit (JDK) 11?

A. Yes, as of Java Agents 5.6, Oracle JDK 11 is supported. You should only use supported versions to prevent compatibility issues.

Q. Is the Pivotal TC Server supported?

A. No, the Pivotal TC Server is not supported.

The Pivotal TC Server is a Web application server based on open-source Apache Tomcat™, but it is customized in a way that the configuration filename and its location etc are not compliant with the default Tomcat server. For example:

pivotal-tc-server-developer-3.1.7.RELEASE/templates/base-tomcat-7/conf $ls catalina-fragment.properties catalina.policy logging-fragment.properties server-fragment.xml web-fragment.xml pivotal-tc-server-developer-3.1.7.RELEASE/tomcat-7.0.72.B.RELEASE $ls LICENSE NOTICE bin lib

As such, Java Agents cannot install on the Pivotal TC Server by default, it has not been tested nor is it supported. If you encounter any issues running on the Pivotal TC Server, you will be asked to reproduce them on a supported container.

Q. What is the difference between centralized and local configuration for Agents?

A. All agents need to have a profile in Identity Cloud or AM. Besides providing the agent name and password, AM URL and agent server URL, the profile also defines whether the agent is configured locally or centrally (remote).

Centralized (Remote)

Centralized configuration is the preferred option and is the default. It allows administrators to manage multiple agent configurations from a central place, using either the Identity Cloud or AM admin UI, or ssoadm in AM. Most of the agent configuration properties must be configured within Identity Cloud or AM. All agent configuration and profile information is stored in the Identity Cloud or AM configuration store. When changes are made to centralized configuration data, a change notification is sent to the affected agent, which triggers them to reload the latest configuration. If you are using a load balancer, the notification is sent directly to the agent without going via the load balancer.


With local configuration, the only information contained in Identity Cloud or AM is the details provided when creating the profile (agent name and password, AM URL, agent server URL and the fact that it is configured locally). The rest of the information is stored in a local configuration file as follows depending on your agent. When changes are made to local configuration data, a server restart is required for them to take effect. The name and location of the local configuration file vary depending on the agent and version:

  • Web Agents - the agent.conf file located in the /path/to/web_agents/agent_version/instances/Agent_nnn/config directory.
  • Java Agents 5.8 and later - the AgentConfiguration.properties file located in the /path/to/java_agents/agent_type/agent_instance/ directory
  • Java Agents (pre-5.8) - the OpenSSOAgentConfiguration.properties file located in the /path/to/java_agents/agent_type/agent_instance/ directory.

See Configuration Location (Web Agents) and Agent Configuration (Java Agents) for further information.


In both centralized and local configurations, properties used when the agent is started are captured in a local file. This is the same agent.conf file detailed above for Web Agents. For Java Agents, a separate file called AgentBootstrap.properties (Java Agents 5.8 and later) or OpenSSOAgentBootstrap.properties (pre-5.8) is used; see next question for information on the bootstrap file.

Q. How is the Agent bootstrap file used?

A. Agent properties are separated into those properties that are read and used at bootstrap time, and those that are not:

  • Web Agents - all properties are stored in the agent.conf file (located in the /path/to/web_agents/agent_version/instances/Agent_nnn/config directory). The properties specific to bootstrap time are only available in the agent.conf file, whereas the other properties are also available in Identity Cloud or AM if your agent is configured centrally.
  • Java Agents 5.8 and later - there are two files: the bootstrap file (AgentBootstrap.properties located in the /config directory where the agent is installed) and the properties file (AgentConfiguration.properties located in the /path/to/java_agents/agent_type/agent_instance/ directory). See Properties Reference for further information.
  • Java Agents (pre-5.8) - there are two files: the bootstrap file (OpenSSOAgentBootstrap.properties located in the /config directory where the agent is installed) and the properties file (OpenSSOAgentConfiguration.properties located in the /path/to/java_agents/agent_type/agent_instance/ directory). See Java Agent Properties for further information.

If your agent configuration is not in the top-level realm (/), you must edit agent.conf, AgentBootstrap.properties or OpenSSOAgentBootstrap.properties to identify the sub-realm that has your agent configuration. Update the com.sun.identity.agents.config.organization.name property to change the / to the path to your agent profile. This allows the agent to properly identify itself to Identity Cloud or AM.

When you start the agent, it reads and parses the file(s). It then uses the naming URL property from the bootstrap data to connect to Identity Cloud or AM and check if the agent is configured locally or centrally (remotely); if you are running remotely, a REST API call is used to fetch properties from the Identity Cloud or AM configuration data store and the properties (in memory) are overwritten with the centralized configuration.

Java Agents

Some properties, such as debug level, exist in both the bootstrap file and Identity Cloud or AM (remote configuration) or the configuration file (local configuration). In such cases, the value set for the bootstrap property is used at startup and is then overwritten once the bootstrap process is finished. For example, if you are troubleshooting an issue at startup, you should set up the debug level to all:5 in the bootstrap file; however, if you are troubleshooting an issue such as policy evaluation, you can modify the property centrally in Identity Cloud or AM (if you have remote configuration) without needing a restart.

Q. Why do I see "Another instance of agentadmin is already running" error when trying to install the Java Agent?

A. The following error is shown when the Java Agent agentadmin installer is aborted with the Ctrl+Z key combination instead of Ctrl+C:

ERROR: Another instance of agentadmin is already running. Please stop that instance and try again.

This key combination issues a Linux/Unix® command that suspends the process. You can resume the process by typing fg in the terminal and pressing Enter. At this point, you can choose to continue with the installation or type Ctrl+C to exit.

Alternatively, you can remove the Agentadmin.lock file located in /path/to/java_agents/agent_type/installer-logs/ to resolve the error and begin a fresh installation.

See Also

Best practice for installing IIS Web Agents (All versions)

FAQ: Configuring Agents in Identity Cloud and AM

Agents and policies in AM

Web Agents User guide

Java Agents User guide

Related Training

ForgeRock Access Management Deep Dive (AM-410)

Related Issue Tracker IDs


Copyright and Trademarks Copyright © 2023 ForgeRock, all rights reserved.