<?xml version="1.0" encoding="UTF-8"?>

<chapter xml:id='chap-msiis-6'

xmlns='http://docbook.org/ns/docbook'

version='5.0' xml:lang='en'

xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'

xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'

xmlns:xlink='http://www.w3.org/1999/xlink'

xmlns:xinclude='http://www.w3.org/2001/XInclude'>

<title>Installing the Microsoft IIS 6 Policy Agent</title>

<indexterm><primary>Microsoft IIS</primary></indexterm>

<para>This chapter covers installation of the policy agent for Microsoft

Internet Information Services 6.</para>

<section xml:id="before-iis6-agent-install">

<title>Before You Install</title>

<para>Make sure OpenAM is installed, running, that you can contact OpenAM

from the system running the policy agent. Next, create a profile for your

policy agent as described in the <citetitle>Administration Guide</citetitle>

section on <link xlink:href="admin-guide#create-agent-profiles"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Creating Agent

Profiles</citetitle></link>. To protect resources with the agent also create

at least one policy as described in the section on <link

xlink:href="admin-guide#configure-authz-policy"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Configuring

Policies</citetitle></link>. Consider creating a simple policy, such as a

policy that allows only authenticated users to access your resources, in order

to test your policy agent after installation.</para>

<para>You must install Microsoft IIS 6 before you install the policy agent,

and make sure that IIS 6 allows anonymous authentication. Make sure that IIS

6 listens on the URL used during the web policy agent installation, such as

<literal>http://win2003.example.com:80/</literal>. Furthermore, you

must reset IIS 6 after installing the policy agent.</para>

<para>>Go to <link xlink:href="install-guide#download-openam-software"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Obtaining OpenAM Software</citetitle></link>

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.</para>

<para>Unpack 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.</para>

<variablelist>

<para>When you unpack the policy agent you download, you find the following

directories under the <filename>web_agents\iis6_agent\</filename>

directory.</para>

<varlistentry>

<term><filename>bin</filename></term>

<listitem>

<para>Contains the configuration creation script,

<command>IIS6CreateConfig.vbs</command>; the agent administration and

installation script, <command>IIS6Admin.vbs</command>; the certificate

management tool <command>certutil.exe</command>; the password hashing tool

<command>cryptit.exe</command>; additional .dll and support files.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><filename>config</filename></term>

<listitem>

<para>Configuration templates used by the scripts during configuration

and installation</para>

</listitem>

</varlistentry>

</variablelist>

</section>

<section xml:id="install-iis6-web-agent">

<title>Installing IIS 6 Web Policy Agent</title>

<para>Complete the following procedures to install the policy agent.</para>

<procedure xml:id="create-iis6-agent-profile">

<title>To Create the IIS 6 Web Agent Profile</title>

<para>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.</para>

<step>

<para>In the OpenAM console, browse to Access Control &gt;

<replaceable>Realm Name</replaceable>&gt; Agents &gt; Web,

and then click the New... button in the Agent table.</para>

</step>

<step>

<para>Complete the web form using the following hints.</para>

<variablelist>

<varlistentry>

<term>Name</term>

<listitem>

<para>The name for the agent profile used when you install the

agent</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Password</term>

<listitem>

<para>Password the agent uses to authenticate to OpenAM</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Configuration</term>

<listitem>

<para>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.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Server URL</term>

<listitem>

<para>The full URL to an OpenAM instance, or if OpenAM is deployed in

a site configuration (behind a load balancer) then the site URL</para>

<para>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.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Agent URL</term>

<listitem>

<para>The web server URL that the agent protects</para>

<para>In centralized configuration mode, the Agent URL is used to

populate the Agent Profile for services such as notifications.</para>

</listitem>

</varlistentry>

</variablelist>

</step>

</procedure>

<procedure xml:id="create-iis6-agent-pwdfile">

<title>To Create the Password File</title>

<step>

<para>Protect the password file you will create as appropriate.</para>

</step>

<step>

<para>Create a text file containing only the password.</para>

<screen>C:\&gt;notepad C:\Windows\Temp\pwd.txt</screen>

</step>

</procedure>

<procedure xml:id="configure-iis6-agent-install">

<title>To Configure Policy Agent Installation</title>

<step>

<para>Log on as a user with Administrator privileges.</para>

</step>

<step>

<para>Change to the directory where you unpacked the agent download.</para>

<screen>C:\&gt;cd web_agents\iis6_agent\bin</screen>

</step>

<step>

<para>Create a configuration file using the

<command>IIS6CreateConfig.vbs</command> script.</para>

<note>

<para>The Web Site Identifier is the value of <literal>id</literal>,

not the site name.</para>

</note>

<screen>C:\web_agents\iis6_agent\bin&gt;cscript IIS6CreateConfig.vbs config.txt

...

Enter the Agent Resource File Name [IIS6Resource.en] :

