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



Chapter 2   Policy Agent Pack 1.1 on Solaris 8


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 Solaris 8 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:


Supported Solaris Web Servers

Policy Agent Pack 1.1 supports the following servers running on the Solaris 8 operating system:

  • iPlanet Web Server 6.0 SPx

  • iPlanet Web Server 4.1 SP8

  • iPlanet Proxy Server 3.6

  • Apache 1.3.12


Patch Cluster for Solaris

  • When running Apache 1.3.12 Web Server on Solaris 8 operating system, you must ensure that the recommended patch cluster 109234-09 is installed. You can download this patch from: http://sunsolve.sun.com.



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 agents on the following servers using the Solaris 8 operating system:

  • iPlanet Web Server 4.1

  • iPlanet Web Server 6.0

  • Apache web server 1.3.12


To Install a Web Server Policy Agent

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

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

    # gunzip -dc agents-RTM Candidate-domestic-us.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 page, click Next.

  4. Read the License Agreement. Click Yes to agree to the license terms.

  5. When prompted, provide the following information about the web server this agent will protect:

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

    Select the desired component: Mark the check box of the agent you want to install, and then click Next.


    Note

    Only one agent can be installed at a time.


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

    Web Server Instance Directory: This prompt displays only if you have selected an iPlanet Web Server agent. 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-mycomputer.siroe.com

    Apache Config File Location: This prompt displays only if you've selected the Apache web server agent. Specify the web server that this agent will protect. Enter the full path to the directory where the httpd.conf file is located.

    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.

  6. Enter information about the web server that runs DSAME policy and management services. The Policy Agent will connect to this server.

    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 web server that runs DSAME services.

    DSAME Services Protocol: If the web server that runs DSAME services is SSL-enabled, 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 name for the secondary web server that will run DSAME 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 DSAME services. If no failover host exists, then leave this field blank.

    When all the information is entered correctly, click Next.

  7. 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.

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

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

  10. You must restart your iPlanet Web Server or Apache web server for the installation to be complete.


Installing a Proxy Server Policy Agent

Use these instructions for installing a Policy Agent on iPlanet Proxy Server 3.6 on the Solaris 8 operating system.


To Install a Proxy Server Policy Agent

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

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

    # gunzip -dc agents-RTM Candidate-domestic-us.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 will find the program in the directory where you untarred the binaries file. At the command line, enter the following:

    # ./setup

  3. In the Welcome page, click Next.

  4. Read the License Agreement. Click Yes to agree to the license terms.

  5. To search for the directory where you would like to install the agent, click Browse. To accept the default, click Next.

  6. Select the component DSAME Agent for iPlanet Proxy Server 3.6, and then click Next.


    Note

    Only one component can be installed at a time.


  7. When prompted, 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 remote web server is installed. For example, mycomputer.siroe.com.

    Proxy Server Instance Directory: Enter the full path to the directory where the iPlanet Proxy Server instance is located. For example:

    proxy_server_root_dir/proxy-mycomputer-proxy

    Proxy Server Port: Enter the port number for the Proxy server instance. If you login to Proxy Server on the local machine as admin, you can click on the Proxy Server instance and check the port number.

    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. When prompted, 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 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 name for the secondary web server that will run DSAME 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 will run DSAME services. If no failover host exists, then leave this field blank.

    When all the information is entered correctly, click Next.

  9. Click Install Now.

  10. When the installation is complete you may review the details or click Exit.

  11. Restart the Proxy Server.


Uninstalling a 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_agent

  2. Click Next on Welcome Panel.

  3. On Type of Install Panel, select Full.

  4. Click Uninstall Now.

  5. Click Exit after uninstallation is complete.

In the directory where the product binary file is unpacked (and where the installation program was invoked), there is another uninstallation program named uninstall. The uninstall program can be used to detect and uninstall all agents that were previously installed using the setup program; even agents that were installed on a remote machine. Invoke uninstall using the following command:

# ./uninstall

