Chapter 4 Tools and APIs

J2EE Policy Agents provide tools and APIs that can be used to better manage your system and create security-aware applications.

This chapter describes the tools as well as APIs provided by the agents. Topics in this chapter include:

Agent Tools

Agent APIs

Agent Tools

The agent tools allow you to encrypt plain text strings, which may be required when changing various passwords and also allow you to configure the agent for new application server instances where supported.

The agent tools can be used by invoking the tool script provided by the agent. This script is located in the directory bin directory of agent installation. On Solaris, HP-UX and AIX platforms, this script is called agentadmin and on Windows platform it is called agentadmin.bat.

When invoked at a shell prompt from the bin directory of the agent installation, this script displays the usage of the tools as follows:

Currently the tools support the following functionality: encryption, configuration and unconfiguration.

Using Tools to Encrypt Strings


Note	The configure and unconfigure options of the agent tools script are not supported for IBM WebSphere Application Server 5.0/5.1 agent. In order to manually configure a new instance of IBM WebSphere Application Server 5.0/5.1, you can refer to the steps described in the section "Agent for IBM WebSphere Application Server 5.0/5.1 Instance" and to unconfigure an instance, refer to the section Agent for IBM WebSphere Application Server 5.0/5.1 Instance.

In order to encrypt a string, simply invoke the agent tools with the -encrypt option as shown here and provide the necessary string that needs to be encrypted. The agent tools will then display the text of the encrypted string.

Configuring the Agent for an Application Server Instance

Once you have installed a policy agent for a particular application server, the agent installation program will not allow you to install the same agent again unless the previous installation has been completely removed from your system. In order to overcome this limitation, you may use the agent tools to configure the agent for another application server instance.

The following steps describe how the agent can be configured for a new instance of an application server using the agent tools.


Note	The configure and unconfigure options of the agent tool are not supported for IBM WebSphere Application Server 5.0/5.1 agent. In order to manually configure the agent for a new instance of IBM WebSphere Application Server 5.0/5.1, you can refer to the steps described in the section Agent for IBM WebSphere Application Server 5.0/5.1 Instance and to unconfigure an instance, refer to the section Agent for IBM WebSphere Application Server 5.0/5.1 Instance. For every application deployed on any instance of the application server that is protected by the agent, you must ensure that the agent filter has been added and appropriate changes to the deployment descriptors have been made to enable web-tier declarative security as needed. Refer to the section on Enabling Web-Tier Declarative Security for further details.

These steps are divided into some common steps that apply to all the agents, followed by steps specific to an agent. After performing the steps outlined in the following section Common Configuration Steps, you may jump to the section relevant to the agent you want to configure.

Common Configuration Steps

The following steps are common to all the agents. After you have completed these steps, you must perform the configuration tasks specific to your agent, which are covered in the next sections.


Note	At any time when using the agent tools to configure a new server instance, you may select the default value shown in brackets [] by pressing the Enter key at the prompt.


Note	If you are configuring the agent for a server instance of Macromedia JRun 4, you must first stop the instance and then start the configuration.

From the bin directory of the agent installation, invoke the agent tool script as follows:

#./agentadmin -configure

On Windows platform, use this command:

agent_install_dir\IdentityServer\j2ee_agents\bin> agentadmin -configure

At the following prompt, enter the protocol for the application server instance being configured.

Server Instance Preferred Protocol ('http' or 'https') [http]?:

At the following prompt, enter the port for the application server instance being configured.

Server Instance listening port [80]?:

At the following prompt, enter the context path for the primary application deployed on this instance of application server.

Primary Application Context Path [/]?:

Enter the value for access denied URI that will be used by the agent for this instance of application server to blocking unauthorized requests.

Access Denied URI []?:

You may leave this value empty, in which case the agent will use the HTTP status code 403 to respond to unauthorized access requests.

Enter the value for agent operation mode from the valid set of choices as displayed by the agent tools:

Agent instance Filter Mode ('NONE', 'SSO_ONLY', 'URL_POLICY', 'J2EE_POLICY', 'ALL') [ALL]?:



Note	When the agent is configured for a new instance of the application server, the agent tools use the same user name and group name as specified during the actual installation to set the appropriate permissions for the debug and configuration directories. If this is not applicable, you must manually reset these permissions to the appropriate owner of the new application server instance process.

