Sun ONE logo     Previous     Contents     Next     
Sun ONE Identity Server Policy Agent Pack Guide



Chapter 8   Policy Agent for Sun ONE Web Server 6.0


Sun ONE Identity Server Policy Agents work in tandem with Sun ONE Identity Server to grant or deny user access to web servers in an enterprise. This chapter explains how to install and configure the Sun ONE Identity Server Policy Agent for Sun ONE Web Server 6.0 running on the Solaris 9 operating system.

Topics include:



Before You Begin

Be sure that you are familiar with the concepts presented in Chapter 1 "Read This First." The chapter includes brief but important information on the following topics:



Using the Graphical User Interface (GUI) Version of the Installation Program

The GUI version of the Installation program allows you to install only one policy agent at a time.


Installing a Web Server Policy Agent

Use these instructions for installing Agent for Sun ONE Web Server 6.0.

You must have root permissions when you run the agent installation program.

  1. Unpack the product binaries file using the following command:

    # gunzip -dc S1WebServer_6.0_agent_1.2.sparc-sun-solaris2.8.tar.gz | tar -xvof -
    Note

    Use the tar that is shipped with Solaris. Don't use the GNU tar.


  2. Run the setup program. You'll find the program in the directory where you untarred the binaries file. At the command line, enter the following:

    # ./setup

  3. In the Welcome Screen, click Next.

  4. In the Software License Agreement screen, read the License Agreement. Click Yes(Accept License) to agree to the license terms.

  5. In the Select Installation Directory screen, provide the following information:

    Install SunONE Webserver Agent in this directory: Enter the full path to the directory where you want this agent to be installed, and then click Next.

  6. Choose an Agent Install component: By default, Sun(TM) ONE Identity Server Policy Agent 1.2 for Sun ONE Web Server 6.0 is selected, click Next.

  7. In the Agent Web Server Information screen, provide the following information about the web server this agent will protect:

    Host Name: Enter the fully qualified domain name of the machine where the web server is installed. For example, mycomputer.siroe.com.

    Sun ONE Web Server Instance Directory: Specify the web server instance that this agent will protect. Enter the full path to the directory where the web server instance is located. Example:

    /Web_Server_root/https-server_instance

    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, choose HTTPS; otherwise choose 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.

  8. In the Identity Server Services Information screen, enter information about the web server that runs Identity Server policy and management services. The Policy Agent will connect to this server.

    Identity Server Services Host: Enter the fully qualified domain name of the system where the primary web server that runs Identity Server services is installed. For example, myserver.siroe.com.

    Identity Server Services Port: Enter the port number for the web server that runs Identity Server services.

    Identity Server Services Protocol: If the web server that runs Identity Server services is SSL-enabled, select HTTPS; otherwise select HTTP.

    Identity Server Services Deployment URI: Enter the location that was specified when Identity Server was installed. The default Universal Resource Identifier (URI) for Identity Server is /amserver.

    Failover Server Host: Enter the fully qualified name for the secondary web server that will run Identity Server services if the primary web server becomes unavailable. If no failover host exists, then leave this field blank.

    Failover Server Port: Enter the port number of the secondary web server that runs Identity Server services. If no failover host exists, then leave this field blank.

    When all the information is entered correctly, click Next.

  9. In the Summary of all the Selections screen, review the Installation Summary to be sure that the information you've entered is correct. If you want to make changes, click Back. If all the information is correct, click Next

  10. In the Ready to Install page, click Install Now.

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

  12. You must restart your Sun ONE Web Server for the installation to be complete.


Uninstalling a Web Server Policy Agent

