![]() |
Sun ONE Identity Server Policy Agent Pack Guide |
Chapter 3 Policy Agent Pack 1.1 on Windows 2000
Sun ONE Identity Server Policy Agents work in tandem with Sun ONE Identity Server (also referred as DSAME) to grant or deny user access to web servers in an enterprise. The Policy Agent Pack 1.1 provides a set of policy agents for use with various web and proxy servers. This chapter explains how to install and configure the policy agents for servers running on the Windows 2000 operating system.
Before You Begin
Using the Graphical User Interface (GUI) Version of the Installation Program
Using the Command-Line Version of the Installation Program
Using Secure Sockets Layer (SSL) with an Agent
Setting the REMOTE_USER Server Variable
Forwarding LDAP User Attributes via HTTP Headers
Before You Begin
Be sure that your are familiar with the concepts presented in Chapter 1 "Read This First." The chapter includes brief but important information on the following topics:
How Policy Agents Work
Java Runtime Environment (JRE) 1.3.1_04 Requirement
The Web Server that Runs Identity Server Services vs. Remote Web Servers
Installing Multiple Web Server Agents on the Same Computer System
Supported Windows Web Servers
The Agent Pack supports the following web servers on the Windows 2000 Server operating system:
Using the Graphical User Interface (GUI) Version of the Installation Program
Use the GUI version of the Installation program to install one agent at a time.
Installing the Policy Agent for Microsoft IIS
The IIS agent enforces policy on URL access for Microsoft's Internet Information Services (IIS) web server. The agent is an IIS ISAPI filter installed at the IIS web service level that will enforce policy on all IIS web sites. Technical considerations prevent the agent from being installed at the web site level.
Prior to installation, be sure that the entry for the system where the agent will be installed has a domain name set. If the web server that runs DSAME services is running on a separate system, make sure the server is also in the DNS query list.
To Install the Policy Agent on Microsoft IIS
You must have administrator privileges to run the installation program.
Unzip the product binaries file.
Run the Installation program by double-clicking setup.exe.
In the Welcome window, click Next.
Read the License Agreement. Click Yes to accept the license agreement.
Select the directory where you would like to install the agent by clicking Browse, or click Next to accept the default.
Select the component "DSAME Agent for IIS" and click Next.
Note Only one component can be installed at a time.
Enter the information about the web server where this agent will be installed:
Host Name: Enter the fully qualified domain name of the system where the agent web server is installed. For example, mycomputer.siroe.com.
Web Server Document Root: Enter the document root directory. This directory needs to accessible by the web server root w3svc.
Web Server Port: Enter the port number for the web server that will be protected by the agent.
Web Server Protocol: If your web server has been configured for SSL, then select HTTPS; otherwise select HTTP.
Agent Deployment URI: Enter a directory name. The default Universal Resource Identifier (URI) is /amagent.
The URI prefix tells the web server where to look for HTML pages that need to be displayed. For example, when a user attempts to access a URL, but cannot provide proper credentials, the agent must display an "Access denied" message. The URI prefix tells the web server where to look for the HTML page that contains the message. A directory specified by this URI will be created in the web server Document Root.
When all the information is entered correctly, click Next.
Provide the following information about the web server that runs DSAME services:
DSAME Services Host: Enter the fully qualified domain name of the system where the primary web server that runs DSAME services is installed. For example, myserver.siroe.com.
DSAME Services Port: Enter the port number for the primary web server that runs DSAME services.
DSAME Services Protocol: If the web server that runs DSAME services has been configured for SSL, then select HTTPS; otherwise select HTTP.
DSAME Services Deployment URI: Enter the location that was specified when DSAME was installed. The default Universal Resource Identifier (URI) for DSAME is /amserver.
Failover Server Host: Enter the fully qualified domain name for the secondary web server that will run DSAME services if the primary server becomes unavailable. If no failover server exists, then leave this field blank.
Failover Server Port: Enter the port number of the secondary web server that will run DSAME services if the primary server becomes unavailable. If no failover server exists, then leave this field blank.
If all the information entered is correct click Next.
Review your selections in the Summary panel and click Install Now.
When the installation is complete you may review the details, and then click Exit.
The installation modifies the system path by appending to it the location of the Agent libraries. In order for the change to take effect and for the Agent to work properly, you must reboot your computer. If you would like to reboot your computer immediately click Reboot Now in the popup window.
Note If the IIS 5.0 agent was previously installed and uninstalled on your machine, you do not need to reboot if you are installing the same IIS 5.0 agent in the same directory.
Installing the Policy Agent for iPlanet Web Server
You must have administrator privileges to run the Installation program.
To Install the Policy Agent on iPlanet Web Server
Unzip the product binaries file.
Run the Installation program by double-clicking setup.exe.
In the Welcome window, click Next.
Read the License Agreement. Click Yes to agree to the license terms.
Select the directory where you would like to install the agent by clicking Browse, or click Next to accept the default.
Select the component "DSAME Agent for iWS 6.0" and click Next.
Note Only one component can be installed at a time.
Provide the following information about the web server where this agent will be installed:
Host Name: Enter the fully qualified domain name of the system where the agent web server is installed. For example, mycomputer.siroe.com.
iPlanet Web Server Instance Directory: Enter the full path to the directory where the iPlanet Web Server instance is located. This is the web server instance that the agent will protect. For example, /Web_Server_root/https-mycomputer.siroe.com.
Web Server Port: Enter the port number for the web server that will be protected by the agent.
Web Server Protocol: If the web server has been configured for SSL, then select HTTPS; otherwise select HTTP.
Agent Deployment URI: Enter a directory name. The default URI for the policy agent is /amagent.
The Universal Resource Identifier (URI) prefix tells the web server where to look for HTML pages the agent needs to display. For example, when a user attempts to access a URL, but cannot provide proper credentials, the agent must display an "Access denied" message. The URI prefix tells the web server where to look for the HTML page that contains the message. A directory denoted by this URI, will be created in the web server Document Root you supplied.
If all the information entered is correct, click Next.
Enter the information about the web server that runs DSAME services.
DSAME Services Host: Enter the fully qualified domain name of the system where the primary web server that runs DSAME services is installed. For example, myserver.siroe.com.
DSAME Services Port: Enter the port number for the primary web server that runs DSAME services.
DSAME Services Protocol: If the web server that runs DSAME services has been configured for SSL, then select HTTPS; otherwise select HTTP.
DSAME Services Deployment URI: Enter the location that was specified when DSAME was installed. The default Universal Resource Identifier (URI) for DSAME is /amserver.
Failover Server Host: Enter the fully qualified domain name for the secondary web server that will run DSAME services if the primary server becomes unavailable. If no failover server exists, then leave this field blank.
Failover Server Port: Enter the port number of the secondary web server that will run DSAME services. If no failover server exists, then leave this field blank.
If all the information entered is correct click Next.
When the installation is complete you may review the details, and then click Exit.
You must restart your iPlanet Web Server for the installation to be complete.
Uninstalling and Disabling Policy Agents
Use the following procedure to uninstall a Policy Agent:
From the Start Menu, open Settings > Control Panel.
In the Control Panel, open Add / Remove Programs.
In the Add/Remove Programs window, choose iPlanet Directory Services Access Management Edition Agent 1.1.
Disabling a Policy Agent Installed on Microsoft IIS
Use the following steps to disable an agent on Microsoft IIS:
Launch Internet Services Manager.
In the Start Menu, click Programs > Administrative Tools > Internet Services Manager.
Check the filter status.
Open properties for the host computer in the Tree Pane of the Internet Services Manager window which is titled "Internet Information Services."
The host computer name should appear in the tree underneath the Internet Information Services root.
Click Edit in the Master Properties section of the Internet Information Services tab.
Select the ISAPI Filters tab in the WWW Service Master Properties dialog that appears.
Highlight the filter named "DSAME IIS Agent."
You can click Edit to view the filter name and executable path. You'll need this information when you want to re-enable the agent. Click Cancel to return to the program.
Click Remove.
Click Apply and exit from the WWW Service Master Properties dialog.
Using the Command-Line Version of the Installation Program
The command-line version of the Installation program provides you an alternative to the graphical user interface (GUI) version.
To Install an Agent Using the Command Line
In the directory where you unzipped the binaries file, at the command line, enter the following command:
setup.bat -nodisplay
When prompted, provide the following information:
Have you read, and do you accept, all of the terms of the preceding Software License Agreement?
Install DSAME Agent in this directory: Specify the directory where you want the agent to be installed. To accept the default directory that is displayed in brackets, press Enter. Otherwise, enter a full path.
The following text displays:
DSAME Agent components showing a checked box will be installed. Only one agent may be installed at a time.
[ ] 1 DSAME Agent for IIS 5.0
[ ] 2 DSAME Agent for iPlanet Web Server 6.0 SP2
First, do one of the following:
To install the agent for Microsoft IIS 5.0, enter 1.
To install the agent for iPlanet Web Server 6.0 SP2, enter 2.
When a check mark appears beside your choice, enter 0 to continue.
When prompted, provide the following information about the web server instance this Agent will protect:
For details on these items, refer to "Using the Graphical User Interface (GUI) Version of the Installation Program" on page 48.
When prompted, provide the following information about the web server that runs DSAME Services:
For details on these items, refer to "Using the Graphical User Interface (GUI) Version of the Installation Program" on page 48.
When displayed, review the summary of installation information you've specified. Press Enter to continue, or enter and exclamation point (!) to exit the program.
The following message displays:
Ready to Install
1. Install Now
2. Start Over
3. Exit Installation
What would you like to do
To continue with installation, enter 1.
When installation is complete, you must restart the web server.
To Uninstall an Agent Using the Command Line
In the Agent_Install_Dir directory, at the command line, enter the following command:
java uninstall_DSAME_Agent -nodisplay
When prompted, provide the following information:
Please select the type of uninstall to perform from the following choices: To remove the product and all of the components, enter. To select some, but not all, product components to removed, enter Partial.
The following message displays:
1. Uninstall Now
2. Start Over
3. Exit Uninstallation
What would you like to do?
To begin uninstalling the agent, enter 1.
When the Installation program is finished, you must reboot the system.
If you want to see more details of the uninstallation, a log file is written in the following location:
%TEMP%\DSAME_Agent_uninstall.*
Using Secure Sockets Layer (SSL) with an Agent
During installation, if you specify the HTTPS protocol for the web server that runs DSAME services, the agent is automatically configured to communicate over SSL.
The Agent's Default Trust Behavior
By default, a policy agent is installed on a iPlanet Web Server 6.0 or Microsoft IIS 5.0 that will trust any server certificate presented over SSL by the web server that runs DSAME services; the agent does not check the Certificate Authority (CA) certificate. If the web server that runs DSAME services is SSL-enabled, and you want the policy agent to perform certificate-checking, you must do two things:
Disable the agent's default trust behavior.
Install CA certificate on the web server where the agent is installed. The CA certificate must the be same one that is installed on the web server that runs DSAME service.
Disabling the Agent's Default Trust Behavior
The following property exists in the AMAgent.properites file, and by default it is set to true:
com.iplanet.am.policy.agents.trust_server_certs=true
This means that the agent does not perform certificate checking.
To Disable the Default Behavior
The following property must be set to false:
com.iplanet.am.policy.agents.trust_server_certs=false
Installing the CA Certificate
The CA certificate that you install on the web server must be the same one that is installed on the web server that runs DSAME services.
To Install the CA Certificate on Microsoft IIS Server
See the instructions for installing a CA Certificate in the documentation that comes with the web server. Generally, this is done through the web server's Administration console.
Go to the following directory:
Agent_Install_Dir\Agents\iis50\utils
Add the same certificate that is installed on the web server that runs DSAME services into the existing certificate database. At the command line, enter the following command:
certutil -A -n cert-name -t "C,C,C" -d cert-dir -i cert-file
using the following variables:
cert-name can be any name for this certificate.
cert-dir is directory where the certificate-related files are located. On Windows the locations is:
Agent_Install_Dir\Agents\iis50\cert
cert-file is the base-64 encoded certificate file.
For more information on certutil, type certutil -H.
Restart IIS.
Setting the REMOTE_USER Server Variable
The REMOTE_USER server environment variable can be set to a DSAME authenticated user or anonymous user. By setting this variable to a specific user, the user becomes available to web applications (such as a CGI, servlet, or ASP program). This feature makes it possible to personalize the content of displayed HTML pages to specific users.
For an iPlanet Web Server agent, the feature is enabled all the time. To enable the REMOTE_USER feature for an IIS 5.0 agent, perform the following steps:
In the Windows Start menu, choose Programs > Administrative Tools > Internet Services Manager.
This will launch the Internet Information Services console.
On the web site that you want the DSAME agent to protect, select Properties.
Select the Directory Security tab.
In the Anonymous Access and Authentication Control section, click Edit.
In the dialog that displays, select Anonymous Access and Basic Authentication, then deselect Integrated Windows Authentication.
Performing these steps will set REMOTE_USER for allowed URLs.
To enable the REMOTE_USER setting for globally not-enforced URLs as specified in the AMAgent.properties file (these are URLs that can be accessed by unauthenticated users), you must set the following property in the AMAgent.properties file to TRUE (by default, this value is set to FALSE):
com.iplanet.am.policy.agents.anonRemoteUser.enable
When you set this property value to TRUE, the value of REMOTE_USER will be set to the value contained in the following property in the AMAgent.properties file (by default, this value is set to anonymous):
com.iplanet.am.policy.agents.unauthenticatedUser
Forwarding LDAP User Attributes via HTTP Headers
DSAME agents has the ability to forward LDAP user attribute values via HTTP headers to end web applications. The LDAP user attribute values come from the server side of DSAME. A DSAME agent behaves like a broker to obtain and relay user attribute values to the destination servlets, CGI scripts, or ASP pages. These applications can in turn use the attribute values to personalize page content.
This feature is configurable through two properties in AMAgent.properties file. To turn this feature on and off, use the following AMAgent.properties file property:
com.iplanet.am.policy.agents.foward_ldapattr_in_http_headers.enable
By default, this property is set to false, and the feature off. To turn on attribute forwarding, set this property to true. To configure the attributes that are to be forwarded in the HTTP headers, use the AMAgent.properties file property com.iplanet.am.policy.agents.ldapattr
Below is an example section in the AMAgent.properties file which shows how this feature is used:
By default, some LDAP user attribute names and HTTP header names are set to sample values.
To find the appropriate LDAP user attribute names, check the following XML file on the machine where the DSAME server is installed:
DSAME_Install_Dir/SUNWam/config/xml/amUser.xml
The attributes in this file could be either DSAME User attributes or DSAME Dynamic attributes (for explanation of these two types of user attributes, refer to the DSAME Administration Guide).
The attribute and HTTP header names that need to be forwarded must be determined by the end-user applications on the web server that the agent is protectingafter all, these applications are the consumers of the forwarded header values (the forwarded information is used for the customization and personalization of web pages).
Validating Client IP Addresses
This feature can be used to enhance security by preventing the stealing or "hijacking" of SSO tokens.
The AMAgent.properties file contains a property titled com.iplanet.am.policy.agents.client_ip_validation.enable, which by default is set to false.
If you set this property value to true, client IP address validation will be enabled for each in-coming request that contains an SSO token. If the IP address from which request was generated does not match the IP address issued for the SSO token, the request will be denied. This is essentially the same as enforcing a deny policy.
This feature should not be used, however, if the client browser uses a web proxy or if there is a load-balancing application somewhere between the client browser and the agent-protected web server. In such cases, the IP address appearing in the request will not reflect the real IP address on which the client browser runs.
Troubleshooting the IIS Policy Agent
If you are experiencing problems with your installation try the following:
Check the installation log file for errors:
%TEMP%\DSAME_install.nnnn
Re-install by uninstalling and then installing.
Launch Internet Services Manager.
Start > Programs > Administrative Tools > Internet Services Manager.
Open the properties for the host computer in the Tree Pane of the Internet Services Manager window that is titled Internet Information Services.
The host computer name should appear in the tree underneath the Internet Information Services root.
Click Edit in the Master Properties section of the Internet Information Services tab.
Select the ISAPI Filters tab in the WWW Service Master Properties dialog that appears.
Look for the filter name "DSAME agent."
If the Filter name "DSAME agent" does not appear at all, then check that the installer was run, and look for any errors during installation. The install log is located at:
%TEMP%\DSAME_install.nnnn
A green arrow pointing up in the Status column to the right of the "DSAME agent" indicates the agent loaded successfully into IIS. A red arrow pointing down indicates that the filter failed to load. The most likely cause of the filter not loading successfully (red arrow) is that it cannot locate the required dll files.
Check your system path to ensure that the following directory is present:
Agent_Install_Dir\Agents\iis50\lib
If the filter did not load successfully check the following:
Check the path of the Agent DLL by clicking "DSAME agent" and then Edit. Ensure that the path in the text box labeled Executable is valid.
The agent also needs several DLL files. Check that the following exist in the directory Agents\iis50\lib:
libamPolicy.dll
libnspr4.dll
libplc4.dll
libplds4.dll
nss3.dll
ssl3.dll
If the libraries are in your system path try rebooting the system.
IIS logs filter loading errors in the System Event Log. To check the event log:
If the agent loads but returns HTTP 500 Internal Server Error for all URL requests to the IIS web server.
This indicates that the agent has loaded but did not properly initialize. Returning HTTP 500 Internal Server Error for all HTTP requests is a fail-safe to protect URL resources when the Agent cannot initialize. The most likely cause is a DSAME agent or server misconfiguration or unavailability.
Check the agent debug log.
The log is located by default at the Agent_Install_Dir directory. This is the best source of debug information for resolving initialization and agent operation issues. The log file directory is specified by the property: com.iplanet.services.debug.directory in the AMAgent.properties file located in the directory:
Agent_Install_Dir\Agents\iis50\config
The property com.iplanet.services.debug.level controls the verbosity of the log information. Setting this property to "message" yields the most debug information. The value "message" should not be used in production environments since it reduces performance and quickly generates large debug outputs to the file.
Check that the agent can locate the AMAgent.properties configuration file.
The agent uses the registry key HKEY_LOCAL_MACHINE\Software\iPlanet\DSAME IIS Agent\5.0 to locate the AMAgent.properties file. The AMAgent.properties file is located at:
Agent_Install_Dir\Agents\iis50\config
The agent uses the Application Event Log to log errors that occur before the debug log file specified in AMAgent.properties is started.
Previous Contents Next
Copyright 2002 Sun Microsystems, Inc. All rights reserved.
Last Updated November 20, 2002