Web Agents

Limitations

The following limitations are inherent to the design, not bugs to be fixed.

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

The NGINX Plus web agent doesn’t 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 Agent installation

Locked IIS configuration

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.

Installation order

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.

IIS Web Agent with client-based sessions

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 was removed in an earlier unsupported 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 be removed for all agent installations, and must be removed for IIS web agents configured for client-based sessions.

Apache HTTP server authentication functionality

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.

Custom error pages not showing after upgrade

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

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