Web Agents 2023.11.1

Install IIS Web Agent

Web Agent instances can be configured to operate with multiple websites in IIS. Each configuration instance is independent and has its own configuration file, debug logs, and audit logs. Each instance can connect to a different AM realm, or even different AM servers.

Consider the following points:

  • Web Agent requires IIS to be run in Integrated mode.

  • A Web Agent configured for a site or parent application protects any application configured within. The same is true for protected applications containing applications within.

Consider the following restrictions:

  • Agents configured in a site or parent application do not protect children applications that do not inherit the parent’s IIS configuration.

  • Agents configured for a site or parent application running under a 64-bit pool do not protect child applications running under 32-bit pools due to architectural differences; 32-bit applications cannot load 64-bit web agent libraries and, therefore, will not be protected.

    The same is true for the opposite scenario.

    In this case, the child applications require their own web agent installation, as explained in the next item of this list. Both 32-bit and 64-bit agent libraries are supplied with the IIS Web Agent binaries.

  • If an application requires a specific web agent configuration or, for example, the application is a 32-bit application configured within a 64-bit site, follow the procedures in this section to create a new web agent instance for it. Configuring a web agent on an application overrides the application’s parent web agent configuration, if any.

    Install Web Agent on the child application before installing it in the parent. Trying to install an agent on a child that is already protected results in error.

  • You can disable the agent protection at any level of the IIS hierarchy, with the following constraints:

    • Disabling the agent in a parent application disables the protection on all children applications that do not have a specific agent instance installed on them.

    • Disabling the agent in a child application does not disable protection on its parent application.

  • Agents require that the Application Development component is installed alongside the core IIS services. Application Development is an optional component of the IIS web server. The component provides required infrastructure for hosting web applications.

    Web agents require that the Application Development component is installed alongside the core IIS services.
    Figure 1. Adding the application development component to IIS

Install IIS Web Agent interactively

  1. Review the information in Before you install, and perform the steps in Preinstallation tasks.

  2. Log on to Windows as a user with administrator privileges.

  3. Make sure AM is running.

  4. Run agentadmin.exe with the --i switch to install the agent.

    c:\> cd web_agents\iis_agent\bin
c:\web_agents\iis_agent\bin> agentadmin.exe --i

  5. When prompted, enter information for your deployment.

    To cancel the installation at any time, press CTRL-C.

    1. Choose the site and application in which to install the web agent.

      The agentadmin command reads the IIS server configuration and converts the IIS hierarchy into an ID composed of three values separated by the dot (.) character:

      • The first value specifies an IIS site. The number 1 specifies the first site in the server.

      • The second value specifies an application configured in an IIS site. The number 1 specifies the first application in the site.

      • The third value specifies an internal value for the web agent.

        The following is an example IIS server configuration read by the agentadmin command:

        IIS Server Site configuration:
====================================
id       details
====================================

         Default Web Site
         application path:/, pool DefaultAppPool
1.1.1    virtualDirectory path:/, configuration: C:\inetpub\wwwroot\web.config

         MySite
         application path:/, pool: MySite
2.1.1    virtualDirectory path:/, configuration C:\inetpub\MySite\web.config
         application path:/MyApp1, pool: MySite
2.2.1    virtualDirectory path:/  configuration C:\inetpub\MySite\MyApp1\web.config
         application path:/MyApp1/MyApp2, pool: MySite
2.3.1    virtualDirectory path:/  configuration C:\inetpub\MySite\MyApp1\MyApp2\web.config

Enter IIS Server Site identification number.
[ q or 'ctrl+c' to exit ]
Site id: 2.1.1

      • ID 2.1.1 corresponds to the first application, / configured in a second IIS site, MySite. You would choose this ID to install the web agent at the root of the site.

      • ID 2.2.1 corresponds to a second application, MyApp1, configured in a second IIS site, MySite. You would choose this ID to install the web agent in the MyApp1 application.

      • ID 2.3.1 corresponds to a child application, MyApp1/MyApp2, configured in the second application, MyApp1, configured in a second IIS site, MySite. You would choose this ID to install the web agent in the sub-application, MyApp1/MyApp2.

    2. The installer can import settings from an existing web agent on the new installation and skips prompts for any values present in the existing configuration file. You will be required to re-enter the agent profile password.

      Enter the full path to an existing agent configuration file to import the settings, or press Enter to skip the import.

      To set properties from an existing configuration enter path to file
