Sun Java System Access Manager Policy Agent 2.2 Guide for Microsoft Internet Information Services 6.0

Previous: Chapter 2 About Policy Agent 2.2 for Microsoft IIS 6.0
Next: Chapter 4 The Relationship Between the Agent Profile and Web Agents in Policy Agent 2.2

Chapter 3 Installing Policy Agent 2.2 for Microsoft IIS 6.0

Policy Agent 2.2 works in tandem with Access Manager to control user access to deployment containers (such as web servers) in an enterprise.

This chapter explains how to install Policy Agent 2.2 for Microsoft IIS 6.0. For information on supported platforms, see Supported Platforms and Compatibility of Agent for Microsoft IIS 6.0.

Note –

Only one instance of Microsoft IIS 6.0 can be installed per computer system. You cannot install multiple instances of Agent for Microsoft IIS 6.0 on the same computer system. For more information, see Information Specific to Agent for Microsoft IIS 6.0.

This chapter leads you through the pre-installation, installation, and installation-related configuration steps. First, perform the pre-installation (preparation) steps. Then, perform the basic installation.

Next, perform the installation-related configuration, which is divided into two distinct phases. The first phase involves creating a configuration file while the second phase involves using this configuration file to configure Policy Agent 2.2 for Microsoft IIS 6.0.

If you want to protect Microsoft Office SharePoint or Outlook Web Access with the agent, additional information is required. See Appendix A, Microsoft Office SharePoint or Outlook Web Access: Deploying Agent for Microsoft IIS 6.0.

After you complete the configuration, verify that the installation was successful.

Next, complete the required post-installation tasks described in Chapter 5, Post-Installation Configuration: Policy Agent 2.2 for Microsoft IIS 6.0.

This chapter contains the following sections:

Preparing To Install Agent for Microsoft IIS 6.0

Follow the specific steps outlined in this section before you install the web agent to reduce the chance of complications occurring during and after the installation.

To Prepare To Install Agent for Microsoft IIS 6.0

Note –

You must have Java Runtime Environment (JRE) 1.3.1 or higher installed or available on a shared file system in order to run the graphical user interface (GUI) of the web agent installation program. Currently, JRE 1.3.1 or any version higher is certified for use with the web agent installation program.

Perform the following pre-installation tasks:

Ensure that Policy Agent 2.2 for Microsoft IIS 6.0 is supported on the desired platform as listed in Supported Platforms and Compatibility of Agent for Microsoft IIS 6.0.

Install Microsoft IIS 6.0 if not already installed.

Refer to the Microsoft IIS 6.0 documentation for details on how best to install and configure this server for your platform.

Ensure that Microsoft IIS 6.0 has the latest patches available.

Set your JAVA_HOME environment variable to a JDK version 1.3.1_04 or higher.

The installation requires that you set up your JAVA_HOME variable correctly. However, if you have incorrectly set the JAVA_HOME variable, the setup script will prompt you for supplying the correct JAVA_HOME value:

Please enter JAVA_HOME path to pick up java:

Next Steps

To install Agent for Microsoft IIS 6.0 to protect Microsoft Office SharePoint or Outlook Web Access you must perform additional pre-installation steps. See Microsoft Office SharePoint and Outlook Web Access: Preparing to Install the Agent.

Installing Agent for Microsoft IIS 6.0

The installation program that installs Agent for Microsoft IIS 6.0 has one interface, a graphical user interface (GUI).

The installation performed by this installer is extremely basic. The installer performs the following:

Provides the license agreement
Distributes the agent files

Therefore, during the installation, you are not prompted for information about the Microsoft IIS 6.0 host or the Access Manager host, though this type of information is often prompted by installers. Instead, for this agent, such information is prompted as part of the configuration process described in Installation-Related Configuration for Microsoft IIS 6.0.

To Install Agent for Microsoft IIS 6.0

This task applies to all deployments of Agent for Microsoft IIS 6.0, including deployments where the agent protects Microsoft Office SharePoint or Outlook Web Access.

You must have administrator privileges to run the installation program.