The information you have entered so far has been common to agents for all application servers that support the configure option. However, the next set of information is specific to each type of application server agent. Please jump to the relevant section to continue with the application server instance configuration.

Agent for Sun ONE Application Server 7.0

After you have completed the steps outlined in the Common Configuration Steps section, the agent tool will prompt you for information specific to the Sun ONE Application Server 7.0 instance that is being configured. Follow these steps:

At the following prompt, enter the location of the config directory for the application server instance that is being configured:

Enter the Sun ONE Application Server instance config Directory?:

At the following prompt, enter the port number where Sun ONE Application Server Administration Server is available. Make sure that the administration server is running when doing this configuration:

Enter Sun ONE Application Server Administrative Server port [4848]?:

At the following prompt, enter the user name for the Administrator of Sun ONE Application Server.

Enter Sun ONE Application Server Administrative User Name [admin]?:

At the following prompt, enter the password for the Administrator of Sun ONE Application Server:

Enter Sun ONE Application Server Administrative User Password?:

At the following prompt, re-enter the password for the Administrator of Sun ONE Application Server:

Reenter Sun ONE Application Server Administrative User Password?:

If the information entered is valid, the agent tools configure the Application Server instance. On completion of this task, prior to the program exiting, the tools display the following message indicating status:

Agent Configured Successfully for Application Server Instance.

Agents for BEA WebLogic Server (All Versions)

BEA WebLogic Server 6.1 SP2,

BEA WebLogic Server 7.0 SP2 or BEA WebLogic Server 8.1

BEA WebLogic 8.1 SP2/SP3 Server/Portal

The agent tools will prompt you for information specific to the WebLogic server instance after you have completed the steps outlined in the Common Configuration Steps section.

At the following prompt, enter the location of the startup script that is used to launch this instance of WebLogic Server or Portal:

If the information entered is valid, the agent tools proceed to configure the instance of the application server. When the configuration is complete, the tools display a message indicating the status of the task. The program then exits and this message is displayed:

Agent for IBM WebSphere Application Server 5.0/5.1 Instance


Note	If the BEA WebLogic Server instance that has been configured is outside the domain in which the agent was installed, you must complete the post-installation tasks for the respective server instance as mentioned in the Post-Installation Tasks section in Chapter 2, Installing the Agent.

The agent tools do not support the configure option for IBM WebSphere Application Server 5.0/5.1 instances. However, the following list of steps allow you to manually configure an agent for a new instance of the application server:

Create a new directory for storing the agent configuration for the new instance of the application server under the agent configuration root directory. On Solaris platform, the agent configuration root directory is in the path /etc/opt/SUNWam/j2ee_agents/am_was50_agent/config. On other platforms, this directory is under Agent_Install_Dir/IdentityServer/j2ee_agents/config directory. Make sure that this is a unique directory that will not be used by any other instance of the application server other than the one being configured.

The rest of the steps will refer to this directory as the new configuration directory.

Under the new configuration directory, create a directory called ums for storing Sun ONE Identity Server’s Directory server configuration file serverconfig.xml.

From the configuration directory of the previously installed agent, copy the files AMAgent.properties and SSOConfig.properties to the new configuration directory.

From the directory config/ums of the previously installed agent, copy the serverconfig.xml file to the ums directory created under the new configuration directory.

Create a new directory for storing the agent audit and debug logs for the new instance of the application server under the agent log root directory. On Solaris platform, the agent log root directory is in the path /var/opt/SUNWam/j2ee_agents/am_was50_agent. On other platforms, this directory is under Agent_Install_dir/IdentityServer/j2ee_agents/logs directory. Make sure that this is a unique directory that will not be used by any other instance of the application server other than the one being configured. The rest of the steps will refer to this directory as the new log directory.

Under the new log directory, create two directories named audit and debug.

Using the IBM WebSphere Application Server 5.0/5.1 Administrative Console, create a new instance of the application server as a clone of the instance for which the agent has been already installed. To do this, go to Servers and then Application Servers and click the New button. Now select the Existing application server radio button, enter a name for the new server instance and click Next.

Once the new server instance has been created, navigate to Advance Java virtual machine setting page for the new Server instance by following the links as Application Servers > <new server name> > Process Definition > Java Virtual Machine.