Enter the Agent URL (Example: http://agent.example.com:80) :

<userinput>http://windows2003.example.com:80</userinput>

Displaying the list of Web Sites and its corresponding Identifiers

Site Name (Site Id)

Default Web Site (1)

Web Site Identifier :

<userinput>1</userinput>

...

Enter the URL where the OpenAM server is running...:

<userinput>http://openam.example.com:8080/openam</userinput>

Please enter the Agent Profile name :

<userinput>IIS 6 Web Agent</userinput>

Enter the Agent profile password file :

<userinput>C:\Windows\Temp\pwd.txt</userinput>

-----------------------------------------------------

Agent Configuration file created : config.txt

-----------------------------------------------------</screen>

</step>

</procedure>

<procedure xml:id="install-agent-into-iis6">

<title>To Install the Policy Agent into IIS 6</title>

<step>

<para>Log on as a user with Administrator privileges.</para>

</step>

<step>

<para>Make sure OpenAM is running.</para>

</step>

<step>

<para>Run <command>IIS6Admin.vbs</command> to install the agent.</para>

<screen>C:\web_agents\iis6_agent\bin&gt;cscript IIS6Admin.vbs -config config.txt

...

Enter the Agent Resource File Name [IIS6Resource.en] :

Creating the Agent Config Directory

Creating the <?eval ${agentsBootstrapFile}?> and

<?eval ${agentsConfigurationFile}?> File

Updating the Windows Product Registry

Loading the IIS 6.0 Agent

Completed Configuring the IIS 6.0 Agent</screen>

</step>

<step>

<para>Restart IIS 6.</para>

<screen>C:\web_agents\iis6_agent\bin&gt;iisreset

Attempting stop...

Internet services successfully stopped

Attempting start...

Internet services successfully restarted</screen>

<note>

<para>If the agent is in a different domain than the server, refer to <citetitle>Administration Guide</citetitle> procedure, <link

xlink:href="admin-guide#chap-cdsso"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Configuring Cross-Domain

Single Sign On</citetitle></link>.</para>

</note>

</step>

<step>

<para>Take note of the configuration files and log locations.</para>

<para>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

<filename>web_agents\iis6_agent\Identifier_1</filename>.

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.</para>

<variablelist>

<varlistentry>

<term><filename>config\<?eval ${agentsBootstrapFile}?></filename></term>

<listitem>

<para>Used to bootstrap the web policy agent, allowing the agent to

connect to OpenAM and download its configuration</para>

</listitem>

</varlistentry>

<varlistentry>

<term><filename>config\<?eval ${agentsConfigurationFile}?></filename></term>

<listitem>

<para>Only used if you configured the web policy agent to use local

configuration</para>

</listitem>

</varlistentry>

<varlistentry>

<term><filename>audit\</filename></term>

<listitem>

<para>Operational audit log directory, only used if remote logging

to OpenAM is disabled</para>

</listitem>

</varlistentry>

<varlistentry>

<term><filename>debug\</filename></term>

<listitem>

<para>Debug directory where the <filename>amAgent</filename> debug file

resides. Useful in troubleshooting policy agent issues.</para>

</listitem>

</varlistentry>

</variablelist>

</step>

<step>

<para>If your policy agent configuration is not in the top-level realm (/),

then you must edit config\<?eval ${agentsBootstrapFile}?> 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. </para>

</step>

<step>

<para>If the web policy agent performs naming URL validation, which you

can configure by setting the

<literal>com.forgerock.agents.ext.url.validation.level</literal> property

in <filename>config\OpenSSOAgentBootstrap.properties</filename>, then

make sure the <literal>IUSR_<replaceable>MachineName</replaceable></literal>

user has read-write access to <filename>C:\Windows\Temp\</filename> before

you start IIS.</para>

</step>

<step performance="optional">

<para>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

<literal>demo</literal>, password <literal>changeit</literal>. After

you authenticate, OpenAM then redirects you back to the resource you tried

to access.</para>

</step>

</procedure>

</section>

<section xml:id="custom-iis6-agent-installation">

<title>Custom IIS 6 Web Policy Agent Installation</title>

<para>When protecting multiple IIS 6 websites on the same host, use different

configuration files for each site.</para>

<para>When preparing a scripted, silent installation, notice that the

configuration file generated using <command>IIS6CreateConfig.vbs</command>

is a text file containing all of the configuration information in clear text

plus the encrypted password retrieved originally from the password

file. Encrypt passwords using <command>cryptit.exe</command>.</para>

<screen>C:\web_agents\iis6_agent\bin&gt;cryptit.exe <replaceable>pwd-file</replaceable> <replaceable>encryption-key</replaceable></screen>

</section>

<section xml:id="uninstall-iis6-agent">

<title>Remove IIS 6 Web Policy Agent Software</title>

<para>To remove the web policy agent, log on as a user with Administrator

privileges, run <command>cscript IIS6Admin.vbs -unconfig config.txt</command>,

and then run <command>iisreset</command>.</para>

</section>

</chapter>