test

Sun Java System Access Manager Policy Agent 2.2 Guide for Sun Java System Web Server 7.0

Chapter 4 Installing Policy Agent 2.2 for Sun Java System Web Server 7.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.

Since Policy Agent 2.2 for Sun Java System Web Server 7.0 was developed as part of the OpenSSO project its distribution files are available only in a .zip file format. More significantly, unlike web agents that were not developed in the OpenSSO project, the instructions around installation differ very little by platform. Therefore, this chapter is not divided into platform-specific sections. Differences that exist, if any, for a particular platform, are explained as applicable. For information on the supported platforms, see Supported Platforms and Compatibility of Agent for Sun Java System Web Server 7.0.

This chapter is organized into the following sections:

In terms of the installation process, first, perform the pre-installation (preparation) steps. Then, perform the installation, itself. After you complete the installation, verify that the installation was successful.

The installation process has two phases. The first phase of the installation includes launching the installation program, which requires a directory to already have been selected for the agent files. The second phase of the installation involves interacting with the installation program. During this phase, the program prompts you step by step to enter information. Accompanying the prompts, are explanations of the type of information you need to enter. After you complete the installation, you can look at the installation log files.

Next, complete the required post-installation tasks described in Chapter 6, Post-Installation of Policy Agent 2.2 for Sun Java System Web Server 7.0.

Preparing to Install Agent for Sun Java System Web Server 7.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.

ProcedureTo Prepare to Install Policy Agent 2.2 for Sun Java System Web Server 7.0

Perform the following pre-installation tasks:

  1. Ensure that Policy Agent 2.2 for Sun Java System Web Server 7.0 is supported on the desired platform as listed in Supported Platforms and Compatibility of Agent for Sun Java System Web Server 7.0.

  2. Install Sun Java System Web Server 7.0 if not already installed.

    Refer to the Sun Java System Web Server 7.0 documentation for details on how best to install and configure this server for your platform.

  3. Ensure that Sun Java System Web Server 7.0 has the latest patches available.

  4. Set your JAVA_HOME environment variable to a JDK version 1.5.0 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:

  5. (Conditional) Create a valid agent profile in Access Manager Console if one has not already been created.

    Web agents can function without the creation of an agent profile. However, creating an agent profile provides greater security. Furthermore, the creation of an agent profile is necessary when cross domain single sign-on (CDSSO) is configured with Access Manager. For information on how to create an agent profile, see Chapter 5, The Relationship Between the Agent Profile and Web Agents in Policy Agent 2.2.

    To avoid a misconfiguration of the agent, ensure that you know the exact ID and password used to create the agent profile. You must enter the agent profile password correctly in the next step and you must enter the agent profile ID correctly when installing the agent.

  6. Create a text file and add the agent profile password to that file.

    Ensure that this file is located in a secure directory of your choice. You will refer to this file during the agent installation process.

    With the agent profile password in this file, stored in a secure location, you do not need to enter sensitive information in the console. A valid password file can have only one line that contains the agent profile password.

  7. Unpack the product binaries

    unzip web-server-version_agent.zip

    where web-server-version is a placeholder for the name of the .zip file. This file name is derived by combining an abbreviation of the agent name with an abbreviation of the respective platform.

  8. (Conditional) On UNIX-based systems, ensure that specific programs have executable permissions.

    1. Change directories to PolicyAgent-base/bin.

    2. Ensure executable permissions are set for the following programs:

      • agentadmin

      • crypt_util

      • certutil

      For example the following command is one method for setting executable permissions for these three programs:

      chmod +x agentadmin certutil crypt_util

Launching the Installation Program of Agent for Sun Java System Web Server 7.0

Once you have performed all the pre-installation steps, you can launch the installation program as described in the following subsection.

ProcedureTo Launch the Installation Program of Agent for Sun Java System Web Server 7.0

To launch the installation program, perform the following steps:

  1. Change to the following directory:


    PolicyAgent-base/bin

    Information about the PolicyAgent-base directory is provided in Location of the Web Agent Base Directory in Policy Agent 2.2.

    The PolicyAgent-base/bin directory contains the agentadmin program, which is used for installing this and other web agents developed in the OpenSSO project. The agentadmin program is used to perform a variety of other tasks as well. For more information on the agentadmin program, see Introduction of the agentadmin Program in Web Agents for Policy Agent 2.2.

  2. Issue the following command:


    ./agentadmin --install

  3. (Conditional) If you receive license agreement information, accept or reject the agreement prompts. If you reject any portion of the agreement, the program will end.

    The license agreement is displayed only during the first run of the agentadmin program.

Next Steps

Next, you must interact with the installation program as described in the following section, Using the Installation Program of Agent for Sun Java System Web Server 7.0. Read the entire section before proceeding to the example installation interaction provided in Example of Installation Program Interaction in Agent for Sun Java System Web Server 7.0.

