Sun JavaTM System Access Manager Policy Agent 2.2 for SAP Enterprise Portal 7.0/Web Application Server 7.0, as with all J2EE agents in the 2.2 release of Policy Agent, is installed from the command line using the agentadmin program. For more information about the tasks you can perform with the agentadmin program, see Role of the agentadmin Program in a J2EE Agent for Policy Agent 2.2.
Before reading this chapter or performing any of the tasks described within, thoroughly review Chapter 2, Vital Installation Information for a J2EE Agent in Policy Agent 2.2 since various key concepts are introduced in that chapter.
This chapter is organized into the following sections:
Preparing to Install Agent for SAP Enterprise Portal 7.0/Web Application Server 7.0
Launching the Installation Program of Agent for SAP Enterprise Portal 7.0/Web Application Server 7.0
Using the Installation Program of Agent for SAP Enterprise Portal 7.0/Web Application Server 7.0
Before describing any task, this chapter provides you with installation-related information specific to SAP Enterprise Portal 7.0/Web Application Server 7.0. The subsequent sections lead you through the pre—installation and installation steps and describe how to view the installation log files. First, perform the pre-installation (preparation) steps. Then, perform the installation, itself. 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.
Once you have completed the steps described in this chapter, complete the applicable post-installation tasks described in Chapter 4, Post-Installation Tasks of Policy Agent 2.2 for SAP Enterprise Portal 7.0/Web Application Server 7.0.
The following sections provide important information about Policy Agent 2.2 for SAP Enterprise Portal 7.0/Web Application Server 7.0 needed before you install the agent.
The following sections provide information about the supported platforms of Policy Agent 2.2 for SAP Enterprise Portal 7.0/Web Application Server 7.0 as well as the compatibility of this agent with Access Manager.
The following table presents the platforms supported by Policy Agent 2.2 for SAP Enterprise Portal 7.0 and Web Application Server 7.0 (SAP Enterprise Portal 7.0/Web Application Server 7.0).
Table 3–1 Platform and Version Support of Agent for SAP Enterprise Portal 7.0/Web Application Server 7.0
Agent for |
Supported Policy Agent Version |
Supported Access Manager Versions |
Supported Platforms |
---|---|---|---|
SAP Enterprise Portal 7.0 and Web Application Server 7.0 (SAP Enterprise Portal 7.0/Web Application Server 7.0) |
Version 2.2 |
Version 7 Version 7.1 |
SolarisTM Operating System (OS) for the SPARC® platform, version 9 and 10 AIX 5L Windows 2003, Enterprise Edition, 32 bit Windows 2003, Standard Edition, 32 bit |
All agents in the Policy Agent 2.2 release are compatible with Access Manager 7 and Access Manager 7.1. Compatibility applies to both of the available modes of Access Manager: Realm Mode and Legacy Mode.
Install the latest Access Manager patches to ensure that all enhancements and fixes are applied. For an example of Access Manager patches that can be installed, see the compatibility information discussed in Sun Java System Access Manager Policy Agent 2.2 Release Notes.
While most agents in the Policy Agent 2.2 software set are also compatible with Access Manager 6.3, Agent for SAP Enterprise Portal 7.0/Web Application Server 7.0 is not compatible with Access Manager 6.3.
These agent binaries are available in .zip file format only. The example that follows provides details about the unpacking process.
You must unpack the .zipfile as the SAP Instance User, SIDadm, in a directory owned by this user. Where SID is a place holder that represents the SAP system ID.
Do not perform this action as the root user. Furthermore, after unpacking the binaries, give execution permissions to the agentadmin utility, which is in the PolicyAgent-base/bin directory. For example:
chmod +x PolicyAgent-base/bin/agentadmin
Always issue the agentadmin utility as the SAP Instance User, SIDadm.
For more information, see , To Prepare to Install Agent for SAP Enterprise Portal 7.0/Web Application Server 7.0.
unzip sap_v7_agent.zip
Follow the specific steps outlined in the following section before you install the agent to reduce the chance of complications occurring during and after the installation.
Perform the following pre-installation tasks:
Ensure that the Policy Agent 2.2 for SAP Enterprise Portal 7.0/Web Application Server 7.0 is supported on the desired platform as listed in Supported Platforms and Compatibility of Agent for SAP Enterprise Portal 7.0/Web Application Server 7.0.
Install SAP Enterprise Portal 7.0/Web Application Server 7.0 if not already installed.
Ensure that the SAP Enterprise Portal 7.0/Web Application Server 7.0 instance that will be protected by the agent is not running.
Create a valid agent profile in Access Manager Console if one has not already been created.
For information on how to create an agent profile, see Creating a J2EE Agent Profile.
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.
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.
Ensure that the agentadmin utility has execution permissions
The following command is an example of how you can add execution permissions for this utility:
chmod +x PolicyAgent-base/bin/agentadmin
Always issue the agentadmin utility as the SAP Instance User, SIDadm.
Once you have performed all the pre-installation steps, you can launch the installation program as described in the following subsection.
On UNIX-based systems, execute the agent installer as the SAP administrative user, such as j2eadm. Never run the installation script as root or any other user. If you run the installer as a user besides the SAP administrative user, problems can occur in the configuration, which could prevent SAP Enterprise Portal 7.0/Web Application Server 7.0 from starting.
To launch the installation program, perform the following steps:
Change to the following directory:
PolicyAgent-base/bin |
This directory contains the agentadmin program, which is used for installing a J2EE agent and for performing other tasks. For more information on the agentadmin program, see Role of the agentadmin Program in a J2EE Agent for Policy Agent 2.2.
Issue the following command:
./agentadmin --install |
(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.
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.
Each step in the installation program includes an explanation that is followed by a more succinct prompt.
For most of the steps you can type any of the following characters to get the results described:
Type the question mark to display Help information for that specific step.
Type the left arrow symbol to go back to the previous interaction.
Type the exclamation point to exit the program.
Most of the steps provide a default value that can be accepted or replaced. If a default value is correct for your site, accept it. If it is not correct, enter the correct value.
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 issuing the agentadmin --install command.
The deployment URI for the agent application is required for the agent to perform necessary housekeeping tasks such as registering policy and session notifications, legacy browser support, and CDSSO support. Accept /agentapp as the default value for this interaction. Once the installation is completed, browse the directory PolicyAgent-base/etc. Use the agentapp.war file to deploy the agent application in the application container. Please note that the deployment URI for agent application during install time should match the deployment URI for the same application when deployed in the J2EE container.
This key is used to encrypt sensitive information such the passwords. The key should be at least 12 characters long. A key is generated randomly and provided as the default. You can accept the random key generated by the installer or create your own using the .agentadmin --getEncryptKey command.
For information about creating a new encryption key, see agentadmin --getEncryptKey.
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 SAP Enterprise Portal 7.0/Web Application Server 7.0. For the actual information on creating an agent profile, see Creating a J2EE Agent Profile.
In summary, the J2EE agent communicates with Access Manager with a specific ID and password created through an agent profile using Access Manager Console. For J2EE agents, the creation of an agent profile is mandatory. Access Manager uses the agent profile to authenticate an agent. This is part of the security infrastructure.
The J2EE password file should have been created as a pre-installation step. For the pre-installation steps, see Preparing to Install Agent for SAP Enterprise Portal 7.0/Web Application 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.
If you are satisfied with the summary, choose 1 (the default).
If you want to edit input from the last interaction, choose 2.
If you want to edit input starting at the beginning of the installation program, choose 3.
If you want to exit the installation program without installing, choose 4.
You can edit your responses as necessary, return to the options list, and choose option 1 to finally process your responses.
The following example is a sample installation snapshot of Policy Agent 2.2 for SAP Enterprise Portal 7.0/Web Application Server 7.0. By no means does this sample represent a real deployment scenario.
The section following this example, Implications of Specific Deployment Scenarios in Agent for SAP Enterprise Portal 7.0/Web Application Server 7.0, explains specific deployment scenarios, such as installing the agent on a Web Application Server (WebAS) domain. If any of these deployment scenarios apply to your deployment, you might need to respond to prompts in a specified manner during the installation as explained in that section. Review the explanations in that section before proceeding with the installation. Those explanations are divided into subsections as follows:
Installing Agent for SAP Enterprise Portal 7.0/Web Application Server 7.0 in a Clustered Environment
************************************************************************ Welcome to the Access Manager Policy Agent for SAP WebAS and Enterprise Portal ************************************************************************ Enter the complete path to the directory of your SAP server ID. This directory uniquely identifies the SAP instance that is secured by this Agent. [ ? : Help, ! : Exit ] Enter the SAP Server <SID> Directory Path [/usr/sap/J2E/JC00/j2ee/cluster/server0]: Enter true if the agent is being installed on a WebAS domain. Enter true only if the agent is installed on WebAS domain. CAUTION : Entering a wrong value will result in the failure of the installation process. [ ? : Help, < : Back, ! : Exit ] Is the agent being installed on a WebAS domain ? [false]: Enter the fully qualified host name of the server where Access Manager Services are installed. [ ? : Help, < : Back, ! : Exit ] Access Manager Services Host: subcompany22.company22.example.com Enter the port number of the Server that runs Access Manager Services. [ ? : Help, < : Back, ! : Exit ] Access Manager Services port [80]: 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 Application Server protected by the agent is installed. [ ? : Help, < : Back, ! : Exit ] Enter the Agent Host name: Enter the fully qualified host name on which the Application Server protected by the agent is installed. [ ? : Help, < : Back, ! : Exit ] Enter the Agent Host name: employee.company22.example.com Enter the preferred port number on which the application server provides its services. [ ? : Help, < : Back, ! : Exit ] Enter the port number for Application Server instance [80]: Select http or https to specify the protocol used by the Application server instance that will be protected by Access Manager Policy Agent. [ ? : Help, < : Back, ! : Exit ] Enter the Preferred Protocol for Application Server instance [http]: Enter the deployment URI for the Agent Application. This Application is used by the agent for internal housekeeping. [ ? : Help, < : Back, ! : Exit ] Enter the Deployment URI for the Agent Application [/agentapp]: Enter a valid Encryption Key. [ ? : Help, < : Back, ! : Exit ] Enter the Encryption Key [UuFkSS0bpli/rY/KqYrGjd6ISaRIQEjT]: 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: exampleagent 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: /export/temp/passwordfile ----------------------------------------------- SUMMARY OF YOUR RESPONSES ----------------------------------------------- SAP <SID> Directory : /usr/sap/J2E/JC00/j2ee/cluster/server0 Agent Installed on WebAS domain : false Access Manager Services Host : subcompany22.company22.example.com Access Manager Services Port : 80 Access Manager Services Protocol : http Access Manager Services Deployment URI : /amserver Agent Host name : employee.company22.example.com Application Server Instance Port number : 80 Protocol for Application Server instance : http Deployment URI for the Agent Application : /agentapp Encryption Key : UuFkSS0bpli/rY/KqYrGjd6ISaRIQEjT Agent Profile name : agent2.2 Agent Profile Password file name : /export00/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]: |
The following sections refer to specific deployment scenarios involving Policy Agent 2.2 for SAP Enterprise Portal 7.0/Web Application 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.
During installation, you are prompted about the domain on which you are installing the agent. The installer configures the installation differently depending upon the deployment container to which the domain is associated: SAP Web Application Server 7.0 or SAP Enterprise Portal 7.0.
The two deployment containers each require that you perform specific post-installation tasks as described in Chapter 4, Post-Installation Tasks of Policy Agent 2.2 for SAP Enterprise Portal 7.0/Web Application Server 7.0.
As shown in the following task description, to install this agent on a Web Application Server 7.0 (WebAS) domain, enter true when prompted. If you are installing the agent on an Enterprise Portal 7.0 domain, do not change this value from its default value of false.
The prompt shown in this procedure appears in the agent installation program, which is described in Example of Installation Program Interaction in Agent for SAP Enterprise Portal 7.0/Web Application Server 7.0.
Enter true to the following prompt:
Enter true if the agent is being installed on a WebAS domain [ ? : Help, < : Back, ! : Exit ] Is the agent being installed on a WebAS domain ? [true]:
One instance of Agent for SAP Enterprise Portal 7.0/Web Application Server 7.0 protecting the SAP Enterprise Portal 7.0 application in addition to another instance running on Web Application Server 7.0 is a supported configuration, however the installation process differs slightly. For example, if you first run the installation program on the SAP Enterprise Portal 7.0 application, you are not required to run the installation program again on the Web Application Server 7.0 instance. Also, you will only be able to configure one config and locale class path in the SAP J2EE configuration tool.
If you are installing the agent on an SAP Enterprise Portal 7.0 domain before installing the agent on an SAP Web Application Server 7.0 domain, follow the instructions for installation and post-installation of SAP Enterprise Portal 7.0 as provided in this guide. You can then configure the second agent instance for SAP Web Application Server 7.0 also following the post-installation task descriptions in this guide, but specifically for SAP Web Application Server 7.0.
To create a cluster in your SAP environment, you can either add additional dialogue instances to the central instance or add additional server processes to your existing central instance. Obtain information on setting up such a cluster at http://help.sap.com/.
Whether your cluster consists of multiple dialogue instances with one or more server processes, or multiple server processes for a central instance, you will need to perform the agent installation process on each server node that you would like the agent to protect. For example the following path represents server0 on the central instance:
/usr/sap/J2E/JC03/j2ee/cluster/server0
And the following path represents server1 on the dialog instance:
/usr/sap/J2E/J04/j2ee/cluster/server1
For the preceding examples, you must provide the corresponding directory structure to the first agent installation interaction. Similarly, on each node, you must deploy the agent application as described in To Deploy the agentapp.war file for SAP Enterprise Portal 7.0/Web Application Server 7.0.
At the end of the installation process, the installation program prints the status of the installation along with the installed J2EE agent information. The information that the program displays can be very useful. For example, the program displays the agent instance name, which is needed when configuring a remote instance. 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 4, Post-Installation Tasks of Policy Agent 2.2 for SAP Enterprise Portal 7.0/Web Application 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 J2EE agent.
The following example serves as a quick description of the location of the J2EE agent base directory (PolicyAgent-base) of Policy Agent 2.2 for SAP Enterprise Portal 7.0/Web Application Server 7.0.
The following directory represents PolicyAgent-base of Agent for SAP Enterprise Portal 7.0/Web Application Server 7.0:
Agent-HomeDirectory/j2ee_agents/sap_v7_agent |
where Agent-HomeDirectory is the directory you choose in which to unpack the J2EE agent binaries.
Information regarding the location of the J2EE agent base directory is explained in detail in Location of the J2EE 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.
Location of the J2EE agent AMAgent.properties configuration file for the agent instance. Every instance of a J2EE 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:
Location of the J2EE agent local audit trail.
Location of all debug files required to debug an agent installation or configuration issue.
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.