On this form, under the classpath properties, modify the classpath entry that points to the old instance’s config directory and replace it with the new config directory created in step 1.

On the same form, under the Generic JVM Arguments, modify the existing arguments and replace the value of the parameter -Dcom.iplanet.coreservices.configpath with the complete path to the ums directory created under the new config directory in step 2. Also, replace the value of the parameter -Djava.util.logging.config.file with the complete path to the new AMAgent.properties file created in step 3.

Save your changes in the IBM WebSphere Application Server 5.0/5.1 Administration console.

Before restarting the server, modify the AMAgent.properties file created under the new config directory and set the values for the following properties:

com.sun.am.policy.amFilter.port.check.map

Set the port and protocol used by this instance of the application server.

com.sun.am.policy.amAgentLog.local.file

Set the path of a file that will reside in the audit directory created under the new log directory in step 6.

com.iplanet.services.debug.directory

Set the path of the debug directory created under the new log directory in step 6.

com.iplanet.am.notification.url

Set the notification URL with the appropriate port and protocol and make sure that the URI for this begins with the context path of the primary application that will be deployed on this instance.

com.sun.identity.agents.notification.url

Set the notification URL with the appropriate port and protocol and make sure that the URI for this begins with the context path of the primary application that will be deployed on this instance.

Refer to the section on AMAgent.properties Reference for details regarding these property keys.

Restart the WebSphere Application Server instance.

Agent for PeopleSoft 8.3/8.4/8.8

If you are configuring the agent for PeopleSoft 8.3/8.4/8.8, the agent tools will prompt you for information specific to the PeopleSoft application server instance after you have completed the steps outlined in the Common Configuration Steps section. Follow these steps:

At the following prompt, enter the PeopleSoft application version on which you are going to configure the agent.

Enter the PeopleSoft application version (’8.3’ or ’8.4’ or ’8.8’) [8.3] ?:

At this prompt, enter the mode in which you want to deploy the agent.

Enter one of the Agent Deployment options (’redeploy’ or ’proxy’) [redeploy] ?:

At this prompt, type true if you have PeopleSoft Application Server installed locally. Else, type false.

PeopleSoft Application Server installed locally (’true’ or ’false’) [true] ?:

At this prompt, type true if you have BEA WebLogic Server installed locally. Else, type false.

WebLogic Server installed locally (’true’ or ’false’) [true]?:

At this prompt, enter the full path to the directory where the PeopleSoft Application Server is installed. For example, PS_HOME/appserv

Enter PeopleSoft AppServer Directory [/export/home/psft/appserv] ?:

At this prompt, enter the PeopleSoft domain that this agent will protect. For example, HDMO.

Enter PeopleSoft Domain Name [HDMO] ?:

At this prompt, enter the full path to the WebLogic instance directory. For example, PS_HOME/weblogic/myserver or BEA_HOME/wlserver6.1/config/peoplesoft

Enter WebLogic instance Directory [/export/home/psft/weblogic/myserver] ?:

At this prompt, enter the system user ID used to install PeopleSoft software. For example, psft

Enter PeopleSoft user ID [psft] ?:

At this prompt, enter the primary group of the PeopleSoft user. For example, sys

Enter PeopleSoft user’s primary group [other] ?:

At this prompt, enter the complete path to the directory containing the JRE used by the application server.

Enter Directory containing JRE used by PeopleSoft?:

At this prompt, enter true if the Sun JCE provider needs to be installed on the JDK. Else, enter false.

Install JCE for this (’true’ or ’false’) [true] ?:

At this prompt, enter true if the Sun JSSE provider needs to be installed on the JDK. Else, enter false.

Install JSSE for this (’true’ or ’false’) [true] ?:

At this prompt, enter the generic PeopleSoft user ID that the web server uses to identify itself to the application server. For example, DEFAULT_USER.

Enter PeopleSoft DEFAULT_USER [DEFAULT_USER] ?:

At this prompt, enter the PeopleSoft DEFAULT_USER password assigned while creating the DEFAULT_USER.

Enter PeopleSoft DEFAULT_USER Password?:

At this prompt, reenter the PeopleSoft DEFAULT_USER password.

Re-enter Password?:

At this prompt, enter the name of the PIA site, as given during PeopleSoft installation. For example, peoplesoft8.

