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

Previous: Chapter 2 About Policy Agent 2.2 for Microsoft IIS 5.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 5.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 5.0. For information on supported platforms, see Supported Platforms and Compatibility of Agent for Microsoft IIS 5.0.

Note –

Only one instance of Microsoft IIS 5.0 can be installed per computer system. You cannot install multiple instances of Agent for Microsoft IIS 5.0 on the same computer system. For more information, see Information Specific to Agent for Microsoft IIS 5.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. 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 5.0.

This chapter contains the following sections:

Notice that two pre-installation sections exist in this document: the general pre-installation that applies to all scenarios and the more specific pre-installation that applies to situations where you want to prevent users from having to authenticate twice as described in Additional Authentication Prompt. If you want to prevent users from having to authenticate twice, then also follow the steps in Preventing an Additional Authentication Prompt: Preparing to Install Agent for Microsoft IIS 5.0.

All Scenarios: Preparing to Install Agent for Microsoft IIS 5.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 5.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 5.0 is supported on the desired platform as listed in Supported Platforms and Compatibility of Agent for Microsoft IIS 5.0.

Install Microsoft IIS 5.0 if not already installed.

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

Ensure that Microsoft IIS 5.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:

Ensure that the entry for the system on which the agent will be installed has a domain name set.

(Conditional) If the deployment container that hosts Access Manager is running on a separate system, ensure that it is also in the DNS query.

Next Steps

If you are interested in preventing users from authenticating a second time, then complete the tasks in the next section, Preventing an Additional Authentication Prompt: Preparing to Install Agent for Microsoft IIS 5.0. If you are not interested in completing the tasks in that section, skip toInstalling Agent for Microsoft IIS 5.0.

Preventing an Additional Authentication Prompt: Preparing to Install Agent for Microsoft IIS 5.0

As explained in Additional Authentication Prompt, Agent for Microsoft IIS 5.0 supports HTTP basic authentication.

However, when Policy Agent 2.2 for Microsoft IIS 5.0 is configured and basic authentication is enabled in the Microsoft IIS 5.0 server, users are required to authenticate twice. Users need to authenticate first with Access Manager and then with the Microsoft IIS 5.0 basic authentication module.

To prevent the user from being prompted a second time for user name and password, you must set the Basic Authentication filter, which is a feature of Agent for Microsoft IIS 5.0. Setting the Basic Authentication filter is a three part process. Notice that two steps of that process are described in this section as pre-installation tasks, as follows:

After you have performed the two tasks described in this section, install the agent. Then, as a post-installation step, you can perform the final task required to set the Basic Authentication filter, as described in Configuring Agent for Microsoft IIS 5.0 for Basic Authentication.

To Deploy the Post Authentication Module in Access Manager

Before You Begin

Synchronize the user name and password on the following two host machines, since such synchronization is required:

The machine that hosts Access Manager.
The machine that hosts Microsoft IIS 5.0 server.

Furthermore, the following information about Access Manager is helpful for this task:

AccessManager-base represents the Access Manager base installation directory.

The following are the default Access Manager base installation directories for Solaris systems and Windows systems:

Solaris Systems: /opt/SUNWam
Windows Systems: jes-install-dir\Access Manager\config

The following are the default locations of the AMConfig.properties file on Solaris systems and Windows systems:

Solaris Systems: /etc/opt/SUNWam/config
Windows Systems: AccessManager-base\config

Set the JAVA_HOME variable to the location used to install Java.

(Conditional) If the files DESGenKey.java and ReplayPasswd.java are not bundled with the Access Manager binaries (see the explanation within this step for details) obtain and compile them. Otherwise, skip to the next step.

The DESGenKey.java file is a key generator while the ReplayPasswd.java file is a plug-in.

The availability of DESGenKey.class and ReplayPasswd.class varies according to the Access Manager version. The following list indicates which versions of Access Manager have these classes bundled with them and which versions do not.
Bundled with
- Access Manager 7.0 series from Patch 5 forward
- Access Manager 7.1 series from Patch 1 forward
Not bundled with
- Any version of the Access Manager 7.0 series prior to patch 5
- Access Manager 7.1
You can obtain the files DESGenKey.java and ReplayPasswd.java by contacting Sun technical support.
1. Download the files DESGenKey.java and ReplayPasswd.java to the following directory:
```
AccessManager-base\lib
```
2. Change to the following directory:
```
AccessManager-base\lib
```
3. Compile ReplayPasswd.java and DESGenKey.java as follows
```
AccessManager-base\lib javac -classpath
AccessManager-base\lib\am_services.jar;AccessManager-base\lib\am_sdk.jar;AccessManager-base\lib\servlet.jar
ReplayPasswd.java DESGenKey.java
```

Execute DESgenKey.class as follows:

Access Manager 7.0 series from Patch 5 forward and Access Manager 7.1 series from Patch 1 forward

AccessManager-base\lib java com.sun.identity.common.DESGenKey

Any version of the Access Manager 7.0 series prior to patch 5 and Access Manager 7.1

AccessManager-base\lib java DESGenKey

Executing the DESgenKey.class returns a string output.

Add the string produced in the previous step to a newly created text file as described in the substeps that follow.
1. Copy the string produced in the previous step.
2. Create a file, which for this example is named des_key.txt, in a directory of your choosing.
  
  The des_key.txt name is used in this guide as an example. Name the file differently if you wish.
3. Save the copied string in the des_key.txt file.

