Chapter 3 Installing Policy Agent 2.2 for Oracle Application Server 10g
Sun JavaTM System Access Manager Policy Agent 2.2 for Oracle Application Server 10g, 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:
-
Installation Related Information About Agent for Oracle Application Server 10g
-
Preparing to Install Agent for Oracle Application Server 10g
-
Launching the Installation Program of Agent for Oracle Application Server 10g
-
Using the Installation Program of Agent for Oracle Application Server 10g
Before describing any task, this chapter provides you with installation-related information specific to Oracle Application Server 10g. 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 Oracle Application Server 10g.
Installation Related Information About Agent for Oracle Application Server 10g
The following sections provide important information about Policy Agent 2.2 for Oracle Application Server 10g needed before you install the agent.
Supported Platforms and Compatibility of Agent for Oracle Application Server 10g
The following sections provide information about the supported platforms of Policy Agent 2.2 for Oracle Application Server 10g as well as the compatibility of this agent with Access Manager.
Platform and Version Support of Agent for Oracle Application Server 10g
The following table presents the platforms supported by Policy Agent 2.2 for Oracle Application Server 10g.
Table 3–1 Platform and Version Support of Agent for Oracle Application Server 10g
Compatibility of Agent for Oracle Application Server 10g With Access Manager
Compatibility of Policy Agent 2.2 With Access Manager 7
All agents in the Policy Agent 2.2 release are compatible with Access Manager 7. Compatibility applies to both of the available modes of Access Manager: Realm Mode and Legacy Mode.
Install the latest Access Manager 7 patches to ensure that all enhancements and fixes are applied. For information about the latest Access Manager 7 patches, see the compatibility information discussed in Sun Java System Access Manager Policy Agent 2.2 Release Notes.
Compatibility of Policy Agent 2.2 With Access Manager 6.3
All agents in Policy Agent 2.2 are also compatible with Access Manager 6.3 Patch 1 or greater. However, certain limitations apply. For more information, see J2EE Agent Backward Compatibility With Access Manager 6.3.
Preparing to Install Agent for Oracle Application Server 10g
Detailed information about unpacking the distribution files for J2EE agents in Policy Agent 2.2 is covered in Chapter 2, Vital Installation Information for a J2EE Agent in Policy Agent 2.2. The best practice is to follow the detailed steps outlined in that chapter before you implement any steps outlined in this chapter.
The following examples provide quick details about the unpacking process. Furthermore, this section provides the opportunity to present again the cautionary note that follows about the GNU_tar program.
Caution – For .tar.gz archives, do not use a program other than GNU_tar to untar the contents of the J2EE agent deliverables. Using a different program, such as another tar program, can result in some files not being extracted properly. To learn more about the GNU_tar program, visit the following web site:
http://www.gnu.org/software/tar/tar.html
Example 3–1 Format of the Distribution Files of Agent for Oracle Application Server 10g
SJS_Oracle_1012_agent_2.2.tar.gz SJS_Oracle_1012_agent_2.2.zip SJS_Oracle_1012_agent_2.2_SUNWamoc4j.tar.gz
For detailed information on the format of the distribution files, see Format of the Distribution Files for a J2EE Agent Installation in Policy Agent 2.2.
Example 3–2 Unpacking Non-Package Formatted Deliverables of Agent for Oracle Application Server 10g
# gzip -dc SJS_Oracle_1012_agent_2.2.tar.gz | tar xvf -
For detailed information about this command, see To Unpack Non-Package Formatted Deliverables of a J2EE Agent in Policy Agent 2.2.
Example 3–3 Unpacking Package Formatted Deliverables of Agent for Oracle Application Server 10g
# gzip -dc SJS_Oracle_1012_agent_2.2_SUNWamoc4j.tar.gz | tar xvf - |
For detailed information about this command, see To Unpack Package Formatted Deliverables of a J2EE Agent in Policy Agent 2.2.
Example 3–4 Unpacking a .zip Compressed file of Agent for Oracle Application Server 10g
unzip SJS_Oracle_1012_agent_2.2.zip
For detailed information about this command, see To Unpack a .zip Compressed file of a J2EE Agent in Policy Agent 2.2.
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.
To Prepare to Install Agent for Oracle Application Server 10g
Perform the following pre-installation tasks:
-
Ensure that Policy Agent 2.2 for Oracle Application Server 10g is supported on the desired platform as listed in Supported Platforms and Compatibility of Agent for Oracle Application Server 10g.
-
(CONDITIONAL) Install the Oracle Application Server 10g instance, if not already installed.
Visit the following link to learn more about installing Oracle Application Server 10g: http://www.oracle.com/technology/software/products/ias/index.html. Refer to the appropriate documentation as necessary. If you install the Oracle Application Server 10g instance at this time, ensure that you use the fully qualified host name as described in the following step.
-
Ensure that the Oracle Application Server 10g instance is installed with the fully qualified host name.
The Oracle Application Server 10g instance gets installed with the fully qualified host name when the installation program is started with the following command-line parameter:
./runInstaller OUI_HOSTNAME=fully-qualified-host-name
Caution – If a fully qualified host name was not provided during installation, the front-end Apache web server will be configured with the wrong host name in the httpd.conf file. This file contains the variable ServerName. For this file is to be configured correctly, the value associated with the variable ServerName must be a fully qualified host name. If a fully qualified host name is not used, a problem can arise where the agent issues an unlimited self-direct.
Perform steps such as the following substeps to ensure that the Oracle Application Server 10g instance is configured with a fully qualified host name.
-
Using the text editor of your choice, access the following file:
DeployContainer-base/Apache/Apache/conf/httpd.conf
where DeployContainer-base represents the directory within which the Oracle Application Server 10g instance was installed.
-
(CONDITIONAL) If the value for ServerName is not the fully qualified host name, change the value to the fully qualified host name.
-
-
Ensure that the Oracle Application Server 10g instance is shut down.
Since the J2EE agent installer changes some of the configuration files in the Oracle Application Server 10g instance, the server should not be running during the agent installation process.
The following substeps, which include the issuance of two commands, serve as an example of how to shut down an Oracle Application Server 10g instance, where DeployContainer-base represents the directory within which the Oracle Application Server 10g instance was installed.
-
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 ownership and group settings for the files in the am_oracle_1012_agent directory are correct.
Therefore, if necessary, change the ownership of all the files in the am_oracle_1012_agent directory to the Oracle Application Server 10g installation user and change the group associated with these files to the same group associated with the Oracle Application Server 10g installation user.
The following is the full path to the am_oracle_1012_agent directory:
Agent-HomeDirectory/j2ee_agents/am_oracle_1012_agent
where Agent-HomeDirectory is the directory you choose in which to unpack the J2EE agent binaries. For more information about J2EE agent directory structure, including Agent-HomeDirectory, see J2EE Agent Directory Structure in Policy Agent 2.2.
The following list provides default values for the Oracle Application Server 10g installation user.
- Default Oracle Application Server 10g installation user:
-
oracle
- Default group of the Oracle Application Server 10g installation user:
-
oinstall
Caution – For the agent installation to be successful, the Oracle Application Server 10g installation user must have ownership of the files in the am_oracle_1012_agent directory and this same user must issue the agent installation command, as described subsequently. Otherwise, the installation can appear successful, but when end users access a protected resource, the browser might issue the following error: NoClassDefFoundError.
This step is necessary since you cannot install this agent as user root. As indicated, instead, install this agent as the Oracle Application Server 10g installation user.
Launching the Installation Program of Agent for Oracle Application Server 10g
Once you have performed all the pre-installation steps, you can launch the installation program as described in the following subsection.
To Launch the Installation Program of Agent for Oracle Application Server 10g
Caution – Do not install Agent for Oracle Application Server 10g as user root.
For the agent installation to be successful, the Oracle Application Server 10g installation user must issue the agent installation command and this same user must have ownership of the files in the am_oracle_1012_agent directory, as described previously. Otherwise, the installation can appear successful, but when end users access a protected resource, the browser might issue the following error: NoClassDefFoundError.
To launch the installation program, perform the following steps:
-
Log in to the system as the Oracle Application Server 10g installation user.
-
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.
Using the Installation Program of Agent for Oracle Application Server 10g
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.
About Installation Prompts in Agent for Oracle Application Server 10g
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
-
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.
- The port number of Application Server
-
The port number referred to in this prompt is not the OC4J port number, but the Apache server port. The default port number is 7777 on UNIX-based systems and 80 on Windows systems.
Caution – Pay attention to the port number being requested by the following prompt: Enter the preferred port number on which the application server provides its services. Entering the OC4J port number results in a misconfiguration.
- The Encryption Key
-
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.
- 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 Oracle Application Server 10g. 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
-
The J2EE password file should have been created as a pre-installation step. For the pre-installation steps, see Preparing to Install Agent for Oracle Application Server 10g.
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.
Example of Installation Program Interaction in Agent for Oracle Application Server 10g
The following example is a sample installation snapshot of Policy Agent 2.2 for Oracle Application Server 10g. By no means does this sample represent a real deployment scenario.
The section following this example, Implications of Specific Deployment Scenarios in Agent for Oracle Application Server 10g, explains specific deployment scenario involving the installation of multiple J2EE agent instances. If such a scenario applies to your deployment, review that section before proceeding with the installation.
Caution – Though the information in this note has already been presented in this guide, it is being repeated because of its importance. During the installation of this agent, pay attention to the port number being requested with the following prompt: Enter the preferred port number on which the application server provides its services. Entering the OC4J port number results in a misconfiguration. Instead, enter the Apache server port number. By default, this port number is 7777 on UNIX-based systems and 80 on Windows systems.
************************************************************************
Welcome to the Access Manager Policy Agent for Oracle10g 10.1.2. 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 Oracle10g OC4J to
store its configuration Files. This directory uniquely identifies the
Oracle10g OC4J instance that is secured by this Agent.
[ ? : Help, ! : Exit ]
Enter the Oracle10g OC4J Config Directory Path
[/opt/oracle/OraHome_1012/j2ee/home/config]: /opt/oracle/OraJ2EE_1012/j2ee/home/
config
Enter the name of the global application.xml
[ ? : Help, < : Back, ! : Exit ]
Enter the name of the global application.xml [application.xml]:
Press Enter
Enter the fully qualified host name of the server where Access Manager
Services are installed.
[ ? : Help, < : Back, ! : Exit ]
Access Manager Services Host: host1.subdomain.domain.com
Enter the port number of the Server that runs Access Manager Services.
[ ? : Help, < : Back, ! : Exit ]
Access Manager Services port [80]: 58080
Enter http/https to specify the protocol used by the Server that runs Access
Manager services.
[ ? : Help, < : Back, ! : Exit ]
Access Manager Services Protocol [http]:
Press Enter
Enter the Deployment URI for Access Manager Services.
[ ? : Help, < : Back, ! : Exit ]
Access Manager Services Deployment URI [/amserver]:
Press Enter
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: host2.subdomain.domain.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 [7777]: 7779
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]:
Press Enter
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]:
Press Enter
Enter a valid Encryption Key.
[ ? : Help, < : Back, ! : Exit ]
Enter the Encryption Key [Nh7wAmL8/XJks33/npM6SwoinIL8Vk0a]:
Press Enter
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: agent1
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: /tmp/password.txt
*********************************************************
SUMMARY OR YOUR RESPONSES
*********************************************************
Oracle10g OC4J instance Config Directory :
/opt/oracle/OraJ2EE_1012/j2ee/home/config
Oracle10g OC4J instance-level application.xml : application.xml
Access Manager Services Host : host1.subdomain.domain.com
Access Manager Services Port : 58080
Access Manager Services Protocol : http
Access Manager Services Deployment URI : /amserver
Agent Host name : host2.subdomain.domain.com
Application Server Instance Port number : 7779
Protocol for Application Server instance : http
Deployment URI for the Agent Application : /agentapp
Encryption Key : Nh7wAmL8/XJks33/npM6SwoinIL8Vk0a
Agent Profile name : agent1
Agent Profile Password file name : /tmp/password.txt
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]
|
Agent Version and Property Configuration: Agent for Oracle Application Server 10g
The instructions presented in this section related to editing the J2EE agent AMAgent.properties configuration file are required for the initial version of Agent for Oracle Application Server 10g. Updated versions of the agent do not require the performance of these configuration instructions. Starting with Policy Agent 2.2 hot patch 4, the configuration instructions presented in this section should not be performed. If you are not certain of the version of this agent, perform the following task about checking the agent version.
To Check the Specific Version of Agent for Oracle Application Server 10g
Next Steps
The preceding command results in the agent issuing version information. If the version indicated is a version prior to hot patch 4, then perform the task that follows. If the version is hot patch 4 or greater, skip the task that follows.
(Conditional) To Configure the J2EE agent AMAgent.properties Configuration File
-
Using the text editor of your choice, access the J2EE agent AMAgent.properties configuration file.
-
Edit the following property as such:
java.util.logging.config.file = PolicyAgent-base/config/AMAgentLogConfig.properties
The property was originally set as follows:
java.util.logging.config.file = PolicyAgent-base/agent_001/config/AMAgentLogConfig.properties
where agent_001 serves as an example that might be different in your situation depending upon the number of agents that have been installed on the machine.
Editing the value for this property involves the removal of the following string “agent_001/”
-
Add the following property and value to the bottom of the configuration file:
com.sun.identity.agents.config.composite.advice.file = PolicyAgent-base/locale/CompositeAdviceForm.txt
-
Save and close the updated J2EE agent AMAgent.properties configuration file.
Implications of Specific Deployment Scenarios in Agent for Oracle Application Server 10g
The following section refers to a specific deployment scenario involving multiple instances of Policy Agent 2.2 for Oracle Application Server 10g.
Installing a J2EE Agent on Multiple Oracle Application Server 10g Instances
Once a J2EE agent is installed for a particular Oracle Application Server 10g instance, you can install the agent on another instance on the same machine by running the agentadmin --install command.
Summary of a J2EE 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 J2EE agent information. The information that the program displays can be very useful. For example, the program displays the agent instance name, which is required 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 Oracle Application Server 10g.
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 Oracle Application Server 10g.
Example 3–5 Policy Agent Base Directory of Agent for Oracle Application Server 10g
The following directory represents PolicyAgent-base of Agent for Oracle Application Server 10g:
Agent-HomeDirectory/j2ee_agents/am_oracle_1012_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.
- PolicyAgent-base/agent_001/config/AMAgent.properties
-
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:
- PolicyAgent-base/agent_001/logs/audit
-
Location of the J2EE 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.
- © 2010, Oracle Corporation and/or its affiliates