Unzip the product binaries.
unzip binaryname.zip
Note –
On Microsoft Windows 2003, the zip file is not automatically unpacked. Therefore, after you download the agents zip file, be sure to extract the zip file to a directory first and then execute setup.exe. To extract the zip file, right click on the zip file in the File Manager and select Extract. After extracting to a directory, double click setup.exe to execute it.

Double-click setup.exe to run the installation program.

In the Welcome window, click Next.

Read the License Agreement and click Yes to accept it.

Select the directory in which you want to install the agent.

The default directory is C:\Sun\Access_Manager\Agents\2.2. The installation program will install the agent in this directory.

The directory in which you install the web agent is referred to as the Policy Agent base directory, or PolicyAgent-base.

(Conditional) Click Create Directory if this option is available.

If the directory does not exist, a dialog box appears giving you the option to create a directory.

Click Install Now.

The program installs the agent.

Click Yes when the program asks if you want to reboot the computer.

Once the installation is complete, you must create agent configuration files to configure the agent for web sites. The following section explains the procedure for creating the agent configuration file.

Installation-Related Configuration for Microsoft IIS 6.0

After you have performed the basic installation process, you must create a configuration file for the web site (or web sites) that is to be protected by the agent and then you must configure the agent for that web site (or web sites). These tasks are described in the following subsections:

Note –

After you create the configuration files, the task that you implement next varies depending on your deployment. At that time, if you are installing Agent for Microsoft IIS 6.0 to protect Microsoft Office SharePoint or Outlook Web Access, you will skip to Microsoft Office SharePoint and Outlook Web Access: Configuring the Agent. For all other deployments, you will continue directly onto the next task (Configuring Agent for Microsoft IIS 6.0 for a Web Site).

Creating Configuration Files: Agent for Microsoft IIS 6.0

The agent for Microsoft IIS 6.0 provides a Visual Basic (VB) script to help you create agent configuration files. When you run it, the VB script prompts for information related to the Web Site Identifier, the agent you are installing, and Access Manager. The script creates an agent configuration file based on the information you provide.

Note –

When you are deploying the agent on multiple web sites, you must create a unique agent configuration file for each of the web sites. Use the following steps to create multiple agent configuration files. However, ensure that you give a unique file name to each of the configuration files.

To Create Configuration Files: Agent for Microsoft IIS 6.0

This task applies to all deployments of Agent for Microsoft IIS 6.0, including deployments where the agent protects Microsoft Office SharePoint or Outlook Web Access.

Change to the directory:
```
PolicyAgent-base\iis6\bin
```
This directory stores the VB script required to create the agent configuration file

Issue the following command (be aware that the command is case sensitive):

cscript.exe IIS6CreateConfig.vbs defaultConfig

IIS6CreateConfig.vbs

is a VB script that saves your responses to prompts about the Microsoft IIS 6.0 host and the Access Manager host in a file. For this example, the file is represented by defaultConfig.

defaultConfig

represents the agent configuration file created by this command and for which you provide the actual name. This is a text file to which the output of the commands entered while running the script are written.

Note –

Give a unique name for this agent configuration file since you will need the same file to unconfigure the agent.

The script prompts for information as it progresses with the creation of the agent configuration file. All the script prompts are displayed in this step. However, information about the responses are presented in the subsequent steps.

Microsoft (R) Windows Script Host Version 5.6
Copyright (C) Microsoft Corporation 1996-2001. All rights reserved.

Copyright c 2004 Sun Microsystems, Inc. All rights reserved
Use is subject to license terms
---------------------------------------------------------
    Microsoft (TM) Internet Information Server (6.0)
---------------------------------------------------------
Enter the Agent Resource File Name [IIS6Resource.en] :

Fully Qualified Host Name :
host1.subexample.example.com

Displaying the list of Web Sites and its corresponding Identifiers
Site Name (Site Id)
Default Web Site (1)
Site A (1701188044)
SharePoint Central Administration (2)

Web Site Identifier :
1

Agent Protocol [http] :

Agent Port Number [80] :

Agent Deployment URI [/amagent] :

------------------------------------------------
Sun Java (TM) Enterprise System Access Manager
------------------------------------------------
Primary Server Host :
host2.subexample.example.com

