• ForgeRock periodically issues patch and minor releases with important fixes to improve the functionality, performance, and security of your web agent deployments. Web Agents 5.5.1.0 is the latest minor release, targeted for AM 6.5 deployments and can be downloaded from the ForgeRock BackStage website. To view the list of fixes in this release, see Web Agents 5.5.1.0.

Web Agents 5.5 is a minor release that includes new features, functional enhancements and fixes.

• Agents Sharing Runtime Resources

  In earlier versions of the Apache and NGINX Plus agent, each agent instance had its own runtime resources and shared memory.

  Apache (Unix) and NGINX Plus Web Agents 5.5 default to share agent runtime resources, installation files and shared memory among all the agent instances. For example, the Agent_1 and Agent_2 instances write the same session logs and audit files (even though each one write to their own file), use the same agent policy cache, and run a single set of worker processes and background tasks.

  To support this change, web agents now log system information in a different log file. For more information, see "Important Changes to Existing Functionality".

  Sharing runtime resources and shared memory is configurable, and you should take it into account when upgrading to Web Agents 5.5. For more information, see "Configuring Whether Unix Web Agents Should Share Runtime Resources and Shared Memory" in the User Guide.

• Validation Option Added to the agentadmin Command

  Web Agents 5.5 adds a new option, --V, to validate agent configurations. Use this option to troubleshoot agent configuration issues in your environment, or before opening a ticket with ForgeRock's Customer Support.

  For more information, see "Command-Line Tool Reference" in the User Guide.

• Shared Memory Requirement Reduced

  Web Agents 5.5 now require a minimum of 16 MB of shared memory for the session and policy cache and the various worker process and, additionally, 32 KB of shared memory for the logging system, down from 140 MB.

  For more information, see "Other Requirements".

• Improved File Permission Management for Unix Agents

  Earlier versions of the Unix agents created several runtime files and resources in such a way that they were always owned by the root user.

  Web Agents 5.5 ensure that runtime resources and files are always created by the user relevant to the agent. For example, all runtime resources created by the NGINX Plus agent belong to the user specified in the User directive in the NGINX Plus server configuration file.

  Moreover, Web Agents 5.5 include a new environment variable, AM_RESOURCE_PERMISSIONS, which specifies the permissions that the agent sets for its runtime resources based on the value of umask.

  For more information, see "Configuring Web Agent Environment Variables" in the User Guide.

• REST Response Timeout Now Configurable

  You can now use the com.sun.identity.agents.config.receive.timeout property to configure the amount of time, in seconds, to wait for a response from the AM server.

  The default is 4 seconds, which matches the previous hard-coded value.

  For more information, see "Configuring Bootstrap Properties" in the User Guide.

• OpenAM

• AM versions earlier than 5.5.

• Fully Qualified Domain Name Checking Off by Default

  The com.sun.identity.agents.config.fqdn.check.enable is now set to false by default. This default value was changed for the 5.5.2.0 release and differs from previous releases, which was set to true. The change better aligns local configurations to be consistent with centralized profiles, which has FQDN checking off by default.

• There are no important changes to existing functionality in this release.

• Changes to the Logging System

  Earlier versions of the web agents logged system information to the /web_agents/agent_type/log/agent.log file.

  Web Agents 5.5 log system information to the /web_agents/agent_type/log/system_n.log, where n indicates the agent group number.

  Consider an environment with two Apache server installations:

  • Apache_1 has two agent instances configured, agent_1 and agent_2, configured to share runtime resources (AmAgentId is set to 0). Both agent instances will write to the syslog_0.log file.

  • Apache_2 has one agent instance configured, agent_3, with AmAgentId set to 1. The instance will write to the syslog_1.log file.

  The system_n.log file can contain the following information:

  • Agent version information, written when the agent instance starts up.

  • Logs for the agent background processes.

  • Web Socket connection errors.

  • Cache stats and removal of old POST data preservation files.

  • Agent notifications.

  Moreover, the AM_DEFAULT_LOG_LEVEL environment property has been renamed to AM_SYSTEM_LOG_LEVEL. Use this property to set up the log level for the instances. For more information, see Web Agent Environment Properties in the User Guide.