Using the Installation Program of Agent for Sun Java System Web Server 7.0

After you issue the agentadmin command and accept the license agreement (if necessary) the installation program appears, prompting you for information.

The steps in the installation program are displayed in this section in an example interaction. Your answers to prompts can differ slightly or greatly from this example depending upon your specific deployment. In the example, most of the defaults have been accepted. This example is provided for your reference and does not necessarily indicate the precise information you should enter.

The following bulleted list provides key points about the installation program.

About Installation Prompts in Agent for Sun Java System Web Server 7.0

The following list provides information about specific prompts in the installation. Often the prompt is self explanatory. However, at other times you might find the extra information presented here to be very helpful. This extra information is often not obvious. Study this section carefully before proceeding.

The Deployment URI for Access Manager Services

Enter a Universal Resource Identifier (URI) that will be used to access Agent for Sun Java System Web Server 7.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://agentHost1.domain:port/web-agent-deployment-uri where agentHost1, domain and port are FQDN and port number of the Sun Java System Web Server 7.0 instance where the agent is installed and web-agent-deployment-uri is the URI where the Sun Java System Web Server 7.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://agentHost1.example.com:80/amagent
The Agent Profile Name

An agent profile should have been created as a pre-installation step. The creation of the agent profile is mentioned in that section. For the pre-installation steps, see Preparing to Install Agent for Sun Java System Web Server 7.0. For the actual information on creating an agent profile, see Chapter 5, The Relationship Between the Agent Profile and Web Agents in Policy Agent 2.2.

In summary, the web agent communicates with Access Manager with a specific ID and password created through an agent profile using Access Manager Console. For web agents, the creation of an agent profile is not mandatory. However, Access Manager uses the agent profile to authenticate an agent. This is part of the security infrastructure.

The Agent Profile Password File

The web agent profile password file should have been created as a pre-installation step. For the pre-installation steps, see Preparing to Install Agent for Sun Java System Web Server 7.0.

When the installation program prompts you for the password for the agent, enter the fully qualified path to this password file.

After you have completed all the steps, a summary of your responses appears followed by options that allow you to navigate through those responses to accept or reject them.

When the summary appears, note the agent instance name, such as Agent_001. You might be prompted for this name during the configuration process.

About the options, the default option is 1, Continue with Installation.

You can edit your responses as necessary, return to the options list, and choose option 1 to finally process your responses.

Example of Installation Program Interaction in Agent for Sun Java System Web Server 7.0

The following example is a sample installation snapshot of Policy Agent 2.2 for Sun Java System Web Server 7.0. By no means does this sample represent a real deployment scenario.

The section following the installation summary section, Implications of Specific Deployment Scenarios in Agent for Sun Java System Web Server 7.0, explains specific deployment scenarios, such as installing multiple agent instances. Review the information in that section before proceeding with the installation. That information is divided into subsections as follows:


************************************************************************
Welcome to the Access Manager Policy Agent for Sun Java System Web Server If
the Policy Agent is used with Federation Manager services, User needs to
enter information relevant to Federation Manager.
************************************************************************
Enter the complete path to the directory which is used by Sun Java System Web
Server to store its configuration Files. This directory uniquely
identifies the Sun Java System Web Server instance that is secured by this
Agent.
[ ? : Help, ! : Exit ]
Enter the SJS Web Server Config Directory Path
[/var/opt/SUNWwbsvr7/https-agentHost1/config]:

Enter the fully qualified host name of the server where Access Manager
Services are installed.
[ ? : Help, < : Back, ! : Exit ]
Access Manager Services Host: amHost.com

Enter the port number of the Server that runs Access Manager Services.
[ ? : Help, < : Back, ! : Exit ]
Access Manager Services port [80]: 8080

Enter http/https to specify the protocol used by the Server that runs Access
Manager services.
[ ? : Help, < : Back, ! : Exit ]
Access Manager Services Protocol [http]:

Enter the Deployment URI for Access Manager Services.
[ ? : Help, < : Back, ! : Exit ]
Access Manager Services Deployment URI [/amserver]:

Enter the fully qualified host name on which the Web Server protected by the
agent is installed.
[ ? : Help, < : Back, ! : Exit ]
Enter the Agent Host name: agentHost1.com

Enter the preferred port number on which the Web Server provides its
services.
[ ? : Help, < : Back, ! : Exit ]
Enter the port number for Web Server instance [80]: 7000

Select http or https to specify the protocol used by the Web server instance
that will be protected by Access Manager Policy Agent.
[ ? : Help, < : Back, ! : Exit ]
Enter the Preferred Protocol for Web Server instance [http]:

Enter a valid Agent profile name. Before proceeding with the agent
installation, please ensure that a valid Agent profile exists in Access
Manager.
[ ? : Help, < : Back, ! : Exit ]
Enter the Agent Profile name [UrlAccessAgent]:

