Notes covering prerequisites, fixes, and known issues for ForgeRock® Access Management Web Agent. ForgeRock Access Management provides authentication, authorization, entitlement, and federation software.

The bootstrap property org.forgerock.agents.config.connection.pool.enable was added for HTTP connection pooling, and is enabled by default.

Use connection pooling to improve performance when AM is available over low bandwidth connections, or to throttle the maximum number of connections made by the agent.

For more information, see org.forgerock.agents.config.connection.pool.enable in the User Guide.

The name of the cookie that the agent accepts as an SSO token, or uses in custom login mode, can now be specified in the property com.sun.identity.agents.config.cookie.name. If the cookie name is not specified, the agent retrieves it from the AM server.

For more information, see Cookie Name in the User Guide, Accept SSO Token in the User Guide, and Custom Login Mode in the User Guide.

A load balancing cookie can now be sent to AM for policy, session, and other calls. Use this property to reduce the number of calls that different AM instances make to the Core Token Service (CTS).

For more information, see AM Load Balancer Cookie Enabled in the User Guide.

Redirect of users to a specific AM instance, an AM site, or website other than AM, requires AM 6 or later versions. For more information, see "Login Redirection and Login Conditional Redirection" in the User Guide.

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

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:

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.

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 client-based sessions.

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.

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

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.