Primary Server Protocol [http] :

Primary Server Port Number [58080] :

Primary Server Deployment URI [/amserver] :

Primary Server Console URI [/amconsole] :

Failover Server Host :
Agent-Access Manager Shared Secret :

Re-enter Shared Secret :

CDSSO Enabled [false] :

-----------------------------------------------------
Agent Configuration file created ==>  defaultConfig
-----------------------------------------------------

When prompted, provide the following information about the Microsoft IIS 6.0 instance that this agent will protect:

Agent Resource File Name: Accept the default for this prompt (IIS6Resource.en).

Host Name: Enter the fully qualified domain name (FQDN) of the system on which Microsoft IIS 6.0 is installed.

For example, if the host is host1, the subdomain is eng, and the domain is example.com, then the Host Name in this case is host1.eng.example.com.

Web Site Identifier: Enter the Web Site Identifier for the specific web site for which you are creating a configuration file. Microsoft IIS 6.0 has a unique identifier associated with every web site on the web server. The Web Site Identifier is displayed when you start Microsoft Internet Information Services Manager and click Web Sites. The Identifier column indicates the unique identifier associated with every web site.

Server Protocol: If this instance of Microsoft IIS 6.0 has been configured for SSL, then select HTTPS; otherwise select HTTP.

Server Port: Enter the port number of the Microsoft IIS 6.0 instance that will be protected by the agent.

Agent Deployment URI: Enter a Universal Resource Identifier (URI) that will be used to access Agent for Microsoft IIS 6.0. The default value is /amagent.

Note –
The web agent uses the value of the com.sun.am.policy.agents.config.agenturi.prefix property in the web agent AMAgent.properties configuration file to support some essential functions such as notification. Agent URI prefix is a configurable subset of Agent Deployment URI. It is important to set a valid URL for this property. Its value should be http://host.domain:port/agent-deployment-uri where host, domain and port are FQDN and port number of the Microsoft IIS 6.0 instance where the agent is installed and agent-deployment-uri is the URI where the Microsoft IIS 6.0 instance will look for web-agent related HTML pages. Its default value is amagent.

The following is an example of an Agent Deployment URI:
```
http://host1.example.com:80/amagent
```
where the host name is host1 and the domain name is example.com.

When prompted, provide the following information about the Access Manager host:

Primary Server Host: Enter the FQDN of the primary Access Manager host.

For example, if the host is host3, the subdomain is eng, and the domain is example.com, then the Host Name in this case is host3.eng.example.com.

Primary Server Protocol: If the primary Access Manager host is SSL-enabled, select HTTPS. Otherwise select HTTP.

Primary Server Port: Enter the port number for the primary Access Manager host.

Primary Server Deployment URI: Enter the location that was specified when Access Manager was installed. The default URI for Access Manager is /amserver.

Primary Console Deployment URI: Enter the location that was specified when Access Manager Console was installed. The default URI for Access Manager is /amconsole.

Failover Server Host: Enter the FQDN of the secondary Access Manager host if the primary Access Manager host becomes unavailable. If no failover server host exists, then leave this field blank.

Failover Server Port: Enter the port number of the secondary Access Manager host. If no failover server host exists, then leave this field blank.

Failover Server Protocol: If the failover Access Manager host is SSL-enabled, select HTTPS. Otherwise select HTTP. If no failover server host exists, then leave this field blank.

Failover Server Deployment URI: Enter the location that was specified when Access Manager was installed. The default URI for Access Manager is /amserver. If no failover server host exists, then leave this field blank.

Failover Console Deployment URI: Enter the location that was specified when Access Manager Console was installed. The default URI for Access Manager is /amconsole. If no failover server host exists, then leave this field blank.

Agent Access Manager Shared Secret: Enter the password for the Access Manager internal LDAP authentication user. This user is also referred to as amldapuser.

For more information about the shared secret and its relationship with the Access Manager agent profile, see Chapter 4, The Relationship Between the Agent Profile and Web Agents in Policy Agent 2.2.

Re-enter Shared Secret: Re-enter the password for the Access Manager internal LDAP authentication user (amldapuser).

