FAQ: Installing Agents in AM/OpenAM

Last updated Nov 2, 2020

The purpose of this FAQ is to provide answers to commonly asked questions regarding installing agents in AM/OpenAM.

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 there a Web Agent that is compatible with IBM HTTP Server (IHS)?

A. No, IHS is currently an unsupported platform. Although IBM Httpd was forked from Apache™, it is no longer the same as Apache which is why you cannot use an Apache agent.

IHS 9 will be supported on AIX only in a future release.

Q. Is there a Web Agent for the NGINX Plus web server?

A. Yes, the NGINX Plus web server has been supported since Web Policy Agent 4.1.0. Web Agent 5 supports NGINX Plus R12 and R13 on CentOS™, RedHat Enterprise Linux®, Ubuntu® and Oracle Linux.

See Web Policy Agent 4.1 Release Notes › What's New in Web Policy Agents and User Guide › Installing the NGINX Plus Web Agent for further information.

Why are different platform versions required?

The vast majority of the kernel options specified in the ngx_auto_config.h files (used during the agent build) need to be identical to the ones on the NGINX server, else the agent will fail its checks and will not load. As such, different platform specific versions of the agent are available and you should ensure you use the correct version.

If you use the wrong version for your platform, you will likely encounter binary compatibility issues and see errors such as:

"/opt/web_agents/nginx12_agent/lib/openam_ngx_auth_module.so" is not binary compatible in /etc/nginx/nginx.conf:1

Q. Is the Pivotal TC Server supported?

A. 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 AM/OpenAM. Besides providing the agent name and password, AM/OpenAM 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 console or ssoadm. Most of the agent configuration properties are defined in AM/OpenAM and must be configured within AM/OpenAM. All agent configuration and profile information is stored in the AM/OpenAM 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 AM/OpenAM is the details provided when creating the profile (agent name and password, AM/OpenAM 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.x and later - the OpenSSOAgentConfiguration.properties file located in the /path/to/java_agents/agent_type/agent_instance/ directory.
  • JEE Policy Agents 3.5.x - the OpenSSOAgentConfiguration.properties file located in the /config directory where the agent is installed.

See Web Agent User Guide › Configuration Location and Java Agents User Guide › Configuration for further information on these configuration properties.


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 OpenSSOAgentBootstrap.properties 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 AM/OpenAM if your agent is configured centrally.
  • Java Agents 5.x and later - 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 User Guide › Configuring Java Agent Properties for further information about these files.
  • JEE Policy Agents 3.5.x - there are two files in the /config directory where the agent is installed: the bootstrap file (OpenSSOAgentBootstrap.properties) and the properties file (OpenSSOAgentConfiguration.properties). See OpenAM JEE Policy Agent User's Guide › Configuring Java EE Policy Agent Properties for further information about these files.

If your agent configuration is not in the top-level realm (/), you must edit agent.conf 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 the AM/OpenAM server.

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 AM/OpenAM 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 AM/OpenAM 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 AM/OpenAM (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 AM/OpenAM (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 Policy Agents (All versions)

FAQ: Configuring Agents in AM/OpenAM

Agents and policies in AM/OpenAM

Installing and configuring AM/OpenAM

Web Agents User Guide

Java Agents User Guide

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-11104 (Tomcat Admin changes done by J2EEAgent not described (AMLogin.html))

Copyright and TrademarksCopyright © 2020 ForgeRock, all rights reserved.