This chapter covers installation of the policy agent for Microsoft Internet Information Services 7.
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 Administration Guide section on Creating Agent Profiles. To protect resources with the agent also create at least one policy 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, in order to test your policy agent after installation.
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
http://windows7.example.com:80/. Furthermore, you
must reset IIS 7 after installing the policy agent.
Go to 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.
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.
When you unpack the policy agent you download, you find the following
directories under the web_agents\iis7_agent\
directory.
binContains the configuration creation script, IIS7CreateConfig.vbs; the agent administration and installation script, IIS7Admin.vbs; the certificate management tool certutil.exe; the password hashing tool cryptit.exe; additional .dll and support files.
configConfiguration templates used by the scripts during configuration and installation
Complete the following procedures to install the 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.
In the OpenAM console, browse to Access Control >
Realm Name> Agents > Web,
and then click the New... button in the Agent table.
Complete the web form using the following hints.
The name for the agent profile used when you install the agent
Password the agent uses to authenticate to OpenAM
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.
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.
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.
Protect the password file you will create as appropriate.
Create a text file containing only the password.
C:\>notepad C:\Windows\Temp\pwd.txt
Log on as a user with Administrator privileges.
Change to the directory where you unpacked the agent download.
C:\>cd web_agents\iis7_agent\bin
Create a configuration file using the IIS7CreateConfig.vbs script.
The Web Site Identifier is the value of id,
not the site name.
C:\web_agents\iis7_agent\bin>cscript IIS7CreateConfig.vbs config.txt ... Enter the Agent Resource File Name [IIS7Resource.en] : Enter the Agent URL (Example: http://agent.example.com:80) : http://windows7.example.com:80 Displaying the list of Web Sites and its corresponding Identifiers (id) SITE "Default Web Site" (id:1,bindings:http/*:80:,state:Started) 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 7 Web Agent Enter the Agent profile password file : C:\Windows\Temp\pwd.txt ----------------------------------------------------- Agent Configuration file created : config.txt -----------------------------------------------------
Log on as a user with Administrator privileges.
Make sure OpenAM is running.
Run IIS7Admin.vbs to install the agent.
C:\web_agents\iis7_agent\bin>cscript IIS7Admin.vbs -config config.txt ... Enter the Agent Resource File Name [IIS7Resource.en] : Creating the Agent Config Directory Creating the and 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
Make sure the authentication method for IIS 7 is set to anonymous.
Restart IIS 7.
C:\web_agents\iis7_agent\bin>iisreset Attempting stop... Internet services successfully stopped Attempting start... Internet services successfully restarted
If the agent is in a different domain than the server, refer to Administration Guide procedure, Configuring Cross-Domain Single Sign On.
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 (id: 1) shown in the examples above has configuration and logs located
under the directory
web_agents\iis7_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.
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.
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.
When protecting multiple IIS 7 websites on the same host, use different configuration files for each site.
When preparing a scripted, silent installation, notice that the configuration file generated using IIS7CreateConfig.vbs 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 cryptit.exe.
C:\web_agents\iis7_agent\bin>cryptit.exe pwd-file encryption-key
The IIS 7 web policy agent now supports IIS 7 basic authentication and password replay. You must use the appropriate software versions.
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.
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.
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.
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.
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.
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.
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.
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.
Follow these steps.
Generate and store an encryption key.
Generate the key using
com.sun.identity.common.DESGenKey using the .jars
where you deployed OpenAM, as in the following example.
$ cd /path/to/tomcat/webapps/openam/WEB-INF/lib $ java -cp openam-core-.jar:openam-shared-.jar com.sun.identity.common.DESGenKey Key ==> sxVoaDRAN0o=
Store the key in the agent configuration on the property in the
OpenAM console under Access Control >
realm-name > Agents > Web >
agent-name > Advanced > Microsoft IIS
Server > Replay Password Key (property name:
com.sun.identity.agents.config.replaypasswd.key),
and then Save your work.
Store the key in the server configuration in the OpenAM console
under Configuration > Servers and Sites >
server-name > Advanced > Add... to add
the property com.sun.am.replaypasswd.key with the
key you generated as the value, and then Save your work.
In the OpenAM console under Access Control >
realm-name > Authentication > All Core
Settings... > Authentication Post Processing Classes, add the class
com.sun.identity.authentication.spi.ReplayPasswd,
and then Save your work.
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.
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 Access Control >
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.
To set the encrypted password in the AUTH_PASSWORD header, in the
OpenAM console under Access Control >
realm-name > Agents > Web >
agent-name > Advanced > Custom Properties,
add com.sun.identity.agents.config.iis.password.header=true.
To have the agent perform Windows logon (for user token
impersonation), in the OpenAM console under Access Control >
realm-name > Agents > Web >
agent-name > Advanced > Custom Properties,
add com.sun.identity.agents.config.iis.logonuser=true.
In the OpenAM console under Access Control >
realm-name > Agents > Web >
agent-name > Advanced > Microsoft IIS
Server, set Authentication Type to basic, and then Save your work.
To use the agent with SharePoint or Microsoft Office, configure
OpenAM to support the iPlanetDirectoryPro as a persistent
cookie.
In the OpenAM console under Access Control >
realm-name > Authentication > All Core
Settings... > Persistent Cookie Mode, select Enabled, and then Save
your work.