Enter Name of the PIA Site?:

At this prompt, enter the name of the PIA web application as given during PeopleSoft installation. For example, PORTAL.

Name of the PIA web application ?:

If the information entered is valid, the agent tools will now proceed to configure the instance of the application server. Once this is completed, the tools will display a message indicating the status of the task and the program will exit:

Agent Configured Successfully for Application Server Instance.

Agent for Apache Tomcat Server 4.1.27

After you have completed the steps outlined in the section Common Configuration Steps, the agent tools will prompt you for information specific to the Tomcat Server instance that is being configured.

At the following prompt, enter the location of the configuration directory of the Tomcat Server instance that is being configured:

Enter complete path to the configuration directory of the Tomcat Server Instance?:

At the following prompt, enter true if you want to install the agent filter in the global deployment descriptor (web.xml). If however, you want to add the filter individually to the application deployment descriptors, enter false.

Filter installed in global web.xml (’true’ or ’false’)?:

If the information entered is valid, the agent tools will now proceed to configure the instance of the Tomcat Server. Once this operation is completed, the agent tools will display a message indicating the status of the task and the program will exit:

Agent Configured Successfully for Application Server Instance.



Note	Automatic reconfiguration of the web applications admin and manager to work with the agent is not supported on any Tomcat Server instance other than the default. The default instance is the first Tomcat Server instance configured after the agent was installed. However, if you have installed the agent filter in your global deployment descriptor (web.xml), you may be able to configure these web applications to work with the default instance and the new instance of the agent (that you are configuring using agentadmin) just like any other web application. Please see the following documents for more information on Tomcat server administration and configuration: http://jakarta.apache.org/tomcat/tomcat-4.1-doc http://jakarta.apache.org/tomcat/tomcat-4.1-doc/manager-howto.html

Agent for Macromedia JRun 4

After you have completed the steps outlined in the section Common Configuration Steps, the If the information entered is valid, the agent tools configure the Application Server instance. On completion of this task, prior to the program exiting, the tools display the following message indicating status:

tool will prompt you for information specific to the Macromedia JRun 4 instance that is being configured.

At the following prompt, enter the location of the configuration directory SERVER-INF of the server instance being configured:

Enter complete path to the SERVER-INF directory of the JRun Server Instance?:

At the following prompt, enter true if you want to install the agent filter in the global deployment descriptor default-web.xml. Or, if you want to add the filter individually to the application deployment descriptors, enter false.

Install agent filter in default-web.xml (’true’ or ’false’)?:

If the information entered is valid, the agentadmin tool will now proceed to configure the instance of Macromedia JRun server. Once this operation is completed, the agentadmin tool will display a message indicating the status of the task and the program will exit:

Agent Configured Successfully for Application Server Instance.



Note	The agent tool does not automatically configure the administration instance of Macromedia JRun 4. So the administration instance will continue to run with the administrator’s user name and password with which it was installed initially. However, you can configure the administration instance manually as explained in the following section.

Configuring the Administration Instance of Macromedia JRun 4

To configure the administration instance of Macromedia JRun 4, do the following:

Create the necessary role (jmcadmin) and user (admin) in Sun ONE Identity Server.

Assign the user to the role.

