Installing Web Policy Agents in Microsoft IIS

This chapter covers prerequisites and installation procedures for Web Policy Agents 4 into Microsoft Internet Information Services (IIS) 7 and 8.

Before You Install

This section describes the prerequisite steps you should take before installing the web policy agents into IIS servers.

  • Ensure OpenAM is installed and running, so that you can contact OpenAM from the system running the policy agent.

  • Create a profile for your policy agent as described in Configuring Web Policy Agent Profiles.

  • Create at least one policy in OpenAM to protect resources with the agent, as described in the section on Configuring Policies. Consider creating a simple policy, such as a policy that allows only authenticated users to access your resources. This allows you to test your policy agent after installation.

  • If the OpenAM server you will be connecting to uses SSL, you must install OpenSSL on the agent machine.

    Ensure the OpenSSL libraries libeay32.dll and ssleay32.dll are available in the lib folder of your agent installation, for example c:\path\to\web_agents\iis_agent\lib\.

  • Web policy 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.

iis application development role
  • See the OpenAM Installation Guide section, Obtaining OpenAM Software to determine which version of the agent to download, and download the agent. Also, verify the checksum of the file you download against the checksum posted on the download page.

    Unzip the file in the directory where you plan to install the web policy agent. The agent you install stores its configuration and logs under this directory.

    When you unzip the policy agent .zip download, you find the following directories:

    bin

    The installation and configuration program agentadmin.

    config

    Configuration templates used by the agentadmin command during installation.

    instances

    Configuration files, and audit and debug logs for individual instances of the web policy agents will be created here. The folder is empty when first extracted.

    legal

    Contains licensing information including third-party licenses.

    lib

    Shared libraries used by the policy agent.

    log

    Location for log files written during installation. The folder is empty when first extracted.

Installing IIS Web Policy Agents

Complete the following procedures to install Web Policy Agents 4 into Apache HTTP Servers.

Check that you have completed the prerequisite steps before proceeding. See Before You Install.

To Create the Agent Profile

Regardless of whether you store configurations centrally in OpenAM or locally with your agents, the agent requires a profile so that it can connect to and communicate with OpenAM.

  1. In the OpenAM console, browse to Realms > Realm Name > Agents > Web, and then click the New…​ button in the Agent table.

  2. Complete the web form using the following hints.

    Name

    The name for the agent profile used when you install the agent

    Password

    Password the agent uses to authenticate to OpenAM

    Configuration

    Centralized configurations are stored in the OpenAM configuration store. You can manage the centralized configuration through the OpenAM console. Local configurations are stored in a file alongside the agent.

    Server URL

    The full URL to an OpenAM instance, or if OpenAM is deployed in a site configuration (behind a load balancer) then the site URL

    In centralized configuration mode, the Server URL is used to populate the agent profile for services, such as Login, Logout, Naming, and Cross Domain SSO.

    Agent URL

    The URL to the web agent application, such as http://www.example.com:80

    In centralized configuration mode, the Agent URL is used to populate the Agent Profile for services, such as notifications.

To Create a Password File
  1. Create a text file containing only the password specified when creating the agent profile.

    UNIX example:

    $ echo password > /tmp/pwd.txt

    Windows example:

    C:\> echo password > pwd.txt
  2. Protect the password file you create as appropriate for your operating system:

    UNIX example:

    $ chmod 400 /tmp/pwd.txt

    Windows example:

    In Windows Explorer, right-click the created password file, for example pwd.txt, select Read-Only, and then click OK.