[ q or 'ctrl+c' to exit, return to ignore ]
Existing agent.conf file:

    3. Enter the full URL of the AM instance the web agents will be using. Ensure the deployment URI is specified.

      If a reverse proxy is configured between AM and the agent, set the AM URL to the proxy URL, for example, https://proxy.example.com:443/am. For information about setting up an environment for reverse proxies, refer to Apache as a reverse proxy. 
      Enter the URL where the AM server is running. Please include the
deployment URI also as shown below:
(http://am.sample.com:58080/am)
[ q or 'ctrl+c' to exit ]
AM server URL: https://am.example.com:8443/am

    4. Enter the full URL of the site the agent will be running in.

      Enter the Agent URL as shown below:
(http://agent.sample.com:1234)
[ q or 'ctrl+c' to exit ]
Agent URL: http://customers.example.com:80

    5. Enter the name given to the agent profile created in AM.

      Enter the Agent profile name
[ q or 'ctrl+c' to exit ]
Agent Profile name: iisagent

    6. Enter the agent profile realm. Realms are case-sensitive.

      Enter the Agent realm/organization
[ q or 'ctrl+c' to exit ]
Agent realm/organization name: [/]: /

    7. Enter the full path to the file containing the agent profile password created earlier.

      Enter the path to a file that contains the password to be used
for identifying the Agent
[ q or 'ctrl+c' to exit ]
The path to the password file: c:\pwd.txt

    8. The installer displays a summary of the configuration settings you specified.

      If a setting is incorrect, type no, or press Enter. The installer loops through the configuration prompts using your provided settings as the default. Press Enter to accept each one, or enter a replacement setting.

      If the settings are correct, type yes to proceed with installation.

      Installation parameters:
   AM URL: https://am.example.com:8443/am
   Agent URL: http://customers.example.com:80
   Agent Profile name: iisagent
   Agent realm/organization name: /
   Agent Profile password source: c:\pwd.txt

Confirm configuration (yes/no): [no]: yes Validating…​
Validating…​ Success.
Cleaning up validation data…​
Creating configuration…​
Installation complete.

      On successful completion, the installer adds the agent as a module to the IIS site configuration.

      The installer grants full access permissions on the created instance folder to the user that the selected IIS site is running under, so that log files can be written correctly.

      Each agent instance has a numbered configuration and logs directory. The first agent configuration and logs are located in web_agents\iis_agent\instances\agent_1\.

  6. Ensure the application pool identity related to the IIS site has the appropriate permissions on the following agent installation folders:

    • \web_agents\iis_agent\lib

    • \web_agents\iis_agent\log

    • \web_agents\iis_agent\instances\agent_nnn

      To change the ACLs for files and folders related to the agent instance, run the agentadmin --o command. For example:

      C:\web_agents\iis_agent\bin>agentadmin.exe --o "ApplicationPoolIdentity1" "C:\web_agents\iis_agent\lib"

      For more information, refer to agentadmin command.

      When permissions are not set correctly, errors such as getting a blank page when accessing a protected resource can occur.

  7. If you installed Web Agent in an application, set CDSSO Redirect URI to the application path, as follows:

    1. Go to Realms > Realm Name > Agents > Web > Agent Name > SSO > Cross Domain SSO.

    2. Add the application path to the default value of CDSSO Redirect URI. For example, if you installed Web Agent in an application such as MyApp1/MyApp2, set the property to MyApp1/MyApp2/agent/cdsso-oauth2.

    3. Save your changes.

Install IIS Web Agent silently

Use the agentadmin --s command for silent installation. For information about the options, refer to agentadmin command.

  1. Review the information in Before you install, and perform the steps in Preinstallation tasks.

  2. Make sure AM is running.

  3. Run the agentadmin --s command with the required arguments. For example:

    c:\web_agents\iis_agent\bin> agentadmin.exe --s ^
  "2.1.1" ^
  "https://am.example.com:8443/am" ^
  "http://iis.example.com:80" ^
  "/" ^
  "iisagent" ^
  "c:\pwd.txt" ^
  --acceptLicence

AM Web Agent for IIS Server installation.

Validating…​
Validating…​ Success.
Cleaning up validation data…​
Creating configuration…​
Installation complete.

  4. Ensure the application pool identity related to the IIS site has the appropriate permissions on the following agent installation folders:

    • \web_agents\iis_agent\lib

    • \web_agents\iis_agent\log

    • \web_agents\iis_agent\instances\agent_nnn

      To change the ACLs for files and folders related to the agent instance, run the agentadmin --o command. For example:

      C:\web_agents\iis_agent\bin>agentadmin.exe --o "ApplicationPoolIdentity1" "C:\web_agents\iis_agent\lib"

      For more information, refer to agentadmin command.

      When permissions are not set correctly, errors such as getting a blank page when accessing a protected resource can occur.

  5. (Optional) If you installed the agent in a parent application, enable it for its child applications by following the steps in Disable and enable agent protection for child applications.

Enable and disable IIS Web Agent

Disable and enable Web Agent on an IIS site or application

The agentadmin command shows only instances of the web agent; to enable or disable the protection of children applications, refer to Disable and enable agent protection for child applications.

  1. Log on to Windows as a user with administrator privileges.

  2. Run agentadmin.exe --l to output a list of the installed web agent configuration instances.

    c:\web_agents\iis_agent\bin> agentadmin.exe --l

AM Web Agent configuration instances:

   id:            agent_1
   configuration: c:\web_agents\iis_agent\bin\..\instances\agent_1
   server/site:   2.2.1

    Make a note of the ID value of the configuration instance you want to disable or enable.

  3. Perform one of the following steps:

    • To disable the web agent in a site, run agentadmin.exe --d, and specify the ID of the web web agent configuration instance to disable.

      c:\web_agents\iis_agent\bin> agentadmin.exe --d agent_1

Disabling agent_1 configuration…​
Disabling agent_1 configuration…​ Done.

    • To enable the web agent in a site, run agentadmin.exe --e, and specify the ID of the web agent configuration instance to enable.

      c:\web_agents\iis_agent\bin> agentadmin.exe --e agent_1

Enabling agent_1 configuration…​
Enabling agent_1 configuration…​ Done.

Disable and enable agent protection for child applications

  1. Edit the child application’s web.config configuration.

  2. Decide whether to enable or disable web agent protection:

    • To disable agent protection, add the following lines to the child application’s web.config file:

      <OpenAmModule enabled="false" configFile="C:\web_agents\iis_agent\instances\agent_1\config\agent.conf" />
<modules>
   <add name="OpenAmModule64" preCondition="bitness64" />
</modules>

      Note that the path specified in configFile may be different for your environment.

    • To enable agent protection, understand that web agents configured in a site or parent application also protect any applications that are inheriting the IIS configuration from that site or parent.

      If you have disabled the agent’s protection for a child application by following the steps in this procedure, remove the lines added to the web.config file to enable protection again.

Enable support for IIS basic authentication and password replay

The IIS web agent now supports IIS basic authentication and password replay. You must use the appropriate software versions.

Given the proper configuration and with Active Directory as a user data store for AM, the IIS web agent can provide access to the IIS server variables. The instructions for configuring the capability follow in this section, though you should read the section in full, also paying attention to the required workarounds for Microsoft issues.

When configured as described, the web agent requests IIS server variable values from AM, which gets them from Active Directory. The web agent then sets the values in HTTP headers so that they can be accessed by your application.

The following IIS server variables all take the same value when set: REMOTE_USER, AUTH_USER, and login_USER. The agent either sets all three, or does not set any of them.

When Logon and Impersonation is enabled, the agent performs Windows login and sets the user impersonation token in the IIS session context.

When Show Password in HTTP Header is enabled, the agent adds the password in the USER_PASSWORD header.

The agent does not modify any other IIS server variables related to the authenticated user’s session.

The agent requires that IIS runs in Integrated mode. Consider the following points for integration with additional Microsoft products:

  • For Microsoft Office integration, you must use Microsoft Office 2007 SP2 or later.

  • For Microsoft SharePoint integration, you must use Microsoft SharePoint Server 2007 SP2 or later.

Microsoft issues

Apply workarounds for the following Microsoft issues:

Microsoft support issue: 841215

Link: http://support.microsoft.com/kb/841215

Description: Error message when you try to connect to a Windows SharePoint document library: "System error 5 has occurred".

Summary: Enable Basic Authentication on the client computer.

Microsoft support issue: 870853

Link: http://support.microsoft.com/kb/870853

Description: Office 2003 and 2007 Office documents open read-only in Internet Explorer.

Summary: Add registry keys as described in Microsoft’s support document.

Microsoft support issue: 928692

Link: http://support.microsoft.com/kb/928692

Description: Error message when you open a Web site by using Basic authentication in Expression Web on a computer that is running Windows Vista: "The folder name is not valid".

Summary: Edit the registry as described in Microsoft’s support document.

Microsoft support issue: 932118

Link: http://support.microsoft.com/kb/932118

Description: Persistent cookies are not shared between Internet Explorer and Office applications.

Summary: Add the website the list of trusted sites.

Microsoft support issue: 943280

Link: http://support.microsoft.com/kb/943280

Description: Prompt for Credentials When Accessing FQDN Sites From a Windows Vista or Windows 7 Computer.

Summary: Edit the registry as described in Microsoft’s support document.

Microsoft support issue: 968851

Link: http://support.microsoft.com/kb/968851

Description: SharePoint Server 2007 Cumulative Update Server Hotfix Package (MOSS server-package): April 30, 2009.

Summary: Apply the fix from Microsoft if you use SharePoint.

Microsoft support issue: 2123563

Link: http://support.microsoft.com/kb/2123563

Description: You cannot open Office file types directly from a server that supports only Basic authentication over a non-TLS connection.

Summary: Enable TLS communications on the web server.

To Configure IIS basic authentication and password replay support

  1. Use the openssl tool to generate a suitable encryption key:

    $ openssl rand -base64 32
e63…​sw=

  2. In the AM admin UI, go to Deployment > Servers > Server Name > Advanced, and then add a property com.sun.am.replaypasswd.key with the encryption key you generated in a previous step as the value.

  3. Go to Realms > Realm Name > Authentication > Settings > Post Authentication Processing, and in Authentication Post Processing Classes, add the class com.sun.identity.authentication.spi.ReplayPasswd.

  4. Restart AM.

  5. In the AM admin UI go to Realms > Realm Name > Applications > Agents > Web > Agent Name > Advanced

    1. In Replay Password Key, enter the encryption key generated in a previous step.

    2. For Windows login for user token impersonation, enable Logon and Impersonation.

    3. Save your changes.

  6. (Optional) To set the encrypted password in the IIS AUTH_PASSWORD server variable, go to Realms > Realm Name > Applications > Agents > Web > Agent Name > Advanced, and enable Show Password in HTTP Header.

  7. (Optional) If you require Windows login, or you need to use basic authentication with SharePoint or OWA, then you must do the following so that the agent requests AM to provide the appropriate account information from Active Directory in its policy response:

    • Configure Active Directory as a user data store

    • Configure the IIS web agent profile User ID Parameter and User ID Parameter Type.

      Skip this step if you do not use SharePoint or OWA and no Windows login is required.

      Make sure the AM data store is configured to use Active Directory as the user data store.

      In the AM admin UI under Realms > Realm Name > Applications > Agents > Web > Agent Name > AM Services, set User ID Parameter and User ID Parameter Type.

      For example, if the real username for Windows domain login in Active Directory is stored on the sAMAccountName attribute, then set the User ID Parameter to sAMAccountName, and the User ID Parameter Type to LDAP.

      Setting User ID Parameter Type to LDAP causes the web agent to request that AM get the value of the User ID Parameter attribute from the data store, in this case, Active Directory. Given that information, the agent can set the HTTP headers REMOTE_USER, AUTH_USER, or login_USER and USER_PASSWORD with Active Directory attribute values suitable for Windows login, setting the remote user, and so forth.

  8. (Optional) To access Microsoft Office from SharePoint pages, configure AM to persist the authentication cookie. For information, refer to "Persistent cookie module" or "Persistent cookie decision node in AM’s Authentication and SSO guide.

Install in a subrealm

Examples in this document install the agent in the top-level realm. To install the agent in a subrealm during interactive or silent installation, use the subrealm during the installation or in the response file.

For example, instead of:

Agent realm/organization name: [/]: /

specify:

Agent realm/organization name: [/]: /myrealm

Even though the agent is installed in a subrealm, the default login redirect requires the user realm to be the top-level realm. For information about how to change the user realm, refer to Login redirect.