FAQ: Installing Policy Agents in AM/OpenAM

Last updated Jan 27, 2020

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

Frequently asked questions

Q. What is the difference between Web and Java policy agents?

A. Web policy agents protect services and web resources hosted on a web or proxy server, whereas Java policy 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 policy 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 policy agent that is compatible with IBM AIX?

A. Yes, support for IBM AIX has been provided since Web policy agent 4. Web Agent 5 supports IBM AIX 6 and 7. See Release Notes › Platform Requirements for further information on supported platforms.

Q. Is there a Web policy 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 policy agent. 

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

Q. Is there a Web policy 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 policy agent will fail its checks and will not load. As such, different platform specific versions of the policy 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 policy 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 policy agents?

A. All policy agents need to have a profile in AM/OpenAM. Besides providing the policy agent name and password, AM/OpenAM URL and policy agent server URL, the profile also defines whether the policy agent is configured locally or centrally. See Setup and Maintenance Guide › Setting Up Policy Agent Profiles for further information.


Centralized configuration is the preferred option and is the default. It allows administrators to manage multiple policy agent configurations from a central place, using either the console or ssoadm. Most of the policy agent configuration properties are defined in AM/OpenAM and must be configured within AM/OpenAM. All policy 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 policy agent, which triggers them to reload the latest configuration. If you are using a load balancer, the notification is sent directly to the policy 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 (policy agent name and password, AM/OpenAM URL, policy 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 policy 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 varies depending on the agent and version:

  • Web Policy 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 policy agent is installed.

See User Guide › Configuring Web Agent Properties and User Guide › Configuring Java Agent Properties for further information on these configuration properties.


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

Q. How is the policy agent bootstrap file used?

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

  • Web Policy 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 policy 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 policy 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 policy 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 policy 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 policy agent configuration. Update the com.sun.identity.agents.config.organization.name property to change the / to the path to your policy agent profile. This allows the policy agent to properly identify itself to the AM/OpenAM server. 

When you start the policy 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 policy 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 Policy Agents

Some properties, such as debug level, exist in both the bootstrap file and AM/OpenAM (centralized 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 centralized 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 Policy 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.