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

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

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 7 Policy Agent</title>

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

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

Internet Information Services 7.</para>

<section xml:id="before-iis7-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 7 before you install the policy agent,

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

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

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

must reset IIS 7 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\iis7_agent\</filename>

directory.</para>

<varlistentry>

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

<listitem>

<para>Contains the configuration creation script,

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

installation script, <command>IIS7Admin.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-iis7-web-agent">

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

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

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

<title>To Create the IIS 7 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-iis7-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-iis7-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\iis7_agent\bin</screen>

</step>

<step>

<para>Create a configuration file using the

<command>IIS7CreateConfig.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\iis7_agent\bin&gt;cscript IIS7CreateConfig.vbs config.txt

...

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

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

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

Displaying the list of Web Sites and its corresponding Identifiers (id)

SITE "Default Web Site" (<emphasis role="strong">id:1</emphasis>,bindings:http/*:80:,state:Started)

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 7 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-iis7">

<title>To Install the Policy Agent into IIS 7</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>IIS7Admin.vbs</command> to install the agent.</para>

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

...

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

Creating the Agent Config Directory

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

<?eval ${agentsConfigurationFile}?> File

Updating the Windows Product Registry

Installing policy web agent module in IIS (status: 0)

Adding policy web agent module to "Default Web Site" (status: 0)

Completed Configuring the IIS 7.0 Agent</screen>

</step>

<step>

<para>Make sure the authentication method for IIS 7 is set to

anonymous.</para>

</step>

<step>

<para>Restart IIS 7.</para>

<screen>C:\web_agents\iis7_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 (id: 1) shown in the examples above has configuration and logs located

under the directory

<filename>web_agents\iis7_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 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-iis7-agent-installation">

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

<para>When protecting multiple IIS 7 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>IIS7CreateConfig.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\iis7_agent\bin&gt;cryptit.exe <replaceable>pwd-file</replaceable> <replaceable>encryption-key</replaceable></screen>

</section>

<!-- OPENAM-1644: Document changes to IIS 7 PA support for Basic Auth and password replay -->

<section xml:id="iis7-enable-basic-auth">

<title>Enable IIS 7 Basic Authentication &amp; Password Replay Support</title>

<itemizedlist>

<para>The IIS 7 web policy agent now supports IIS 7 basic authentication and

password replay. You must use the appropriate software versions.</para>

<listitem>

<para>For Microsoft Office integration, you must use Microsoft Office 2007

SP2 or later.</para>

</listitem>

<listitem>

<para>For Microsoft SharePoint integration, you must use Microsoft

SharePoint Server 2007 SP2 or later.</para>

</listitem>

</itemizedlist>

<variablelist>

<para>You must also apply workarounds as described for the following

Microsoft issues.</para>

<varlistentry>

<term>Microsoft Support Issue: 841215</term>

<listitem>

<para>Link: <link xlink:show="new"

xlink:href="http://support.microsoft.com/kb/841215"

>http://support.microsoft.com/kb/841215</link></para>

<para>Description: Error message when you try to connect to a Windows

SharePoint document library: "System error 5 has occurred"</para>

<para>Summary: Enable Basic Authentication on the client computer.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Microsoft Support Issue: 870853</term>

<listitem>

<para>Link: <link xlink:show="new"

xlink:href="http://support.microsoft.com/kb/870853"

>http://support.microsoft.com/kb/870853</link></para>

<para>Description: Office 2003 and 2007 Office documents open read-only

in Internet Explorer</para>

<para>Summary: Add registry keys as described in Microsoft's support

document.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Microsoft Support Issue: 928692</term>

<listitem>

<para>Link: <link xlink:show="new"

xlink:href="http://support.microsoft.com/kb/928692"

>http://support.microsoft.com/kb/928692</link></para>

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

<para>Summary: Edit the registry as described in Microsoft's support

document.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Microsoft Support Issue: 932118</term>

<listitem>

<para>Link: <link xlink:show="new"

xlink:href="http://support.microsoft.com/kb/932118"

>http://support.microsoft.com/kb/932118</link></para>

<para>Description: Persistent cookies are not shared between Internet

Explorer and Office applications</para>

<para>Summary: Add the web site the list of trusted sites.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Microsoft Support Issue: 943280</term>

<listitem>

<para>Link: <link xlink:show="new"

xlink:href="http://support.microsoft.com/kb/943280"

>http://support.microsoft.com/kb/943280</link></para>

<para>Description: Prompt for Credentials When Accessing FQDN Sites From a

Windows Vista or Windows 7 Computer</para>

<para>Summary: Edit the registry as described in Microsoft's support

document.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Microsoft Support Issue: 968851</term>

<listitem>

<para>Link: <link xlink:show="new"

xlink:href="http://support.microsoft.com/kb/968851"

>http://support.microsoft.com/kb/968851</link></para>

<para>Description: SharePoint Server 2007 Cumulative Update Server

Hotfix Package (MOSS server-package): April 30, 2009</para>

<para>Summary: Apply the fix from Microsoft if you use SharePoint.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Microsoft Support Issue: 2123563</term>

<listitem>

<para>Link: <link xlink:show="new"

xlink:href="http://support.microsoft.com/kb/2123563"

>http://support.microsoft.com/kb/2123563</link></para>

<para>Description: You cannot open Office file types directly from a

server that supports only Basic authentication over a non-SSL

connection</para>

<para>Summary: Enable SSL encryption on the web server.</para>

</listitem>

</varlistentry>

</variablelist>

<procedure xml:id="configure-ii7-basic-auth">

<title>To Configure IIS 7 Basic Authentication &amp; Password Replay Support</title>

<para>Follow these steps.</para>

<step>

<para>Generate and store an encryption key.</para>

<substeps>

<step>

<para>Generate the key using

<literal>com.sun.identity.common.DESGenKey</literal> using the .jars

where you deployed OpenAM, as in the following example.</para>

<screen>$ cd /path/to/tomcat/webapps/openam/WEB-INF/lib

$ java -cp openam-core-<?eval ${serverDocTargetVersion}?>.jar:openam-shared-<?eval ${serverDocTargetVersion}?>.jar

com.sun.identity.common.DESGenKey

Key ==> sxVoaDRAN0o=</screen>

</step>

<step>

<para>Store the key in the agent configuration on the property in the

OpenAM console under Access Control &gt;

<replaceable>realm-name</replaceable> &gt; Agents &gt; Web &gt;

<replaceable>agent-name</replaceable> &gt; Advanced &gt; Microsoft IIS

Server &gt; Replay Password Key (property name:

<literal>com.sun.identity.agents.config.replaypasswd.key</literal>),

and then Save your work.</para>

</step>

<step>

<para>Store the key in the server configuration in the OpenAM console

under Configuration &gt; Servers and Sites &gt;

<replaceable>server-name</replaceable> &gt; Advanced &gt; Add... to add

the property <literal>com.sun.am.replaypasswd.key</literal> with the

key you generated as the value, and then Save your work.</para>

</step>

</substeps>

</step>

<step>

<para>In the OpenAM console under Access Control &gt;

<replaceable>realm-name</replaceable> &gt; Authentication &gt; All Core

Settings... &gt; Authentication Post Processing Classes, add the class

<literal>com.sun.identity.authentication.spi.ReplayPasswd</literal>,

and then Save your work.</para>

</step>

<step>

<para>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 date store, and you must configure the IIS 7 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.</para>

<para>Skip this step if you do not use SharePoint or OWA and no Windows

logon is required.</para>

<para>Make sure OpenAM data store is configured to use Active Directory as

the user data store.</para>

<para>In the OpenAM console under Access Control &gt;

<replaceable>realm-name</replaceable> &gt; Agents &gt; Web &gt;

<replaceable>agent-name</replaceable> &gt; OpenAM Services &gt; 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 <literal>samaccountname</literal>

attribute, then set the User ID Parameter to

<literal>samaccountname</literal>, and the User ID Parameter Type to

<literal>LDAP</literal>.</para>

<para>Setting the User ID Parameter Type to <literal>LDAP</literal> 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

<literal>remote_user</literal>, <literal>auth_user</literal>, or

<literal>logon_user</literal> and <literal>user_password</literal> with

Active Directory attribute values suitable for Windows logon, setting the

remote user, and so forth.</para>

</step>

<step>

<para>To set the encrypted password in the AUTH_PASSWORD header, in the

OpenAM console under Access Control &gt;

<replaceable>realm-name</replaceable> &gt; Agents &gt; Web &gt;

<replaceable>agent-name</replaceable> &gt; Advanced &gt; Custom Properties,

add <literal>com.sun.identity.agents.config.iis.password.header=true</literal>.</para>

</step>

<step>

<para>To have the agent perform Windows logon (for user token

impersonation), in the OpenAM console under Access Control &gt;

<replaceable>realm-name</replaceable> &gt; Agents &gt; Web &gt;

<replaceable>agent-name</replaceable> &gt; Advanced &gt; Custom Properties,

add <literal>com.sun.identity.agents.config.iis.logonuser=true</literal>.</para>

</step>

<step>

<para>In the OpenAM console under Access Control &gt;

<replaceable>realm-name</replaceable> &gt; Agents &gt; Web &gt;

<replaceable>agent-name</replaceable> &gt; Advanced &gt; Microsoft IIS

Server, set Authentication Type to basic, and then Save your work.</para>

</step>

<step>

<para>To use the agent with SharePoint or Microsoft Office, configure

OpenAM to support the <literal>iPlanetDirectoryPro</literal> as a persistent

cookie.</para>

<para>In the OpenAM console under Access Control &gt;

<replaceable>realm-name</replaceable> &gt; Authentication &gt; All Core

Settings... &gt; Persistent Cookie Mode, select Enabled, and then Save

your work.</para>

</step>

</procedure>

</section>

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

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

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

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

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

</section>

</chapter>