Chapter 4. Installing the Microsoft IIS 6 Policy Agent

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 Access Control > 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 web server URL that the agent protects

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

1. Protect the password file you will create as appropriate.

2. Create a text file containing only the password.

   C:\>notepad C:\Windows\Temp\pwd.txt

1. Log on as a user with Administrator privileges.

2. Change to the directory where you unpacked the agent download.

   C:\>cd web_agents\iis6_agent\bin

3. Create a configuration file using the IIS6CreateConfig.vbs script.

   Note

   The Web Site Identifier is the value of id, not the site name.

   C:\web_agents\iis6_agent\bin>cscript IIS6CreateConfig.vbs config.txt
   ...
   Enter the Agent Resource File Name [IIS6Resource.en] :
   
   Enter the Agent URL (Example: http://agent.example.com:80) :
   http://windows2003.example.com:80
   
   Displaying the list of Web Sites and its corresponding Identifiers
   Site Name (Site Id)
   Default Web Site (1)
   
   Web Site Identifier :
   1
   ...
   Enter the URL where the OpenAM server is running...:
   http://openam.example.com:8080/openam
   
   Please enter the Agent Profile name :
   IIS 6 Web Agent
   
   Enter the Agent profile password file :
   C:\Windows\Temp\pwd.txt
   
   -----------------------------------------------------
   Agent Configuration file created : config.txt
   -----------------------------------------------------

1. Log on as a user with Administrator privileges.

2. Make sure OpenAM is running.

3. Run IIS6Admin.vbs to install the agent.

   C:\web_agents\iis6_agent\bin>cscript IIS6Admin.vbs -config config.txt
   ...
   Enter the Agent Resource File Name [IIS6Resource.en] :
   
   Creating the Agent Config Directory
   Creating the  and
     File
   Updating the Windows Product Registry
   Loading the IIS 6.0 Agent
   Completed Configuring the IIS 6.0 Agent

4. Restart IIS 6.

   C:\web_agents\iis6_agent\bin>iisreset
   
   Attempting stop...
   Internet services successfully stopped
   Attempting start...
   Internet services successfully restarted

   Note

   If the agent is in a different domain than the server, refer to Administration Guide procedure, Configuring Cross-Domain Single Sign On.

5. Take note of the configuration files and log locations.

   Each agent instance that you install on the system has its own configuration and logs directory. The agent protecting the Default Web Site (1) shown in the examples above has configuration and logs located under the directory web_agents\iis6_agent\Identifier_1. The number in the path to the agent configuration reflects the IIS site ID, unlike the other agents for which the number in the path is a counter. The number in the path therefore remains the same when you uninstall and then reinstall an agent to protect the same site.

   config\

   Used to bootstrap the web policy agent, allowing the agent to connect to OpenAM and download its configuration

   config\

   Only used if you configured the web policy agent to use local configuration

   audit\

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

   debug\

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

6. If your policy agent configuration is not in the top-level realm (/), then you must edit config\ to identify the sub-realm that has your policy agent configuration. Find com.sun.identity.agents.config.organization.name and change the / to the path to your policy agent profile. This allows the policy agent to properly identify itself to the OpenAM server.

7. If the web policy agent performs naming URL validation, which you can configure by setting the com.forgerock.agents.ext.url.validation.level property in config\OpenSSOAgentBootstrap.properties, then make sure the IUSR_MachineName user has read-write access to C:\Windows\Temp\ before you start IIS.

8. If you have a policy configured, you can test your policy agent. For example, try to browse to a resource that your policy agent protects. You should be redirected to OpenAM to authenticate, for example as user demo, password changeit. After you authenticate, OpenAM then redirects you back to the resource you tried to access.