To uninstall an agent, you must run the Uninstallation program. Follow the steps below:

  1. In the directory where the agent is installed, at the command line, enter the following command:

    # ./uninstall_SunONE_Webserver_agent

  2. Click Next on Welcome Panel.

  3. In the Select Type of Uninstall screen, select Full to remove the product and all of the components from your system.

  4. Click Uninstall Now.

  5. Click Exit after uninstallation is complete.



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

  1. In the directory where you unpacked the binaries file, at the command line, enter the following:

    # ./setup -nodisplay

  2. When prompted, provide the following information:

    Have you read, and do you accept, all of the terms of the preceding Software License Agreement? Enter yes.

    Install Sun ONE Webserver Agent in this directory: Enter the full path to the directory in which you want to install the policy agent.

    The following text displays:

    SunONE Webserver Agent components showing a checked box will be installed. Only one agentmay be installed at a time.
    [ ]  1 Sun(TM) ONE Identity Server Policy Agent for SunONE Web Server 6.0

    To check a particular component, enter its number, or 0 when you are finished: Enter the number that corresponds to the policy agent you want to install. The following message displays, with a checkmark beside the server your specified.

    [X]  1 Sun(TM) ONE Identity Server Policy Agent for SunONE Web Server 6.0

    To check a particular component, enter its number, or 0 when you are finished: Enter 0 to continue.

  3. Provide the following information about the iPlanet Web Server this agent will protect:

    • Host Name

    • SunONE Web Server Instance Directory

    • Web Server Port

    • Web Server Protocol

    • Agent Deployment URI

    For details on these items, refer to "Using the Graphical User Interface (GUI) Version of the Installation Program" on page 124.

  4. Provide the following information about the web server that runs Identity Server Services:

    • Identity Server Services Host

    • Identity Server Services Port

    • Identity Server Services Protocol

    • Identity Server Services Deployment URI

    • Failover Server Host

    • Failover Server Port

    For details on these items, refer to "Using the Graphical User Interface (GUI) Version of the Installation Program" on page 124.

  5. The Summary of all the selections you have made is displayed.

  6. The following text displays:

    Ready to Install

    1. Install Now
    2. Start Over
    3. Exit Installation

    When prompted, What would you like to do?, enter 1 to start the installation.

  7. The Installation details are displayed:
    Product                    Result       More Info
    1. SunONE Webserver Agent  Installed    Available
    2. Done

    To see log information on the agent, enter 2.To exit the Installation program, enter 2.


To Uninstall an Agent Using the Command Line

  1. From the directory where the agent is installed, enter the following command at the command line:

    # ./uninstall_SunONE_Webserver_agent -nodisplay

  2. The following text displays:
    Please select the type of uninstall to perform from the following choices:
    1. Full
    2. Partial

    To remove the product and all of the components from your system, enter 1 for Full. To remove some, but not all, product components, enter 2 for Partial.

  3. The following text displays:
    Ready to Uninstall

    1. Uninstall Now
    2. Start Over
    3. Exit Uninstallation

    When prompted, What would you like to do? enter 1 to begin uninstallation.

  4. The following text displays:

    Product                        Result     More Info
    1.  SunONE Webserver Agent     Full       Available
    2.  Done

    To see log information on the agent, enter 1. To exit the Uninstallation program, enter 2.



Installing Multiple Web Server Agents on the Same Solaris Computer System

To install multiple web server agents on a single computer system, use the graphical user interface (GUI) version of the Agent Installation program to install the first agent. After the first agent is installed, you can then install successive agents using the config script. This script must be run from the command line as described in the next section.


To Install Multiple Web Server Agents on the Same Computer System

Once you have installed an agent on a system, you can install successive agents on that system using a script that copied to the system during the agent installation. The two scripts, config and unconfig are located in the following directory:

Agent_Install_Dir/SUNWam/iws60/bin

To install additional agents on a system after the original agent has been installed, run the config script from the bin directory using the following command:

# ./config

Follow the prompts to install the additional agents. For information on each of the prompts, see "Installing a Web Server Policy Agent". In general, information needs to be entered for both the protected web server instance and the Identity Server(s). The following text shows an example run:

# ./config
Enter the Web Server Instance Directory: [/Web_Server_root/https-server_instance]
Enter the Local Hostname: [mycomputer.siroe.com]
Enter the Agent Web Server Port: [80]
Select Agent Web Server Protocol: [1] http [2] https-->[1]
Enter the Agent Deployment URI: [/amagent]
Enter the DSAME Service Host: [mycomputer.siroe.com]
Enter the DSAME Service Port: [58080]
Select DSAME Service Protocol: 1. http 2. https-->[1]
Enter the DSAME Deployment URI: [/amserver]
Enter the DSAME Failover Server Host: []
Enter the DSAME Failover Server Port: []
Configuring webserver ... Webserver version: 6.0
The directory /var/opt/SUNWam/agents/_usr_iplanet_servers_https-server_instance does not exist. Creating it.
Deploying web application
Loading new configuration
Web application deploy successful

done


Using the config Script for Silent Installations

The config script can also be used to do silent, non-interactive agent installations. For details on its usage, use the config -h command to display details on the config command:

# ./config -h
Usage: config [ -r response_file | -R | -h ]
-r specifies a response file.
-R prints out the response file template.
-h prints out this message.

In order to perform a silent installation, you must supply a response.file for each of the agents you want to install. The command config -R indicates the fields which you must supply in the response.file. This text file needs to be created before you begin the silent installation.

# ./config -R
Response file contains:
AGENT_HOST # agent hostname
WS_INSTANCE_DIR # iWS instance directory
AGENT_PORT # agent server port
AGENT_PROTOCOL # agent protocol: http|https
AGENT_DEPLOY_URI # agent deploy URI
SERVER_HOST # dsame server name
SERVER_PORT # dsame server port
SERVER_PROTO # dsame server protocol: http|https
SERVER_DEPLOY_URI # dsame server deploy URI
FAILOVER_S_HOST # dsame fail over server name
FAILOVER_S_PORT # dsame fail over server port