Define appropriate resources (http://host:adminport/*)

Define appropriate policies (rules, subjects, etc.) for the resource(s).

Configure the agent for administration instance as explained in the previous section.

Agents for Oracle 9iAS R2 and Oracle 10g

If you are configuring the agent for Oracle 9iAS R2 or Oracle 10g, the agent tools will prompt you for information specific to the Oracle 9iAS or Oracle 10g server instance respectively after you have completed the steps outlined in the section Common Configuration Steps.

At the following prompt, enter the complete path to the Oracle Server instance configuration directory. Ensure that you have write privileges for this directory.

Enter the location of Oracle Instance Config directory?:



Note	If you specify the directory path with a "/" at the end, for example instance_dir/oracle/config/, you will have to enter the path in the same form while unconfiguring too.

If the information entered is valid, the agent tools will now proceed to configure the instance of the application server. When this is completed, the tools will display a message indicating the status of the task and the program will exit:

Agent Configured Successfully for Application Server Instance.



Note	If the Oracle 9iAS or Oracle 10g instance that has been configured is outside the domain in which the agent was installed, you must complete the post-installation tasks for the respective instance as mentioned in the section "Post-Installation Tasks".

Agent for SAP Enterprise Portal 6.0 SP2

If you are installing the agent for SAP Enterprise Portal 6.0 SP2, after you have completed the steps outlined in the Common Configuration Steps section, the agent tool will prompt you for information specific to the SAP Enterprise Portal 6.0SP2 Server instance that is to be configured.

At the following prompt, enter the complete path to the server instance directory that will be configured:

Enter the path to SAP Enterprise Portal Server Directory?:

Agent Configured Successfully for Application Server Instance.



Note	Before you configure an instance, you must follow the appropriate pre-installation steps as outlined in the section "Pre-Installation Tasks". Once the instance has been configured by the agentadmin tool, you must follow the applicable post-installation steps as mentioned in the section "Post-Installation Tasks".

Agent for SAP Enterprise Portal 6.0 SP2 and Web Application Server 6.20 SP1

If you are installing the agent for SAP Enterprise Portal 6.0 SP2 and Web Application Server 6.20 SP1, after you complete the steps outlined in Common Configuration Steps, the agent tool displays the following prompt:

On the prompt, enter the complete path to the server instance directory that will be configured.

If the information you enter is valid, the agent tools proceed to configure the instance of the application server. When this is completed, the tools display a message indicating the status of the task. The program then exits and this message is displayed:

Agent for Sun Java System Application Server 8.1


Note	Before you configure an instance, follow the appropriate pre-installation steps as outlined in "Pre-Installation Tasks" Once the instance has been configured by the agentadmin tool, follow the applicable post-installation steps described in "Post-Installation Tasks"

After you have completed the steps outlined in "Common Configuration Steps", the agent tool will prompt you for information specific to the Sun Java System Application Server 8.1 instance that is being configured. Follow these steps:

At the following prompt, enter the location of the Domain Config Directory for the Sun Java Application Server 8.1 instance that is being configured:

Enter the Domain config Directory [ApplicationServer-base/domains/domain1/config]?:

At the following prompt, enter the application server instance that is being configured

Enter Sun Java(TM) System Application Server Instance Name?: [ExampleServer]?

At the following prompt, enter the port number where Sun Java System Administration Server is available:

Enter Sun Java(TM) System Application Server Administrative Server port [4849] ?:

where 4849 is the default port number.

At the following prompt, enter the user name for the Administrator of Sun Java System Application Server 8.1.

Enter Sun Java(TM) System Application Server Administrative User Name?: admin

where admin is the default administrative user name. Of course the actual administrative user name could be different.

At the following prompt, enter the password for the Administrator of Sun Java System Application Server 8.1:

Enter Sun Java(TM) System Application Server Administrative User Password?:

At the following prompt, re-enter the password for the Administrator of Sun Java System Application Server 8.1:

Reenter Sun Java(TM) System Application Server Administrative User Password?

Agent Configured Successfully for Application Server Instance.



Note	For instances where DAS is not on the agent host, therefore DAS is remote, the following applies: The agentadmin tool cannot configure a remote instance. If the server instance is on a different host than the DAS host, then the agent has to be installed on every host that has a server instance on it. For instances belonging to a different domain, the following applies: The Agentadmin tool cannot configure instances within a different domain on the same host. Agents do not support multiple domains per host.

Unconfiguring the Agent for an Application Server Instance

This section outlines the steps necessary to unconfigure an agent for an application server instance.

There are no common steps for unconfiguring all the agents using the agent tools. Hence, you can directly jump to the relevant agent section from the following list to unconfigure the agent for the respective application server instance.


Note	The agent tools for IBM WebSphere Application Server 5.0/5.1 agent do not support the unconfigure option. In order to manually unconfigure the agent for IBM WebSphere Application Server 5.1, you can refer to the steps described in the section Agent for IBM WebSphere Application Server 5.0/5.1 Instance. When the agent is removed from any application server instance, you must ensure that any applications deployed on that particular instance are changed to remove the agent filter component and are restored to their previous state as described in "Pre-Uninstallation Tasks".

Agent for Sun ONE Application Server 7.0

In a shell prompt from the bin directory of the agent installation, invoke the agent tool using the control script as follows:

#./agentadmin -unconfigure

On Windows platform, use this command:

agent_install_dir\IdentityServer\j2ee_agents\bin> agentadmin -unconfigure

At the following prompt, enter the location of the config directory for the application server instance that is being unconfigured:

Enter the Sun ONE Application Server instance config Directory?:

At the following prompt, enter the port number where Sun ONE Application Server Administration Server is available. Make sure that the administration server is running when doing this process:

Enter Sun ONE Application Server Administrative Server port [4848]?:

At the following prompt, enter the user name for the Administrator of Sun ONE Application Server.

Enter Sun ONE Application Server Administrative User Name [admin]?:

At the following prompt, enter the password for the Administrator of Sun ONE Application Server:

Enter Sun ONE Application Server Administrative User Password?:

At the following prompt, re-enter the password for the Administrator of Sun ONE Application Server:

Reenter Sun ONE Application Server Administrative User Password?:

If the information entered is valid, the agent tools will now proceed to unconfigure the instance of the application server. Once this is completed, the tools will display a message indicating the status of the task and the program will exit:

Agent Unconfigured Successfully for Application Server Instance.

Agents for BEA WebLogic Server (All Versions)


Note	If the BEA WebLogic Server instance being unconfigured is outside the domain in which the agent was installed, complete the pre-uninstallation tasks for BEA WebLogic Server instance as mentioned in the chapter Chapter 5, "Uninstalling the Agent".

BEA WebLogic Server 6.1 SP2,

BEA WebLogic Server 7.0 SP2 or BEA WebLogic Server 8.1

BEA WebLogic 8.1 SP2/SP3 Server/Portal

In a shell prompt from the bin directory of the agent installation, invoke the agent tool using the following command:

#./agentadmin -unconfigure

On Windows platform, use this command:

C:\Sun\IdentityServer\j2ee_agents\bin> agentadmin -unconfigure

At the following prompt, enter the location of the startup script that is used to launch this instance of WebLogic Server or Portal that is being unconfigured:

Enter the location of WebLogic Server Startup Script?:

If the information entered is valid, the agent tools proceed to unconfigure the instance of the application server. Once this is completed, the tools display a message indicating the status of the task. The program then exits and this message is displayed:

Agent Unconfigured Successfully for Application Server Instance.

Agent for IBM WebSphere Application Server 5.0/5.1 Instance

The agent tools do not support the unconfiguration option for IBM WebSphere Application Server 5.0/5.1 instances. However, the following list of steps provide the necessary details that will allow you to manually unconfigure an agent for an instance of the application server:

Stop the WebShpere Application Server instance that is being unconfigured.

Using the Administrative Console, remove the agent-specific classpath and boot classpath entries.

Using the Administrative Console, remove the agent-specific JVM options from Generic JVM Arguments.

Restart the WebSphere Application Server instance.



Note	Since WebSphere Application Server relies on a global security scheme, the application server instance that has been unconfigured will continue to operate with the agent realm, which is installed as a part of the earlier agent installation. Once the agent is unconfigured from the instance, the instance will no longer be able to load the agent realm and may fail to start. In order to completely unconfigure this instance, you can either uninstall the agent from this system, or operate the agent for the previous instance in a mode that does not require agent realm and disable the agent realm. Refer to the section on Agent Filter Modes for information on which agent operation modes do not require agent realm, and the section on Disabling the Agent Realm for information on how the agent realm can be disabled for IBM WebSphere Application Server instance.

Agent for PeopleSoft 8.3/8.4/8.8

In a shell prompt from the bin directory of the agent installation, invoke the agent tool using the control script as follows:

#./agentadmin -unconfigure

On HP-UX platform, use this command:

agent_install_dir\IdentityServer\j2ee_agents\bin> agentadmin -unconfigure

At the following prompt, enter the version of the PeopleSoft Application version you want to unconfigure.

Enter the PeopleSoft application version (’8.3’ or ’8.4’ or ’8.8’) [8.3] ?:

At this prompt, enter true if you have the PeopleSoft application server installed locally. Else, enter false.

PeopleSoft Application Server installed locally (’true’ or ’false’) [true] ?:

At this prompt, enter true if you have BEA WebLogic Server installed locally. Else, enter false.

WebLogic Server installed locally (’true’ or ’false’) [true] ?:

At this prompt, enter the full path to the directory where the PeopleSoft Application Server is installed. For example, PS_HOME/appserv

Enter PeopleSoft AppServer Directory [/export/home/psft/appserv] ?:

At this prompt, enter the PeopleSoft domain that this agent protects. For example, HDMO.

Enter PeopleSoft Domain Name [HDMO] ?:

At this prompt, enter the full path to the WebLogic instance directory. For example, PS_HOME/weblogic/myserver

Enter WebLogic instance Directory [/export/home/psft/weblogic/myserver] ?:

Agent Unconfigured Successfully for Application Server Instance.

Agent for Apache Tomcat Server 4.1.27

Stop the Tomcat Server instance you want to unconfigure.

At a shell prompt from the bin directory of the agent installation, invoke the agent tools using the following command:

#./agentadmin -unconfigure

On the Windows platform, use this command:

agent_install_dir\IdentityServer\j2ee_agents\bin\agentadmin -unconfigure

At the following prompt, enter the path to the configuration directory of the Tomcat Server instance that is being configured:

Enter complete path to the configuration directory of the Tomcat Server Instance?:

At the following prompt, enter true if you have installed the agent filter in the global deployment descriptor (web.xml). If however, you have added the filter individually to the application deployment descriptors, enter false.

Filter installed in global web.xml (’true’ or ’false’)?:



Note	The agent tools will not unconfigure the individual web applications’ deployment descriptors, if you had not installed the agent filter globally. Hence, you will need to remove the agent filter manually from the deployment descriptor of every deployed web application.

If the information entered is valid, the agent tools will now proceed to unconfigure the instance of the Tomcat Server. Once this operation is completed, the agent tools will display a message indicating the status of the task and the program will exit:

Agent Unconfigured Successfully for Application Server Instance.

Agent for Macromedia JRun 4

To unconfigure an instance of Macromedia JRun 4 using agent tools, you must first stop the instance and then start the configuration as explained in the following steps:

At the Solaris command prompt, invoke the agentadmin control script as follows:

# Agent_Install_Dir/SUNWam/j2ee_agents/bin/agentadmin -unconfigure

At the following prompt, enter the location of the configuration directory (SERVER-INF) of Macromedia JRun server instance being configured:

Enter the complete path to the SERVER-INF directory of the JRun 4 Server Instance?:

At the following prompt, enter true if the agent filter was installed in the global deployment descriptor default-web.xml. In this case, the unconfiguration program will remove the agent filter. If the filter was added individually to the application deployment descriptors, enter false. In this case, default-web.xml will remain untouched by the unconfiguration program.

Install agent filter in default-web.xml (’true’ or ‘false’)?:

If the information entered is valid, the agentadmin tool will now proceed to unconfigure the instance of the Macromedia JRun Server 4.0. Once this operation is completed, the agentadmin tool will display a message indicating the status of the task and the program will exit:

Agent Unconfigured Successfully for Application Server Instance.

When you uninstall the agent or unconfigure a Macromedia JRun 4 server instance, the jrun_instance_name_jvm.config file is simply removed. You must make sure to back up or save any custom configuration data that might have been added to this file.

Agent for Oracle 9iAS R2 and Oracle 10g Server Instance

Use the following steps to unconfigure the application server instance of Oracle 9iAS or Oracle 10g:

In a shell prompt from the bin directory of the agent installation, invoke the agent tool using the following command:

# ./agentadmin -unconfigure

At the following prompt, enter the complete path to the Oracle Server instance configuration directory. Ensure that you have write privileges for this directory.

Enter the location of Oracle Instance Config directory?:

If the information entered is valid, the agent tools will now proceed to unconfigure the instance of the application server.



Note	While configuring the instance directory, if you had specified the directory path with a "/" at the end, for example instance_dir/oracle/config/, you must enter the path in the same form while unconfiguring too.

Once this is completed, the tools will display a message indicating the status of the task and exit:

Agent Unconfigured Successfully for Application Server Instance.

Agent for SAP Enterprise Portal 6.0 SP2

Perform the following steps to unconfigure the SAP Enterprise Portal server instance:

In a shell prompt from the bin directory of the agent installation, invoke the agent tools using the following command:

# ./agentadmin -unconfigure

At the following prompt, enter the location of the startup script that is used to launch this instance of WebLogic Server which is being unconfigured:

Enter the path to SAP Enterprise Portal Server Directory?:

Agent Unconfigured Successfully for Application Server Instance.



Note	Before you unconfigure an instance, you must follow the appropriate pre-uninstallation steps as outlined in "Pre-Uninstallation Tasks". Once the instance has been unconfigured by the agentadmin tool, you must follow the applicable post-uninstallation steps as mentioned in "Post-Uninstallation Tasks".

Agent for SAP Enterprise Portal 6.0 SP2 and Web Application Server 6.20 SP1

In a shell prompt from the bin directory of the agent installation, invoke the agent tools using the following command:

./agentadmin -unconfigure

The following prompt appears:

Enter the path to SAP Server Directory?:

Enter the location of the server directory which is being unconfigured.

If the information you enter is valid, the agent tools proceed in unconfiguring the instance of the application server. Once the process is complete, the tools display a message indicating the status of the task. The program then exits and this message is displayed:

Agent Unconfigured Successfully for Application Server Instance.



Note	Before you unconfigure an instance, follow the appropriate pre-uninstallation steps as outlined in "Pre-Uninstallation Tasks" Once the instance has been configured by the agentadmin tool, follow the applicable post-uninstallation steps described in "Post-Uninstallation Tasks"

Agent for Sun Java System Application Server 8.1

Perform the following steps to unconfigure the Sun Java System Application Server 8.1 instance:

At the following prompt, enter the location of the Domain Config Directory for the Sun Java Application Server 8.1 instance that is being unconfigured:

Enter the Domain config Directory [ApplicationServer-base/domains/domain1/config]?:

At the following prompt, enter the application server instance that is being configured

Enter Sun Java(TM) System Application Server Instance Name?: [ExampleServer]?

At the following prompt, enter the port number where Sun Java System Administration Server is available:

Enter Sun Java(TM) System Application Server Administrative Server port [4849] ?:

where 4849 is the default port number.

At the following prompt, enter the protocol used by Application Server. This protocol value may either be HTTP or HTTPS:

Enter Sun Java(TM) System Application Server Administrative Server protocol [https] ?:

At the following prompt, enter the user name for the Administrator of Sun Java System Application Server 8.1.

Enter Sun Java(TM) System Application Server Administrative User Name?: admin_user_name

where admin is the default administrative user name. Of course the actual administrative user name could be different.

At the following prompt, enter the password for the Administrator of Sun Java System Application Server 8.1:

Enter Sun Java(TM) System Application Server Administrative User Password?:

At the following prompt, re-enter the password for the Administrator of Sun Java System Application Server 8.1:

Reenter Sun Java(TM) System Application Server Administrative User Password?

Agent Configured Successfully for Application Server Instance.



Note	For instances where DAS is not on the agent host, therefore DAS is remote, the following applies: the agentadmin tool cannot unconfigure a remote instance.

Agent APIs

The agent runtime provides access to all the Sun ONE Identity Server APIs that can be used to further enhance the security of your application. On top of these APIs, the agent also provides a set of APIs that allow the application to find out the SSO Token string associated with the logged on user. These APIs can be used from within the Web Container or the EJB Container of the application server.

The following sections illustrate the available agent APIs that can be used from within an application:

Class AmFilterManager

Available API

public static com.sun.identity.agents.filter.AmSSOCache getAmSSOCacheInstance() throws com.sun.identity.agents.arch.AgentException

This method returns an instance of Class AmSSOCache, which can be used to retrieve the SSO Token for the logged on user. This method can throw an AgentException if an error occurs while processing this request.

Class AmSSOCache

Available API

public java.lang.String getSSOTokenForUser(javax.servlet.http.HttpServletRequest request)

This method returns the SSO Token for the logged on user whose request is currently being processed in the application server’s Web Container. This method can return null if the requested token is not available at the time of this call.

public java.lang.String getSSOTokenForUser(javax.ejb.EJBContext context)

This method returns the SSO Token for the logged on user whose request is currently being processed in the application server’s EJB Container. This method can return null if the requested token is not available at the time of this call.



Note	The API getSSOTokenForUser(javax.ejb.EJBContext) can be used only when the agent operation mode is either J2EE_POLICY or ALL.