CDSSO Enabled: Check this box if you want to enable CDSSO.

With the information you provide, the script creates the agent configuration file for you to use to configure this agent as described in the following section.

Next Steps

At this point, the next task to be implemented varies depending on your deployment. If you are installing Agent for Microsoft IIS 6.0 to protect Microsoft Office SharePoint or Outlook Web Access, skip to Microsoft Office SharePoint and Outlook Web Access: Configuring the Agent. For all other deployments, continue with the task that follows (Configuring Agent for Microsoft IIS 6.0 for a Web Site).

Configuring Agent for Microsoft IIS 6.0 for a Web Site

Caution –

Do not perform the task described in this section if you are installing Agent for Microsoft IIS 6.0 to protect Microsoft Office SharePoint or Outlook Web Access. Instead continue the configuration process by implementing the steps in Microsoft Office SharePoint and Outlook Web Access: Configuring the Agent. For all other deployments, continue with this task.

Configure Agent for Microsoft IIS 6.0 for a web site after you have created an agent configuration file. If you have not already created an agent configuration file, create one as explained in Creating Configuration Files: Agent for Microsoft IIS 6.0.

Note –

If you want to configure the agent for multiple web sites, you must create a separate agent configuration file for each web site.

To configure the agent for a web site, follow these steps:

To Configure Agent for Microsoft IIS 6.0 for a Web Site

Change to the directory:
```
PolicyAgent-base\iis6\bin
```

Issue the following command (be aware that the command is case sensitive):

cscript.exe IIS6admin.vbs -config defaultConfig

IIS6admin.vbs: is a VB script that uses the output of the IIS6CreateConfig.vbs script. The output was saved to a configuration file, which for this example is represented by defaultConfig.
-config: is the option that allows the output to be used to configure the web site to use Agent for Microsoft IIS 6.0.
defaultConfig: represents the agent configuration file created previously as described in To Create Configuration Files: Agent for Microsoft IIS 6.0.

The script displays messages to indicate the progress of the configuration as shown in the following sample.

Microsoft (R) Windows Script Host Version 5.6
    Copyright (C) Microsoft Corporation 1996-2001. All rights reserved.

    Copyright c 2004 Sun Microsystems, Inc. All rights reserved
    Use is subject to license terms

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

    Creating the Agent Config Directory
    Creating the AMAgent.properties File
    Updating the Windows Product Registry
    Loading the IIS 6.0 Agent
    Completed Configuring the IIS 6.0 Agent

Ensure that the authentication method of Microsoft IIS 6.0 Server is set to Anonymous.

Restart the application pool to which the web site belongs.

Restart the web site.

Try accessing the web site (http://fqdn:port/index.html).

This link should take you to the Access Manager login page. After a successful authentication, if the policy is properly defined, you should be able to view the resource.

If you want to view the agent log file amAgent, do so at the following location:
PolicyAgent-base\debug\Identifier_site-identifier
where site-identifier is a number, such as 1, that represents the identifier of the web site for which the agent is being configured.

Note –
If you want to configure the agent for multiple web sites, you must follow the above steps for each of the web sites.

Next Steps

The last step of this task addresses verification of the agent installation. See, the section that follows (Verifying a Successful Installation of Policy Agent 2.2) for an expanded explanation on verifying the agent installation.

Verifying a Successful Installation of Policy Agent 2.2

Note –

The task presented in this section about verifying the agent installation does not apply to deployments where the agent protects Microsoft Office SharePoint or Outlook Web Access. To verify agent installation for those types of installations, see Microsoft Office SharePoint and Outlook Web Access: Verifying a Successful Agent Installation.

After installing a web agent, ensure that the agent is installed successfully. Two methods are available for verifying a successful web agent installation. Perform both for best results.

To Verify a Successful Installation

Attempt to access a resource on the deployment container where the agent is installed.

If the web agent is installed correctly, accessing any resource should take you to the Access Manager login page. After a successful authentication, if the policy is properly defined, you should be able to view the resource.

Check the web agent AMAgent.properties configuration file.

Make sure that each property is set properly. For information on the properties in this file, see Appendix D, Web Agent AMAgent.properties Configuration File.