Best Practice
ForgeRock Identity Platform
ForgeRock Identity Cloud

Best practice for installing IIS Web Agents (All versions)

Last updated Jan 11, 2023

The purpose of this article is to provide best practice advice on installing IIS Web Agents.

2 readers recommend this article


There are a number of things you should check before installing the IIS agents. In summary, these are:

  • All Application Development features are installed on the IIS web server. If you attempt to install the IIS agent without installing these features first, you will end up with empty debug directories and a non-working, non-registered IIS agent on your IIS web server.
  • The authentication method for IIS is set to anonymous.
  • All relevant configuration sections in the IIS Manager (under Site > Management > Configuration Editor) are unlocked. Typically, you will only need to unlock modules under the system.webServer configuration section (system.webServer/modules). If any required configuration sections are locked when you attempt the install, you will see the following error: Creating configuration... AddElement failed, file MACHINE/WEBROOT/APPHOST/SITE1: The process cannot access the file because another process has locked a portion of the file.
  • The application pool should be set as the default Integrated mode rather than Classic mode. In Classic mode, you cannot share sessions between the agent and another .NET application, so Logon and Impersonation are not operative. Furthermore, IIS in Classic mode treats all modules as ISAPI extensions and request processing, including that of Post Data Preservation, is affected.
  • Both the site and nested web application must be on the same application pool for them both to be protected by the agent. If they are on different application pools, only the site will be protected.
  • Pre-Web Agents 5.9: The value of the com.sun.identity.client.notification.url property has been removed; this is especially pertinent if the agent is configured for client-based sessions as you will encounter HTTP 403 errors when trying to access a protected resource if this property is populated. This property is not used in Agents 5.x and has been removed in Web Agents 5.9.

See Microsoft Windows systems for further information.


You should then install the IIS agents per the documentation: Install the IIS Web Agent.

If 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.


You should be consistent with running everything in 32bit mode or 64bit mode as appropriate. If you attempt to use a 64bit agent when running in 32bit mode (Enable 32-Bit Applications option set to 'true'), you will see the following error in the event logs:

The Module DLL 'D:\openam\web_agents\iis7_agent\bin\amiis7module.dll' could not be loaded due to a configuration problem. The current configuration only supports loading images built for a x86 processor architecture.

See Also

Installing a Web Agent (All versions) fails with a no ssl/library support error

redirect_uri_mismatch error occurs after upgrading to, or installing Agents (All versions)

Authentication fails with Internal Server Error (500) after installing or upgrading the Agent (All versions)

Related Training


Related Issue Tracker IDs


Copyright and Trademarks Copyright © 2023 ForgeRock, all rights reserved.