Here is an example response.file, named response.iws60:

AGENT_HOST=mycomputer.siroe.com
WS_INSTANCE_DIR=/Web_Server_root/https-server_instance
AGENT_PORT=80
AGENT_PROTOCOL=http
AGENT_DEPLOY_URI=/amagent
SERVER_HOST=mycomputer.siroe.com
SERVER_PORT=http
SERVER_PROTO=58080
SERVER_DEPLOY_URI=/amserver
FAILOVER_S_HOST=
FAILOVER_S_PORT=

Below is an example showing how the config script is used in conjunction with the response.iws60 response file to complete a silent installation:

# ./config -r ./response.iws60
Configuring webserver ... Webserver version:
The directory /var/opt/SUNWam/agents/_usr_iplanet_servers_https-server_instance does not exist. Creating it.
Deploying web application
Loading new configuration
Reconfigure failure: server not running

Web application deploy successful

done


Note

Be sure to use the unconfig script to uninstall any agent that was installed using the config script—you cannot use the GUI installation program to uninstall agents that were installed via the command line.



Removing an Agent Using the unconfig Script

To remove an agent that was installed from the command line using the config script, use the script unconfig. The unconfig script is located in the following directory:

Agent_Install_Dir/SUNWam/iws60/bin

Here is an example run of the unconfig script:

# ./unconfig /Web_Server_root/https-server_instance
Unconfiguring webserver ... Deleting web application
Loading new configuration
Reconfigure failure: server not running

Web application delete successful
done.


Note You cannot uninstall the original agent if multiple web server agents are installed on the system. To uninstall the original agent, uninstall the agents using unconfig script and uninstall the original agent using command line.




Using Secure Sockets Layer (SSL) with an Agent


During installation, if you choose the HTTPS protocol, the agent is automatically configured and ready to communicate over SSL.


Note

Before proceeding with the following steps, you should have a solid understanding of SSL concepts and the security certificates required to enable communication over the HTTPS protocol. See the documentation that comes with your web server or access from the following site:

http://docs.sun.com/source/816-5691-10/esecurty.htm



The Agent's Default Trust Behavior

By default, the Policy Agent installed on a Sun ONE Web Server 6.0 that will trust any server certificate presented over SSL by the web server that runs Identity Server services; the agent does not check the Certificate Authority (CA) certificate. If the web server that runs Identity Server services is SSL-enabled, and you want the URL policy agent to perform certificate-checking, you must do two things:

  1. Disable the agent's default trust behavior.

  2. Install CA certificate on the remote web server (where the agent is installed). The CA certificate must the be same one that is installed on the web server that runs Identity Server 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 Identity Server services.


To Install the CA Certificate on iPlanet Web Server

See the Web Server documentation for installing a CA Certificate.

http://docs.sun.com/source/816-5691-10/



Setting the REMOTE_USER Server Variable


The REMOTE_USER server environment variable can be set to a Identity Server 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.

REMOTE_USER will be set while accessing 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=TRUE

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=anonymous



Forwarding LDAP User Attributes via HTTP Headers


Identity Server 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 Identity Server. An Identity Server 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:

# Ldap User Attributes
# format: ldap_attribute_name|http_header_name
#
# below are a few notes based on different behaviours of web servers
#
# NOTE: for iWS agents, "http_header_name" must be in lower-case letters,
# and any _ will become -
# NOTE: for IIS and Apache agents, "http_header_name" will be prefixed
# by HTTP_, and all lower case letters will become upper case,
# and any - will become _
#
com.iplanet.am.policy.agents.ldapattr=cn|common-name,ou|organiza tion-unit,o|organization,
c|country,mail|email,employeenumber|employee-number

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 Identity Server is installed:

DSAME_Install_Dir/SUNWam/config/xml/amUser.xml

The attributes in this file could be either Identity Server User attributes or Identity Server Dynamic attributes (for explanation of these two types of user attributes, refer to the Sun ONE Identity Server 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 protecting—after all, these applications are the consumers of the forwarded header values (the forwarded information is used for the customization and personalization of web pages).


Note

Each web server has its own peculiarities about HTTP header name conventions. For more information on this feature, refer to the comments listed before each property in the AMAgents.properties file.




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.

com.iplanet.am.policy.agents.client_ip_validation.enable=true


Previous     Contents     Next     
Copyright 2002   Sun Microsystems, Inc. All rights reserved.

Last Updated November 20, 2002