Configure the com.sun.am.replaypasswd.key property in the AMConfig.properties configuration file as described in the substeps that follow.
1. Open the AMConfig.properties configuration file.
2. Add the following property to the file:
```
com.sun.am.replaypasswd.key
```
3. Copy the string from the des_key.txt file.
4. Add the copied string as the value of the com.sun.am.replaypasswd.key property.
  
  For example, if the string in the des_key.txt file is wuqUJyr=5Gc=, then the new property would be set as follows:
```
com.sun.am.replaypasswd.key = wuqUJyr=5Gc=
```
5. Save and close the AMConfig.properties configuration file.

Deploy the post-authentication plug-in, ReplayPasswd, as described in the substeps that follow.

This step requires the use of Access Manager Console.
1. Log in to Access Manager as amadmin.
2. With the Access Control tab selected, click the name of the realm you wish to configure.
3. Click the Authentication tab.
4. Click Advanced Properties.
  
  The Advanced Properties button is in the General section.
5. Scroll down to the Authentication Post Processing Classes field.
6. In the Authentication Post Processing Classes field, enter the appropriate text depending upon the Access Manager version:
  
  For Access Manager 7.0 series from Patch 5 forward and Access Manager 7.1 series from Patch 1 forward
  
  Enter the following: com.sun.identity.authentication.spi.ReplayPasswd
  
  For any version of the Access Manager 7.0 series prior to patch 5 and Access Manager 7.1
  
  Enter the following: ReplayPasswd
7. Scroll up to click Save.
8. Click Log Out to log out of the Access Manager Console.

Verify the deployment of the post-authentication plug-in, ReplayPasswd, as described in the substeps that follow.
1. Stop Access Manager.
2. Access the AMConfig.properties configuration file.
3. Note the value of the following property before changing it to message, as indicated:
```
com.iplanet.services.debug.level = message
```
  You must change this value back to its original value at the completion of this step.
4. Save and close the file.
5. Start Access Manager.
6. Log in to Access Manager Console.
  
  Again use amadmin.
7. Click Log Out to immediately log out of the Access Manager Console.
8. Change directories to the Access Manager debug log files.
  
  The default location of the debug log files is /var/opt/SUNWam/debug.
9. Verify the existence of a file named ReplayPasswd.
  
  The existence of this file indicates the successful deployment of the post-authentication plug-in.
10. Reset the debug value to its original value.

Restart Access Manager.

To Enable Basic Authentication in Microsoft IIS 5.0

This task is performed in Microsoft IIS 5.0 server.

Start the Internet Services Manager.

Right click the web site that is protected by the agent.

Select Properties from the drop-down list.

Select Directory Security.

Select Edit in Authentication and access control.

By default, “Enable anonymous access” is selected.

Uncheck the “Enable anonymous access” box.

Check the box Basic Authentication.

Click OK to save the changes.

Restart the web site.

Installing Agent for Microsoft IIS 5.0

The web agent installation program has one interface, the graphical user interface (GUI), for Windows systems. Use the following instructions to install Agent for Microsoft IIS 5.0.

Installation of Agent for Microsoft IIS 5.0

You must have administrator privileges to run the installation program.

To Install Agent for Microsoft IIS 5.0

Unpack the product binaries using Windows zip utility or Winzip utility.

Run the installation program by double-clicking setup.exe.

The Welcome page appears.

In the Welcome page, click Next.

Read the License Agreement. Click Yes to accept the license agreement.

Select the directory where you want to install the agent.

The default directory is C:\Sun\Access_Manager\Agents\2.2.

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

Enter the applicable information about the Microsoft IIS 5.0 instance where this agent will be installed in the dialog box.

The dialog box provides fields for entering the required information. You are prompted for information in the order shown as follows:

Web Server Host Name: Enter the fully qualified domain name (FQDN) of the system where the Microsoft IIS 5.0 instance 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 Server Instance Directory: Specify the Microsoft IIS 5.0 instance that this agent will protect. Enter the full path to the directory where the instance is located. For example: C:\inetpub\wwwroot.

Web Server Port: Enter the port number for the Microsoft IIS 5.0 instance that will be protected by the agent.

Web Server Protocol: If your Microsoft IIS 5.0 instance has been configured for SSL, then select HTTPS; otherwise select HTTP.

Web Agent Deployment URI: Enter a Universal Resource Identifier (URI) that will be used to access Agent for Microsoft IIS 5.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 and POST data preservation. Web agent URI prefix is a configurable subset of Web Agent Deployment URI. It is important to set a valid URL for this property. Its value should be http://host.domain:port/web-agent-deployment-uri where host, domain and port are FQDN and port number of the Microsoft IIS 5.0 instance where the agent is installed and web-agent-deployment-uri is the URI where the Microsoft IIS 5.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
```

When you have entered all the information, click Next.

Provide the following information about the Access Manager host:

The deployment container will connect to this server.

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 Port: Enter the port number for the primary Access Manager host.

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

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 the CDSSO feature.

After entering all the information, click Next.

Review the installation summary to ensure that the information you have entered is correct.

Note that it displays the CDCServlet URL if you have checked the CDSSO Enabled box in the previous panel.

If you want to make changes, click Back. If all the information is correct, click Next.

In the Ready to Install page, click Install Now.

When the installation is complete, you can click Details to view details about the installation, or click Close to end the installation program.

Restart the computer.

Restarting your computer is necessary for the agent to work properly. The installation modifies the system path by appending to it the location of the agent libraries. This change takes effect only after your computer is restarted.

Next Steps

To ensure that the installation was successful, see Verifying a Successful Installation on Policy Agent 2.2.

Verifying a Successful Installation on Policy Agent 2.2

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 C, Web Agent AMAgent.properties Configuration File.