To Install the Policy Agent into IIS
  1. Log on to Windows as a user with administrator privileges.

  2. Make sure OpenAM is running.

  3. Run agentadmin.exe with the --i switch to install the agent. You will be prompted to read and accept the software license agreement for the agent installation.

    c:\> cd web_agents\iis_agent\bin
    c:\web_agents\iis_agent\bin> agentadmin.exe --i
  4. When prompted for information, enter the inputs appropriate for your deployment.

    You can cancel web policy agent installation at anytime by pressing CTRL+C

    1. Enter the ID number of the IIS site in which to install the web policy agent.

      IIS Server Site configuration:
      
      Number of Sites: 2
      id: 1   name: "DEFAULT WEB SITE"
      id: 2   name: "CUSTOMERPORTAL"
      
      Enter IIS Server Site identification number.
      [ q or 'ctrl+c' to exit ]
      Site id: 2
    2. The installer can import settings from an existing web policy agent into 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 OpenAM instance the web policy agents will be using. Ensure the deployment URI is specified.

      Enter the URL where the OpenAM server is running. Please include the
      deployment URI also as shown below:
      (http://openam.sample.com:58080/openam)
      [ q or 'ctrl+c' to exit ]
      OpenAM server URL: http://openam.example.com:8080/openam
    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 OpenAM.

      Enter the Agent profile name
      [ q or 'ctrl+c' to exit ]
      Agent Profile name: iisagent
    6. Enter the OpenAM realm containing the agent profile.

      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:
        
           OpenAM URL: http://openam.example.com:8080/openam
           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.

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

    + The installer also sets up configuration and log directories for the agent instance. Each agent instance that you install on the system has its own numbered configuration and logs directory. The first agent’s configuration and logs are located under the directory web_agents\iis_agent\instances\agent_1\.

    +

    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.

    + The configuration files and log locations are as follows:

    +

    config/agent.conf

    Contains the bootstrap properties the web policy agent requires to connect to OpenAM and download its configuration. Also contains properties that are only used if you configure the web policy agent to use local configuration.

    logs/audit/

    Operational audit log directory, only used if remote logging to OpenAM is disabled.

    logs/debug/

    Debug directory where the amAgent debug file resides. Useful in troubleshooting policy agent issues.

Installing IIS Web Policy Agents Silently

You can run a silent, non-interactive installation by running agentadmin.exe --s, along with arguments used to configure the instance.

Check that you have completed the prerequisite steps before proceeding. See Before You Install.

The required arguments, and the order in which to specify them are:

Web server configuration file

Enter the ID number of the IIS site in which to install the web policy agent.

To list the sites in an IIS server, run agentadmin.exe --n:

OpenAM URL

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

Agent URL

Enter the full URL of the IIS site the agent will be running on.

Realm

Enter the OpenAM realm containing the agent profile.

Agent profile name

Enter the name given to the agent profile created in OpenAM.

Agent profile password

Enter the full path to the file containing the agent profile password.

--changeOwner

Optionally have the installer change the ownership of created directories to be the same user that is running the selected IIS site.

--acceptLicence

You can suppress the license agreement prompt during a silent, non-interactive install by including the --acceptLicence parameter. The inclusion of the option indicates that you have read and accepted the terms stated in the license. To view the license agreement, open /path/to/web_agents/agent_type/legal/Forgerock_License.txt.

--forceInstall

Add this optional switch to have the installer proceed with a silent installation even if it cannot connect to the specified OpenAM server during installation, rather than exiting.

For example:

c:\web_agents\iis_agent\bin> agentadmin.exe --s ^
  "1" ^
  "http://openam.example.com:8080/openam" ^
  "http://iis.example.com:80" ^
  "/" ^
  "iisagent" ^
  "c:\pwd.txt" ^
  --changeOwner ^
  --acceptLicence

OpenAM Web Agent for IIS Server installation.

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

Managing IIS Web Policy Agents

This section explains how to disable, enable, and remove web policy agents that are in an IIS site, and how to completely uninstall web policy agents from IIS.

To disable and enable a web policy agent in an IIS site
  1. Log on to Windows as a user with administrator privileges.

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

    c:\web_agents\iis_agent\bin> agentadmin.exe --l
    OpenAM Web Agent configuration instances:
    
       id:            agent_1
       configuration: c:\web_agents\iis_agent\bin\..\instances\agent_1
       server/site:   2

    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 policy agent in a site, run agentadmin.exe --d, and specify the ID of the web policy 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 policy agent in a site, run agentadmin.exe --e, and specify the ID of the web policy 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.
To remove a web policy agent from an IIS site
  1. Log on to Windows as a user with administrator privileges.

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

    c:\web_agents\iis_agent\bin> agentadmin.exe --l
    OpenAM Web Agent configuration instances:
    
       id:            agent_1
       configuration: c:\web_agents\iis_agent\bin\..\instances\agent_1
       server/site:   2

    Make a note of the ID value of the configuration instance you want to remove.

  3. Run agentadmin.exe --r, and specify the ID of the web policy agent configuration instance to remove.

    c:\web_agents\iis_agent\bin> agentadmin.exe --r agent_1
    
    Removing agent_1 configuration...
    Removing agent_1 configuration... Done.
To remove web policy agents from IIS
  1. Log on to Windows as a user with administrator privileges.

  2. Run agentadmin --g. A warning is displayed. Type yes to proceed with removing the configuration instance.

    c:\web_agents\iis_agent\bin> agentadmin.exe --g
    
    Warning! This procedure will remove all OpenAM Web Agent references from
    IIS Server configuration.
    
    Continue (yes/no): [no]: yes
    
    Removing agent module from IIS Server configuration...
    Removing agent module from IIS Server configuration... Done.

Enable IIS Basic Authentication and Password Replay Support

The IIS web policy 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 OpenAM, the IIS web policy 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 policy agent requests IIS server variable values from OpenAM, which gets them from Active Directory. The policy 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 LOGON_USER. The policy agent either sets all three, or does not set any of them.

When you enable Logon and Impersonation in the console (com.sun.identity.agents.config.iis.logonuser=true in the policy agent configuration), the policy agent performs Windows logon and sets the user impersonation token in the IIS session context.

When you enable Show Password in HTTP Header in the console (com.sun.identity.agents.config.iis.password.header=true in the policy agent configuration), the policy agent adds it in the USER_PASSWORD header.

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

The policy agent works best with IIS running in Integrated, not Classic mode. In Classic mode, you cannot share sessions between the policy 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 is affected. It is therefore strongly recommended that you run IIS in Integrated mode:

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

You must also apply workarounds as described 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 web site 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-SSL connection.

Summary: Enable SSL encryption on the web server.

To Configure IIS Basic Authentication and Password Replay Support

Follow these steps:

  1. Generate and store an encryption key:

    1. Generate the key using com.sun.identity.common.DESGenKey using the .jars where you deployed OpenAM, as in the following example. The Java command below is broken out into multiple lines for display purposes only:

      $ cd /tomcat/webapps/openam/WEB-INF/lib
      $ java -cp forgerock-util-3.0.0.jar:openam-core-13.jar:\
         openam-shared-13.jar com.sun.identity.common.DESGenKey
      Key ==> sxVoaDRAN0o=

      Windows users should use semi-colons (";"), instead of colons (":") in the commands. The Java command below is broken out into multiple lines for display purposes only:

      c:\> cd \tomcat\webapps\openam\WEB-INF\lib
      c:\> java -cp forgerock-util-3.0.0.jar;openam-core-13.jar; ^
          openam-shared-13.jar com.sun.identity.common.DESGenKey
      Key ==> sxVoaDRAN0o=
    2. In the OpenAM console navigate to Realms > Realm Name > Agents > Web > Agent Name > Advanced > Microsoft IIS Server > Replay Password Key (property name: com.sun.identity.agents.config.replaypasswd.key), enter the generated key, and then click Save.

    3. In the OpenAM console, navigate to Configuration > Servers and Sites > Server Name > Advanced > Add…​, then add a property com.sun.am.replaypasswd.key with the key you generated as the value, and then click Save.

  2. In the OpenAM console, navigate to Realms > Realm Name > Authentication > Settings > Post Authentication Processing > Authentication Post Processing Classes, then add the class com.sun.identity.authentication.spi.ReplayPasswd, and then click Save.

  3. If you require Windows logon, or you need to use basic authentication with SharePoint or OWA, then you must configure Active Directory as a user data store, and you must configure the IIS policy agent profile User ID Parameter and User ID Parameter Type so that the policy agent requests OpenAM to provide the appropriate account information from Active Directory in its policy response.

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

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

    In the OpenAM console under Realms > Realm Name > Agents > Web > Agent Name > OpenAM Services > Policy Client Service, set User ID Parameter and User ID Parameter Type, and then save your work. For example if the real username for Windows domain logon 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 the User ID Parameter Type to LDAP causes the policy agent to request that OpenAM get the value of the User ID Parameter attribute from the data store, in this case, Active Directory. Given that information, the policy agent can set the HTTP headers REMOTE_USER, AUTH_USER, or LOGON_USER and USER_PASSWORD with Active Directory attribute values suitable for Windows logon, setting the remote user, and so forth.

  4. To set the encrypted password in the AUTH_PASSWORD header, browse in the OpenAM console to Realms > Realm Name > Agents > Web > Agent Name > Advanced > Microsoft IIS Server, then select Show Password in HTTP Header, and then click Save.

  5. To have the agent perform Windows logon (for user token impersonation), browse in the OpenAM console to Realms > Realm Name > Agents > Web > Agent Name > Advanced > Microsoft IIS Server, then select Logon and Impersonation, and then click Save.

  6. In the OpenAM console, navigate to Realms > Realm Name > Agents > Web > Agent Name > Advanced > Microsoft IIS Server, then set Authentication Type to basic, and then click Save.

  7. (Optional) To access Microsoft Office from SharePoint pages, configure OpenAM to persist the authentication cookie. For details, see "Hints for the Persistent Cookie Module" in the OpenAM Administration Guide.