Enter the path to a file that contains the password to be used for identifying
the Agent.
[ ? : Help, < : Back, ! : Exit ]
Enter the path to the password file: /opt/password

-----------------------------------------------
SUMMARY OF YOUR RESPONSES
-----------------------------------------------
SJS Web Server Config Directory : /var/opt/sun/SUNWwbsvr7/https-agentHost1/config
Access Manager Services Host : amHost.com
Access Manager Services Port : 8080
Access Manager Services Protocol : http
Access Manager Services Deployment URI : /amserver
Agent Host name : agentHost1.com
Web Server Instance Port number : 7000
Protocol for Web Server instance : http
Agent Profile name : UrlAccessAgent
Agent Profile Password file name : /opt/password

Verify your settings above and decide from the choices below.
1. Continue with Installation
2. Back to the last interaction
3. Start Over
4. Exit
Please make your selection [1]:

Summary of a Web Agent Installation in Policy Agent 2.2

At the end of the installation process, the installation program prints the status of the installation along with the installed web agent information. The information that the program displays can be very useful. The program also displays the location of specific files, which can be of great importance. In fact, you might want to view the installation log file once the installation is complete, before performing the post-installation steps as described in Chapter 6, Post-Installation of Policy Agent 2.2 for Sun Java System Web Server 7.0.

The location of directories displayed by the installer are specific. However, throughout this guide and specifically in Summary of Agent Installation shown in this section, PolicyAgent-base is used to describe the directory where the distribution files are stored for a specific web agent.

The following example serves as a quick description of the location of the web agent base directory (PolicyAgent-base) of Policy Agent 2.2 for Sun Java System Web Server 7.0.

Example 4–1 Policy Agent Base Directory of Agent for Sun Java System Web Server 7.0

The following directory represents PolicyAgent-base of Agent for Sun Java System Web Server 7.0:


Agent-HomeDirectory/web_agents/sjsws_agent

where Agent-HomeDirectory is the directory you choose in which to unpack the web agent binaries.

Information regarding the location of the web agent base directory is also explained in Location of the Web Agent Base Directory in Policy Agent 2.2.

The following type of information is printed by the installer:


SUMMARY OF AGENT INSTALLATION
-----------------------------
Agent instance name: Agent_001
Agent Configuration file location:
PolicyAgent-base/Agent_001/config/AMAgent.properties
Agent Audit directory location:
PolicyAgent-base/Agent_001/logs/audit
Agent Debug directory location:
PolicyAgent-base/Agent_001/logs/debug

Install log file location:
PolicyAgent-base/logs/audit/install.log

Thank you for using Access Manager Policy Agent

Once the agent is installed, the directories shown in the preceding example are created in the Agent_00x directory, which for this example is specifically Agent_001. Those directories and files are briefly described in the following paragraphs.

PolicyAgent-baseAgent_001/config/AMAgent.properties

Location of the web agent AMAgent.properties configuration file for the agent instance. Every instance of a web agent has a unique copy of this file. You can configure this file to meet your site's requirements. For more information, see the following sections:

PolicyAgent-base/Agent_001/logs/audit

Location of the web agent local audit trail.

PolicyAgent-base/Agent_001/logs/debug

Location of all debug files required to debug an agent installation or configuration issue.

PolicyAgent-base/logs/audit/install.log

Location of the file that has the agent install file location. If the installation failed for any reason, you can look at this file to diagnose the issue.

Implications of Specific Deployment Scenarios in Agent for Sun Java System Web Server 7.0

The following sections refer to specific deployment scenarios involving Policy Agent 2.2 for Sun Java System Web Server 7.0. These scenarios are likely to affect how you respond to prompts during the installation process. You might also need to perform additional configurations.

Installing a Web Agent on Multiple Sun Java System Web Server 7.0 Instances

After you install the agent for a specific Sun Java System Web Server 7.0 instance, you can install the agent on another Web Server 7.0 instance by executing the agentadmin --install command again.

Installing Agent for Sun Java System Web Server 7.0 on the Access Manager Host

Note –

Installing Agent for Sun Java System Web Server 7.0 on the Access Manager Host is not recommended for production deployments in that performance is degraded.

To install this web agent on the Access Manager host, on the same Sun Java System Web Server 7.0 instance, add all of the URLs related to Access Manager to the not enforced URL list. Configuring the not-enforced URL list is described in Configuring the Not-Enforced URL List. If you are installing the agent on a different Sun Java System Web Server 7.0 instance, configuration of the not-enforced URL list is not required.

Verifying a Successful Installation on Policy Agent 2.2

After installing a web agent, ensure that the agent is installed successfully. Two methods are listed in this section. Perform both for best results.

ProcedureTo Verify a Successful Installation

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

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