• Changes to AM URL Validation

  In earlier versions, web agents used the following properties to validate that it could reach the AM instances it was connected to:

  • com.forgerock.agents.ext.url.validation.default.url.set

  • com.forgerock.agents.ext.url.validation.level

  • com.forgerock.agents.ext.url.validation.ping.interval

  • com.forgerock.agents.ext.url.validation.ping.miss.count

  • com.forgerock.agents.ext.url.validation.ping.ok.count

  • com.sun.identity.agents.config.naming.url

  Web Agents 5.5 removes all the properties but com.sun.identity.agents.config.naming.url property, which should be configured to the load balancer in front of the AM instances (or load balancers, in case of having multiple sites).

• Changes to agentadmin --v Command Output

  Information regarding system resources is no longer included in the output from the agentadmin --v command.

  System resource information is now displayed by using the new agentadmin --V (Validator) command. For more information, see "Command-Line Tool Reference" in the User Guide

• Agents Timestamp Events in Coordinated Universal Time (UTC)

  When logging to a file, previous versions of the web agents timestamped events using the current timezone configured for the server.

  Web Agents 5.5 timestamp events in UTC.

• There is no deprecated functionality in this release.

• There is no deprecated functionality in this release.

• No components were removed in this release.

• AM_DEFAULT_LOG_LEVEL Environment Property Renamed

  The AM_DEFAULT_LOG_LEVEL has been renamed to AM_SYSTEM_LOG_LEVEL.

  For more information, see Web Agent Environment Properties in the User Guide.

• Removed properties

  The following properties have been removed from Web Agents 5.5:

  • com.forgerock.agents.ext.url.validation.default.url.set

  • com.forgerock.agents.ext.url.validation.level

  • com.forgerock.agents.ext.url.validation.ping.interval

  • com.forgerock.agents.ext.url.validation.ping.miss.count

  • com.forgerock.agents.ext.url.validation.ping.ok.count

• AMAGENTS-1933: init_ssl errors fill error_log

• AMAGENTS-1977: Add openssl 1.1.1 library detection for AIX web agent

• AMAGENTS-1982: Custom login page issue when handling advices

• AMAGENTS-2053: Web agent does not honour com.sun.identity.agents.config.attribute.multi.value.separator value

• AMAGENTS-2085: Web Agent 5 should not have a value for com.sun.identity.client.notification.url property in OpenSSOAgentConfiguration.properties

• AMAGENTS-2095: Agent validator crash on Windows with erroneous agent.conf file

• AMAGENTS-2147: Agent 5.5x has a race condition creating semaphores on centos 32

• AMAGENTS-2150: Update pcre and http_parser libraries for agents 5.5.0.1

• AMAGENTS-2152: Original_request_url is not present after upgrading to Agent 5

• AMAGENTS-2153: WPA resource leak in json_find_node

• AMAGENTS-1840: Agent's version information disappear from the debug.log

• AMAGENTS-1598: The agent gives 403 response rather than redirect when token is invalid before notification is received

• AMAGENTS-1556: WPA5 crashes when running with local audit log mode enabled

• AMAGENTS-1552: WPA5 crashes on return from auth redirect when username contains UTF8 characters

• AMAGENTS-1551: WPA agentadmin --g option is changing empty xml element value

• AMAGENTS-1550: WPA5 doesn't encode white space in username for REST /users endpoint

• AMAGENTS-1537: Agent 5 does not have standard solution for custom login pages.

• AMAGENTS-1533: web agent 5 is not working with AM6

• AMAGENTS-1511: Agent5 is crashing on Apache for Windows server shutdown

• AMAGENTS-1510: Agent5 is crashing with unchecked use of r->conf->jwt_name value

• AMAGENTS-1509: Agent5 is crashing with unchecked use of r->conf->redirect_uri value

• AMAGENTS-1408: SIGSEGV when trying to install agent 5 with wrong AM version

• AMAGENTS-1185: url.validation.ping.interval does not work for C Agent 5

• AMAGENTS-1174: Files are left over in tmp directory after apache has been switched off

• AMAGENTS-1030: Nginx Web agent add Authorization header and send request along.

• There are no additional limitations and workarounds in this release. Refer to previous releases for more information.

The following limitations and workarounds apply to Web Agent 5.5:

• Ignore Path Info Properties Is not Supported for NGINX Plus Agent

  The NGINX Plus web agent does not support the following ignore path info properties:

  • com.sun.identity.agents.config.ignore.path.info

  • com.sun.identity.agents.config.ignore.path.info.for.not.enforced.list

