Web Agents

Limitations

Limitations are inherent to the design, not bugs to be fixed. Unless otherwise stated, a limitation introduced in a release also exists in later releases.

Introduced in Description

2024.9

-

2024.6

-

2024.3

-

2023.11

-

2023.9

-

2023.6

-

2023.3

-

5.10

-

5.9
Custom login redirection mode

Redirect of users to a specific AM instance, an AM site, or website other than AM. For more information, refer to Login redirect.
Ignore path info properties are 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.

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.
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 com.sun.identity.client.notification.url is configured.

The com.sun.identity.client.notification.url property is removed in this release. Earlier versions of Web Agent use it to specify the notification listener for the agent. 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 agent installations, and must be removed for IIS web agents configured for client-based sessions.
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 HTTP 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.
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
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.