On the other hand, uninstall_agent will uninstall only the agent (or agents) that were previously installed with the setup program in the current directory.



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 DSAME Agent in this directory: Enter the full path to the directory in which you want to install the policy agent.

    The following text displays:

    [ ] 1 DSAME Agent for iPlanet Web Server 6.0 SPx
    [ ] 2 DSAME Agent for iPlanet Web Server 4.1 SP8
    [ ] 3 DSAME Agent for iPlanet Proxy Server 3.6
    [ ] 4 DSAME Agent for Apache 1.3.12
    DSAME Agent components showing a checked box will be installed. Only one agentmay be installed at a time.

    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  DSAME Agent for iPlanet Web Server 6.0 SPx
    [ ]  2  DSAME Agent for iPlanet Web Server 4.1 SP8
    [ ]  3  DSAME Agent for iPlanet Proxy Server 3.6
    [ ]  4  DSAME Agent for Apache 1.3.12

    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:

    • Hose Name

    • Web Server Port

    • Web Server Protocol

    • iPlanet Web Server Instance Directory

    For more information on each of these items, see "Installing a Web Server Policy Agent".

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

    • Host Name

    • Port Number

    • Protocol

    • Deployment URI

    • Failover Host

    • Failover Port

    • amAdmin Password

    For more information on each of these items, see "Installing a Web Server Policy Agent".

  5. 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.


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_agent -nodisplay


    Note

    You can also use the uninstall command from the directory where the product was originally installed (this is the directory from where you ran the setup command). To uninstall an agent from the original installation directory, enter the following command:

    # ./uninstall -nodisplay


    If you have used the uninstall_agent -nodisplay command, the following text displays:
    Please select the type of uninstall to perform from the following choices:
    1. Full
    2. Partial

    If you have used the uninstall command from the installation directory, a list of agents is displayed. From this list, select the agent that you wish to uninstall.

    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.

  2. 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.

  3. The following text displays:

    Product           Result     More Info
    1. DSAME Agent    Full       Available
    2. Done

    To see log information on the agent, enter 1. To exit the Installation 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 y 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 a 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, located in the following directory:

Agent_Install_Dir/SUNWam/agent_directory/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 DSAME 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/_opt_iws6a_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 prepared 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=
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: 60
The directory /var/opt/SUNWam/agents/_opt_iws6a_https-server_instance does not exist.
Creating it.
Deploying web application
Loading new configuration
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/agent_directory/bin

Here is an example run of the unconfig script:

# ./unconfig /opt/iws6a/https-mycomputer.siroe.com
Unconfiguring webserver ... Deleting web application
Loading new configuration
Web application delete successful
done.



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. If you're using iPlanet Web Server, you can access the following documentation on the Internet:

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



The Agent's Default Trust Behavior

By default, a policy agent is installed on a iPlanet Web Server 6.0 or Apache Server 1.3.12 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 URL policy agent to perform certificate-checking, you must do two things:

  1. Disable the agent's default trust behavior.

  2. Install a 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 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 iPlanet Web Server

See the instructions for installing a CA Certificate in the documentation that comes with the web server. In general, you install a CA Certificate through the web server's Administration console.

You can access the documentation for iPlanet Web Server 6.0 on the Internet at the following URL:

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


To Install the CA Certificate on Apache 1.3.12

You can use the certutil program to install the CA Certificate on Apache 1.3.12.

  1. In C shell, at the command line, enter the following commands:

    # cd /Agent_Install_Dir/SUNWam/apache1.3.12/cert

    # setenv LD_LIBRARY_PATH /Agent_Install_Dir/SUNWam/apache1.3.12/lib

    # export LD_LIBRARY_PATH

    # ./certutil -A -n cert-name -t "C,C,C" -d . -i cert-file

    In the commands above, the variables represent the following:

    • cert-name can be any name for this certificate.

    • cert-dir is directory where the certificate-related files are located.

    • cert-file is the base-64 encoded root certificate file.

    For more information on the certutil utility, enter certutil -H for online Help.

  2. To verify that the certificate is properly installed, at the command line, enter the following:

    # ./certutil -L -d .

    Trust database information will display including the name of the root CA certificate you installed. Example:

    Certificate Name Trust Attrubutes

    rootCAcert

    p Valid peer
    P Trusted peer (implies p)
    c Valid CA
    T Trusted CA to issue client certs (implies c)
    C Trusted CA to certs(only server certs for ssl) (implies c)
    u User cert
    w Send warning



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.

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

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


Note

This feature is not available for the iPlanet Proxy Server Agent.




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:

# 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 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 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 that 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.


Note

This feature is not available for the iPlanet Proxy Server Agent.




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.


Note

This feature is not available for the iPlanet Proxy Server Agent.



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

Last Updated November 20, 2002