• IIS Web Agents May Fail to Install When IIS Configuration Is Locked

  Installing web agents in IIS may fail with an error similar to the following:

  Creating configuration...
      Error: failed to create module entry for MACHINE/WEBROOT/APPHOST/AgentSite/ (error 0x80070021, line: 1823).
      The process cannot access the file because another process has locked a portion of the file. (error: 0x21).
      Installation failed.

  This error message means the agentadmin.exe command cannot access some IIS configuration files because they are locked.

  To work around this issue, perform the following steps:

  1. Open the IIS Manager and select the Configuration Editor.

  2. Unlock the IIS system.webServer/modules module.

  3. Retry the web agent installation.

  Note

  Unlocking the system.webServer/modules module should allow the installation to finish. However, you may need to unlock other modules depending on your environment.

• Apache HTTP Server Authentication Functionality Not Supported

  The web agent replaces authentication functionality provided by Apache, for example, the mod_auth_* modules. Integration with built-in Apache httpd authentication directives, such as AuthName, FilesMatch, and Require is not supported.

• AMAGENTS-456: URL Comparison Case Sensitivity Check does not work for policies

• AMAGENTS-523: The files created during installation (e.g agent.conf) have the wrong permissions

• AMAGENTS-1584: Error message is confusing if using a different realm for obtaining the ID token compared with the SSO token

• AMAGENTS-2164: When setting audit log location to REMOTE there is a huge drop in performance

• CA Certificate File Name Property not Honored when Client Authentication is not Required in Secure Channel Environments

  If you are using the Windows built-in Secure Channel API but your environment does not require client authentication, instead of setting the CA certificate friendly name in the CA Certificate File Name Property, set it in the Public Client Certificate File Name property. For example:

  com.forgerock.agents.config.cert.ca.file =
  com.forgerock.agents.config.cert.file = CA-cert-friendly-name
  com.sun.identity.agents.config.trust.server.certs = false

• IIS Web Agent With Client-Based Sessions Returning HTTP 403 Errors When Accessing Protected Resources

  IIS web agents configured for client-based sessions will return HTTP 403 errors when trying to access a protected resource if the com.sun.identity.client.notification.url property is configured.

  The com.sun.identity.client.notification.url property, used by earlier versions of the web agents to specify the notification listener for the agent, is not used or required anymore. However, to provide backwards-compatibility with earlier versions of the agents, AM populates this property when creating the agent profile.

  The value of this property should removed for all web agents installations, and must be removed for IIS web agents configured for stateless (client-based) sessions.

• Install IIS Web Agents on Child Applications Before Installing in Parent Application

  In an IIS environment where you need to protect a parent application and a child application with different web agent configurations, you must install the web agent on the child application before installing the web agent in the parent. Trying to install a web agent on a child that is already protected will result in error.

• Default Welcome Page Showing After Upgrade Instead of Custom Error Pages

  After upgrading, you may see the default Apache welcome pages instead of custom error pages defined by the Apache ErrorDocument directive.

  If you encounter this issue, check your Apache ErrorDocument configuration. If the custom error pages are not in the document root of the Apache server, you should enclose the ErrorDocument directives in Directory elements. For example:

  <Directory "/web/docs">
     ErrorDocument 403 myCustom403Error.html
  </Directory>

  Refer to the Apache documentation for more details on the ErrorDocument directive.

• AMAGENTS-1584: Error message is confusing if using a different realm for obtaining the ID token compared with the SSO token

• AMAGENTS-1486: Agents 5 bootstrap retry settings are not used

• AMAGENTS-1319: Changing debug log level in agent profile has effect for background tasks agent.log file

• AMAGENTS-1310: When we install the agent manually on Ubuntu Apache, the installer does not change permissions on the agent files

• AMAGENTS-1295: Can not disable configuration change notifications with Solaris Agent

• AMAGENTS-1267: org.forgerock.agents.config.secure.channel.disable should be in agent.conf by default

• AMAGENTS-1252: It is not possible to install an IIS agent for child application, if one agent instance is installed for parent application/site

• AMAGENTS-1240: Decrease log level for incorrect JWT token in Agent 5

• AMAGENTS-1156: Disabled "Agent Configuration Change Notification" does not work properly, if new worker is created for C Agent

• AMAGENTS-1039: If C Agent Policy Client Service - Realm does not have a slash at the start the realm value is not understood by the C Agent

• AMAGENTS-769: org.forgerock.agents.config.cdsso.deny.cleanup.disable property is not valid for C Agent 5

• AMAGENTS-704: C Agent 5 returns 403, if you don't login immediately

• AMAGENTS-523: The files created during installation (e.g agent.conf) have the wrong permissions

• AMAGENTS-456: URL Comparison Case Sensitivity Check does not work for policies