Sun ONE Identity Server J2EE Agent Guide: Chapter 5 Policy Agent for PeopleSoft 8.3

Previous Contents Next

Sun ONE Identity Server J2EE Agent Guide

Chapter 5 Policy Agent for PeopleSoft 8.3

This chapter gives an overview of PeopleSoft Agent and describes how to install and configure Sun ONE Identity Server Policy Agent for PeopleSoft 8.3. Topics in this chapter include:

PeopleSoft Agent Architecture

Operating System and Software Required

Installing the Agent

Configuring Sun ONE Identity Server

Verifying a Successful Installation

Agent Configuration

Troubleshooting Information

Uninstalling the Agent

PeopleSoft Agent Architecture

Sun ONE Identity Server Policy Agent for PeopleSoft 8.3 protects web access to PeopleSoft 8.3 (HRMS Application) using Sun ONE Identity Server security features such as authentication, single sign-on and policy.
PeopleSoft applications are web-enabled through PeopleSoft Internet Architecture (PIA) that involves deploying PeopleSoft servlets on a web server (Apache or WebLogic) tier, which fronts the PeopleSoft proprietary application server. Sun ONE Identity Server Policy Agent can either be installed on the web server or on a web container that acts as proxy to the PeopleSoft web server.
Figure 5-1    PeopleSoft Agent Architecture

Sun ONE Identity Server Policy Agent is based on the Single Sign-on (SSO) infrastructure provided by PeopleSoft. For more information, see Chapter 7 of the Security PeopleBook.
The Sun ONE Identity Server Policy Agent code on the user's web server (either the proxy or the PeopleSoft provided web server) works like a regular Sun ONE Identity Server web agent. It intercepts all user-requests and is responsible for authenticating and authorizing web access to the PeopleSoft application based on the authentication schemes and policies defined in Sun ONE Identity Server.
The PeopleSoft configuration required for the agent to work is a three-step process:

Creating a default user in PeopleSoft.

Configuring the web server servlets to pass on the default user to the application server.

Configuring the application server to delegate the process of determining the user logged in to a special PeopleCode (PeopleSoft's proprietary language) provided by Sun ONE Identity Server.

The rest of PeopleSoft configuration, specifically the existing PeopleSoft user repository, user profiles and PeopleSoft roles based access control do not need any changes, and work exactly like before.

The current implementation of identifying the user to PeopleSoft assumes that Sun ONE Identity Server and PeopleSoft separately maintain users, and a pre-determined LDAP attribute in the user's entry that contains the PeopleSoft userid. User synchronization between the two user repositories is beyond the scope of Sun ONE Identity Server or the Sun ONE Identity Server Policy Agents. While continuing to support this form of mapping, future implementations will provide support for installations that have a single user LDAP repository shared between Sun ONE Identity Server and PeopleSoft.

Deployment Options

The two deployment options are illustrated in the Figure 5-1.

Option 1) Agent on PeopleSoft Provided WebLogic 5.1 Server

This option requires redeploying the PeopleSoft application as a web application. The installer automatically makes necessary modifications. The AuthFilter implementation provided with the Agent gets called each time when a resource is accessed in this web application. The AuthFilter implementation is responsible for authenticating the user with Sun ONE Identity Server.

Option 2) Proxy Solution - Agent on a Separate Proxying Web Server

When you choose this option, the Sun ONE Web Server 4.1 (also referred as iPlanet Web Server or iWS) is configured as a proxy for WebLogic Server hosting PeopleSoft servlets. This option is recommended for the following reasons:

More secure. Isolates the application business logic contained in PeopleSoft servlets and PeopleSoft Application server, thereby allowing the proxy server to be deployed in a Demilitarized Zone (DMZ) and hence minimizing attacks such as denial of service.

Better Performance.

Wider choice among Sun ONE Identity Server Policy agents that will act as the proxy. PeopleSoft provided web servers support only Apache and WebLogic 5.1. Sun ONE Identity Server web agents are available on a variety of web containers and hardware platforms.

Operating System and Software Required

Operating systems supported:

Solaris 8

HP-UX 11
Other required software:

PeopleSoft-provided WebLogic 5.1 SP12 Server

Sun ONE Identity Server 5.1

Sun ONE Web Server 4.1 SP8

Sun ONE Identity Server Policy Agent 1.1 for Sun ONE Web Server 4.1

Installing the Agent

The installation script installs the Sun ONE Identity Server Policy Agent. The following sections provide the steps necessary for installing the Agent on each of these platforms.

Pre-Installation Tasks

The following tasks must be completed before the Sun ONE Identity Server Policy Agent for PeopleSoft 8.3 can be installed:

Determine which deployment option to choose by first identifying your scenario, and then follow the detailed instructions that correspond to that scenario.

Install PeopleSoft 8.3 and configure the Web Server tier that will execute PeopleSoft servlets.

If not already done, upgrade your WebLogic to sp12. To do this, you can download weblogic510sp12.tar from the following location:

ftp://ftp.peoplesoft.com/outgoing/GSC/jim/weblogic510

You can read the file readme.html available at this location for instructions on how to apply the service pack.

Install the Sun ONE Web Server 4.1 in case you choose the proxy solution.

Overview of Installation and Configuration Tasks

In order to use the Sun ONE Identity Server Policy Agent for PeopleSoft 8.3, the following steps are necessary:

Setting up PeopleSoft for SSO

Installing the Sun ONE Identity Server Policy Agent

Installing Sun ONE Web Server 4.1 for Proxy Solution

Configuring Sun ONE Identity Server

Setting Up PeopleSoft for SSO

The following procedures include steps for setting up PeopleSoft for Single Sign-on (SSO).

To Create DEFAULT_USER

Invoke the web PeopleSoft application by entering the following URL:

http://PS_web_server:port/servlets/iclientservlet/peoplesoft8/?cmd=start

Log on to PeopleTools as a privileged user. Example: PS

Navigate to Home > PeopleCode > Maintain Security > Use > UserProfiles screen then select "Add a New Value" and create a user.

In the User ID field, enter DEFAULT_USER.

In the Password field, enter the password.

This user should not have any privileges/roles. Choose the default values or leave the non-mandatory fields blank.

Note
You will need this password while configuring the Web server during setup.

In the User Profiles page, open the ID tab and select the ID Type as None.

DEFAULT_USER does the initial communication between PeopleSoft web server servlets and the PeopleSoft Application Server.

Click the Save button to save the changes.

Log out of the PeopleTools application.

To Install PeopleCode

Invoke Application Designer on the Windows NT machine where PeopleSoft application is installed. To do this, go to Start menu > Programs > PeopleSoft Installation > Application Designer.

Login as a privileged user. Example: PS

Navigate to the FUNCLIB_LDAP record. To do this, click File > Open.

In the Open Object window, select the Object Type Record.

In the name field, enter FUNCLIB_LDAP.

Leave the default values in the rest of the fields and click Open.
Figure 5-2    Open Object window

Select the LDAP Auth row and right-click the mouse button to select "View PeopleCode" option.

Append the contents of ISPeopleCode.txt to the end of the existing PeopleCode source. This file is provided with the Policy Agent binaries.

Search for Function getWWWAuthConfig()" in the PeopleCode:

Function getWWWAuthConfig()

&defaultUserId = "";

End-Function

Modify the variable &defaultUserId to return the User ID created in previous step as follows.

Function getWWWAuthConfig()

&defaultUserId = "DEFAULT_USER";
End-Function;

Click the Save button to save and exit from the Application Designer.
PeopleCode provided with the agent can be configured in four modes using the properties set in the AMAgent.properties file. For an explanation of these properties, see the section "Agent Configuration" on page 200.

Validate SSO Token off, PeopleSoft userid retrieval off

This mode provides the least security. The Sun ONE Identity Server Policy Agent authenticates the user and a special HTTP header variable is set by the agent to identify the logged in user.

Validate SSO Token off, PeopleSoft userid retrieval on

This mode ignores the PeopleSoft userid in the HTTP header variable set by the agent, and retrieves the same from the Sun ONE Identity Server.

Validate SSO Token on, PeopleSoft userid retrieval off

This mode adds extra security by validating the SSO Token. If SSO Token is not valid, access is denied.

Validate SSO Token on, PeopleSoft userid retrieval on

This mode provides high security. The PeopleCode validates the SSO token and retrieves the mapped PeopleSoft userid ignoring the one specified in the HTTP header variable that is set by the agent.

To Register PeopleCode for Authentication

Navigate to Home > PeopleTools > Utilities > Use > SignOn PeopleCode window.

Add a new row, which should look like the 6th row shown in the Figure 5-3. To add a new row, click + on the last row.

Ensure that the FunctionName column shows DSAME_Authentication, Exec Auth Fail column is not selected, and the Enabled column is selected.
Figure 5-3    Sign-On PeopleCode Window

Click Save to save the changes.

Launching the Agent Installation Program

Launching the Agent Installation Program on Solaris Platform

Be sure the PeopleSoft application server and web server are shutdown before starting the installation program.

Login as a PeopleSoft user. Example: psft

Unpack the product binaries using the following command:

# gzip -dc ps83agent-1.0-domestic-us.sparc-sun-solaris2.8.tar.gz | tar xvf -

Set your JAVA_HOME environment variable to JDK version 1.3.1 or higher. If your system does not have the required version of JDK, use the JDK supplied with PeopleSoft. This JDK is located at:

PS_HOME/jre

Run the setup program. You'll find the program in the directory where you untarred the binaries. At the command line, type the following:

# ./setup

The installation program requires that you set up your JAVA_HOME variable correctly as pointed out in the Step 3. However, if you have set the JAVA_HOME variable incorrectly, the setup script will prompt you for the correct JAVA_HOME value:

Enter JAVA_HOME location (Enter "." to abort):

Specify the JAVA_HOME value by typing the full path to the JDK installation directory. Otherwise, enter a period (.) to abort the installation.

In order that the GUI installation program be displayed on your console, the DISPLAY environment variable of your shell must be set correctly. If your DISPLAY environment variable is not set at the time of invoking the setup script, the installation program will prompt you for the DISPLAY environment variable value as follows:

Please enter the value of DISPLAY variable (Enter "." to abort):

Provide the DISPLAY value by typing the exact value at the above prompt. Otherwise, enter a period (.) to abort the installation.

Launching the Agent Installation Program on HP-UX 11 Platform

Login as a PeopleSoft User. Example: psft

Unpack the product binaries using the following the command:

# gzip -dc ps83agent-1.0-domestic-us.hppa1.0-hp-hpux11.00.tar.gz | tar xvf -

Set your JAVA_HOME environment variable to JDK version 1.3.1 or higher. If your system does not have the required version of JDK, use the JDK supplied with PeopleSoft. This JDK is located at:

PS_HOME/jre

Run the setup program. You'll find the program in the directory where you untarred the binaries file. At the command line, enter the following:

# ./setup

The installation program requires that you set up your JAVA_HOME variable correctly as pointed out in the Step 3. However, if you have incorrectly set the JAVA_HOME variable, the setup script will prompt you for the correct JAVA_HOME value:

Enter JAVA_HOME location (Enter "." to abort):

Specify the JAVA_HOME value by typing the full path to the JDK installation directory. For example, PS_HOME/jre. Otherwise, enter a period (.) to abort the installation.

In order that the GUI installation program be displayed on your console, the DISPLAY environment variable of your shell must be set correctly. If your DISPLAY environment variable is not set at the time of invoking the setup script, the installation program will prompt you for the DISPLAY environment variable value as follows:

Please enter the value of DISPLAY variable (Enter "." to abort):

Provide the DISPLAY value by typing the exact value at the above prompt. For example, nila:0. Otherwise, enter a period (.) to abort the installation.

Installing the Agent Using GUI

When you run the setup program, the installation GUI starts up. The opening panel informs you that you would need Administrative privileges in PeopleSoft to install the agent. Make sure that you have Administrative privileges in PeopleSoft before you proceed with installation.

Click Next to open the Welcome panel.

Click Next to open the Software License Agreement panel. Read the License Agreement and click Yes to agree to the license terms.

Click Next and in the Select Installation Directory panel, provide the following information.

Install Sun ONE Identity Server Policy Agent 1.0 in this directory: Enter the full path to the directory where you want this agent to be installed.

Click Next and in the Select an Agent panel, select Sun ONE Identity Server Policy Agent 1.0 for PeopleSoft 8.3.

In the Sun ONE Identity Server Information panel, provide information about the web server that runs Sun ONE Identity Server policy and management services. The URL Policy Agent will connect to this server.

Identity Server Host: Enter the fully qualified domain name of the system where the primary web server that runs Identity Server services is installed. Example: myserver.siroe.com.

Identity Server Port: Enter the port number for the web server that runs Identity Server services.

Identity Server Protocol: If the web server that runs Identity Server is SSL-enabled, select HTTPS; otherwise select HTTP.

Identity Server Deployment URI: Enter the location that was specified when Identity Server was installed. The default Universal Resource Identifier (URI) for Identity Server is /amserver.

amAdmin Password: Enter the password of the amAdmin user of Identity Server.

Re-enter Password: Enter the amAdmin user password again to confirm it.

In the Directory Server Information panel, provide the following information about the Directory Server that is associated with Sun ONE Identity Server services.

Directory Host: Enter the fully qualified host name of the system where the Directory Server is installed.

Directory Port: Enter the port number used by the Directory Server.

Root Suffix: Enter the root suffix to be used with this Directory Server.

Installation Organization: Enter the name of the installation organization used when installing the Sun ONE Identity Server.

In the Deployment Options panel, select the mode for deploying the Policy Agent.

Agent on PeopleSoft Provided WebLogic 5.1 Server: Select this option to install the Agent on top of WebLogic 5.1 Server provided with PeopleSoft. This option requires redeploying the PeopleSoft application as a web application.

Proxy Solution - Agent on a Separate Proxying Web Server: Select this option if you want to configure Sun ONE Web Server 4.1 (also referred as iPlanet Web Server or iWS) as a proxy for WebLogic Server hosting PeopleSoft servlets.

In the PeopleSoft Installation Information panel, provide the following information about your existing PeopleSoft installation.

PeopleSoft Application Server Installed locally: Click this check box to specify that you have PeopleSoft Application Server installed locally.

WebLogic 5.1 Server Installed locally: Click this check box if you have WebLogic 5.1 Server installed locally.

Directory containing JRE used by PeopleSoft: Enter the absolute path to the directory where the JRE used by PeopleSoft is available. For example, PS_HOME/jre.

PeopleSoft AppServer Directory: Enter the absolute path to the directory that contains the PeopleSoft AppServer. For example PS_HOME/appserv.

PeopleSoft Domain Name: Enter the HRMS domain that this agent will protect. Example: HDMO

WebLogic 5.1 Home Directory: Type the full patch to the directory where the application server is installed. Example: PS_HOME/weblogic

In the Configuration Details panel, provide the following information about how PeopleSoft is configured at your site. This panel is displayed only if, in the previous panel, you had checked the box WebLogic 5.1 Server Installed locally.

PeopleSoft Server Host: Enter the fully qualified host name of the PeopleSoft Web Server used to access the PeopleSoft Applications. Example: peoplesoft.sun.com

For Proxy Solution, enter the fully qualified host name of iWS 4.1.

PeopleSoft Server Port: Enter the port number used to access PeopleSoft Applications.

For Proxy Solution, enter the port number of iWS 4.1.

PeopleSoft Server Protocol: Enter the Web protocol used to access PeopleSoft Applications.

For Proxy Solution, use the web protocol of iWS 4.1.

PeopleSoft DEFAULT_USER: PeopleSoft SSO configuration parameter identifying a generic PeopleSoft userid that the web server uses to identify itself to the Application Server. Example: DEFAULT_USER.

Make sure it is same as the one configured for DEFAULT_USER. For more information, refer "To Create DEFAULT_USER."

PeopleSoft DEFAULT_USER Password: Enter the password defined for the PeopleSoft DEFAULT_USER.

Re-enter Password: Enter the PeopleSoft DEFAULT_USER Password again to confirm the password.

Name of the PIA Site: Enter the name of the PIA site that was provided during PeopleSoft installation.

In the Summary of all the selections screen, review and verify the installation options that you have specified for the Agent. If you need to make changes, click Back. Otherwise, click Next to proceed.

In the Ready to Install screen, click Install Now to begin the installation.

In the Installation Summary panel, click Details for a detailed summary of the configuration information that was processed during installation. Click Exit to end the program.

Note
A successful installation creates a file containing the environment variables necessary for the agent code installed PeopleSoft Application Server to execute correctly. This file is created under PS_HOME/appserv/psdsameenv.sh. You must add PS_HOME/appserv/psdsameenv.sh to the $HOME/.profile of the userid that executes PeopleSoft startup and shutdown.
Make sure that you execute psdsameenv.sh before starting the Application Server.

Installing from the Command Line

Run the command:

./setup -nodisplay

The installation program starts. It provides instructions on the screen to help you proceed with the installation.

At the following prompt, type Yes or press Enter to continue.

At the following prompt, press Enter to display the Sun ONE Software License Agreement.

Read the agreement carefully and type Yes to accept it.

At the following prompt, provide the following information.

The Sun(TM) ONE Identity Server Policy Agent 1.0 components will be installed in the following directory, which is referred to as the "Installation Directory". To use this directory, press only the Enter key. To use a different directory, type in the full path of the directory to use followed by pressing
the Enter key.

Install Sun(TM) ONE Identity Server Policy Agent 1.0 in this directory [/export/home/psft/agent] {"<" goes back, "!" exits}:

Install Sun ONE Identity Server Policy Agent 1.0 in this directory [export/home/psft/agent]: Press Enter if you want to install in the default directory prompted by the installation program. However, if you want install in a different directory, enter the full path to that directory.

If you enter a directory name that does not exist, the installation program asks whether you want to create the new directory and then creates it for you.

At the following prompt, press Enter to select Sun ONE Identity Server Policy Agent 1.0 for PeopleSoft 8.3.

Sun(TM) ONE Identity Server Policy Agent 1.0 components showing a checked box will be installed. Only one component may be installed at a time.

[X] 1 Sun(TM) ONE Identity Server Policy Agent 1.0 for PeopleSoft 8.3
4.40 MB

Select a component" [0] {"<" goes back, "!" exits}

At the following prompts, provide information about the web server that runs Sun ONE Identity Server policy and management services. The URL Policy Agent will connect to this server.

Sun(TM) ONE Identity Server Services Details.
Identity Server Host [nila.Eng.Siroe.COM] {"<" goes back, "!" exits}:
Identity Server Port [58080] {"<" goes back, "!" exits}:
Identity Server Protocol [http] {"<" goes back, "!" exits}:
Identity Server Deployment URI [/amserver] {"<" goes back, "!" exits}:
amAdmin Password [] {"<" goes back, "!" exits}:
Re-enter Password [] {"<" goes back, "!" exits}:

Identity Server Host: Enter the fully qualified domain name of the system where the primary web server that runs Identity Server services is installed. For example, nila.Eng.siroe.com.

Identity Server Port: Enter the port number for the web server that runs Identity Server services.

Identity Server Protocol: If the web server that runs Identity Server is SSL-enabled, select HTTPS; otherwise select HTTP.

Identity Server Deployment URI: Enter the location that was specified when Identity Server was installed. The default Universal Resource Identifier (URI) for Identity Server is /amserver.

amAdmin Password: Enter the password of the amAdmin user of Identity Server.

Re-enter Password: Enter the amAdmin user's password.

At the following prompts, provide the following information about the Directory Server that is associated with Sun ONE Identity Server services.

Sun(TM) ONE Identity Server Directory Details
Directory Host [nila.Eng.Siroe.COM] {"<" goes back, "!" exits}:
Directory Port [389] {"<" goes back, "!" exits}:
Root Suffix [o=isp] {"<" goes back, "!" exits}:
Installation Organization [o=sun.com] {"<" goes back, "!" exits}:

Directory Host: Enter the fully qualified host name of the system where the Directory Server is installed.

Directory Port: Enter the port number used by the Directory Server.

Root Suffix: Enter the root suffix to be used with this Directory Server.

Installation Organization: Enter the name of the installation organization used when installing the Sun ONE Identity Server.

At the following prompt, select the mode for deploying the Policy Agent. Enter the number corresponding to an option to select it.

Deployment Options
1. Agent on PeopleSoft Provided WebLogic 5.1 Server
2. Proxy Solution - Agent on a Separate Proxying Web Server
Choose one of the options from above [1] {"<" goes back, "!" exits}

Agent on PeopleSoft Provided WebLogic 5.1 Server: Select this option to install the Agent on top of WebLogic 5.1 Server provided with PeopleSoft. This option requires redeploying the PeopleSoft application as a web application.

Proxy Solution - Agent on a Separate Proxying Web Server: Select this option if you want to configure Sun ONE Web Server 4.1 (also referred as iPlanet Web Server or iWS) as a proxy for WebLogic Server hosting PeopleSoft servlets.

At the following prompts, provide information about your existing PeopleSoft installation.

PeopleSoft installation Details
PeopleSoft Application Server installed locally [true] {"<" goes back, "!" exits}
WebLogic 5.1 Server installed locally [true] {"<" goes back, "!" exits}
Directory containing jre used by PeopleSoft [/export/home/psft] {"<" goes back, "!" exits}
PeopleSoft AppServer Directory [/export/home/psft/appserv] {"<" goes back,"!" exits}
PeopleSoft Domain Name [HDMO] {"<" goes back, "!" exits} HIND
WebLogic 5.1 Home Directory [/export/home/psft/weblogic] {"<" goes back, "!" exits}

PeopleSoft Application Server Installed locally: Press Enter to specify that you have PeopleSoft Application Server installed locally. Otherwise, enter false.

WebLogic 5.1 Server Installed locally: Press Enter if you have WebLogic 5.1 Server installed locally. Otherwise, enter false.

Directory containing JRE used by PeopleSoft: Enter the absolute path to the directory where the JRE used by PeopleSoft is available. For example PS_HOME/jre.

PeopleSoft AppServer Directory: Enter the path to the directory where the Application Server is installed. For example, PS_HOME/appserv

PeopleSoft Domain Name: Enter the HRMS domain that this agent will protect. Example: HDMO

WebLogic 5.1 Home Directory: Type the full patch to the directory where the application server is installed. Example: PS_HOME/weblogic

In the Configuration Details panel, provide the following information about how your PeopleSoft installation is configured. These prompts appear only if you had specified that WebLogic 5.1 Server is installed locally.

Configuration details for this installation.
PeopleSoft Server Host [nila.Eng.Siroe.COM] {"<" goes back, "!" exits}:
PeopleSoft Server Port [80] {"<" goes back, "!" exits}:
PeopleSoft Server Protocol [http] {"<" goes back, "!" exits}:
PeopleSoft DEFAULT_USER [DEFAULT_USER] {"<" goes back, "!" exits}:
PeopleSoft DEFAULT_USER Password [] {"<" goes back, "!" exits}: 1
Re-enter Password [] {"<" goes back, "!" exits}: 1
Name of the PIA Site [peoplesoft8] {"<" goes back, "!" exits}:

PeopleSoft Server Host: Enter the fully qualified host name of the PeopleSoft Web Server used to access the PeopleSoft Applications. Example: peoplesoft.siroe.com

If you are deploying the agent as a Proxy Solution, enter the fully qualified host name of iWS 4.1.

PeopleSoft Server Port: Enter the port number used to access PeopleSoft Applications.

If you are deploying the agent as a Proxy Solution, enter the port number of iWS 4.1.

PeopleSoft Server Protocol: Enter the Web protocol used to access PeopleSoft Applications.

If you are deploying the agent as a Proxy Solution, use the web protocol of iWS 4.1.

PeopleSoft DEFAULT_USER: PeopleSoft SSO configuration parameter identifying a generic PeopleSoft userid that the web server uses to identify itself to the Application Server. Example: DEFAULT_USER

PeopleSoft DEFAULT_USER Password: Enter the password defined for PeopleSoft DEFAULT_USER.

Re-enter Password: Reenter the DEFAULT_USER password to confirm it.

Name of the PIA Site: Enter the name of the PIA site provided during PeopleSoft installation.

The installation program displays a summary of all your selections at the previous prompts.

Review the summary and at the prompt, press Enter to proceed.

At the following prompt, press Enter to install the Agent.

Following components will be installed:
PRODUCT: Sun_TM_ONE Identity Server Policy Agent
LOCATION: /export/home/psft/agent
SIZE: 4.40 MB
------------------------------------------------
Sun(TM) ONE Identity Server Policy Agent 1.0 for PeopleSoft 8.3
Ready to install
1. Install Now
2. Start Over
3. Exit
Choose one option from above [1] {"<" goes back, "!" exits}

The next prompt informs you that you have successfully installed the agent. At this prompt, press Enter to exit the installation program.

Note
A successful installation creates a file containing the environment variables necessary for the agent code installed PeopleSoft Application Server to execute correctly. This file is created under PS_HOME/appserv/psdsameenv.sh. You must add PS_HOME/appserv/psdsameenv.sh to the $HOME/.profile of the userid that executes PeopleSoft startup and shutdown.
Make sure that you execute psdsameenv.sh before starting the Application Server.

Installing Sun ONE Web Server 4.1 for Proxy Solution

The following procedure includes steps for configuring the Sun ONE Web Server 4.1 as proxy for WebLogic Server hosting PeopleSoft servlets.

Install Sun ONE Web Server 4.1 and the supporting Sun ONE Identity Server Policy Agent. For more information on installing Sun ONE Policy Agent for Sun ONE Web Server 4.1 access the documentation at: http://docs.sun.com/source/816-5428-10/index.html

Download and install WebLogic plug-in for Sun ONE Web Server 4.1. To do this, make a directory libproxy_Dir, for example web_server_dir/server_instance/lib.

Go to WebLogic_Dir/lib/solaris.

Copy libproxy.so to libproxy_Dir.

For detailed information see: http://www.weblogic.com/docs51/admindocs/nsapi.html

Make following modifications to the obj.conf, which is located at:

Web_Server_Dir/server_instance/config

Append the following lines at the beginning of the obj.conf file.

Code Example 5-1
Init fn="load-modules" funcs="wl-proxy,wl-init"\

      shlib=_libproxy_Dir/libproxy.so

Init fn="wl-init"

Append the following lines at the end of the obj.conf file
Code Example 5-2
<Object name="weblogic" ppath="*">

Service fn=wl-proxy WebLogicHost=myserver.com\

WebLogicPort=7001

</Object>

where:

Web_Server_Dir: The directory where Sun ONE Web Server is installed.

server_instance: The identity of the web server instance you want to configure.

Install_Dir: The installation directory of the WebLogic proxy libraries.

myserver.com: WebLogic hostname.

Object is given a name weblogic. This object instructs the web server to redirect all the URLs that match the pattern defined as the value of ppath. The library method invoked when such a pattern occurs, is defined as the value of the fn variable. The rest of the parameters are input parameters to the wl-proxy function itself.

The above example shows that all the requests to this server are serviced by the wl-proxy function. If you modify the ppath=*/weblogic/* then all URLs that matches the pattern */weblogic/* are serviced by the wl-proxy function.

It is recommended that only the proxy web server be allowed to access the WebLogic 5.1 server hosting PeopleSoft servlets and all other accesses be blocked. You can do this either by:

Installing a firewall on the machine executing the WebLogic server with appropriate firewall rules. For example, allowing http access only from the proxy web server machine, and denying all other http access.

Enabling the SimpleConnectionFilter class on the WebLogic server. For more information refer the documentation at:

http://www.weblogic.com/docs51/examples/security/net/package-examples.security.net.html

Configuring Sun ONE Identity Server

The following procedures help you configure the Sun ONE Identity Server.

Configuring Sun ONE Identity Server Policy and Authentication Server

Option 1

Log on to Sun ONE Identity Server Console as Administrator.

Select the LDAP attribute to be used to map Sun ONE Identity Server userids to PeopleSoft userids. Update the attribute for each Sun ONE Identity Server user that needs access to PeopleSoft.

Option 2

Log on to Sun ONE Identity Server Console as Administrator.

Set up appropriate URL policies and roles for access to PeopleSoft Application. Example:

Allow http://Web_server:port/servlets/*

Assign PeopleSoft policies and roles to users.

Select the LDAP attribute to be used to map Sun ONE Identity Server userids to PeopleSoft userids. Update the attribute for each Sun ONE Identity Server user that needs access to PeopleSoft.

Note
PeopleSoft uses the mapped userid while performing its own authorization. No changes are necessary to PeopleSoft policy.

Verifying a Successful Installation

To verify a successful installation of Sun ONE Identity Server Policy Agent do the following:

Try to access PeopleSoft Application by entering one of the following links depending on your deployment option. You should see the Sun ONE Identity Server login page.

If you have deployed the Agent on PeopleSoft-provided WebLogic 5.1 Server, use this link:

http://PS_WebLogic_server:port/servlets/iclientservlet/peoplesoft8/?cmd=start

If you have deployed the Agent as a Proxy Solution, use this link:

http://Web_Server:port/servlets/iclientservlet/peoplesoft8/?cmd=start

Successful login to Sun ONE Identity Server should display the PeopleSoft Application with the appropriately mapped PeopleSoft user logged in. Unsuccessful login should not allow access to the PeopleSoft Application.

Logout from the PeopleSoft Application should result in complete logout from PeopleSoft Application as well as Sun ONE Identity Server, and should return back to the Sun ONE Identity Server authentication page.

Agent Configuration

The file AMAgent.properties located at Agent_Install_Dir/SUNWam/agent/config directory provides the core configuration needed by the Sun ONE Identity Server Policy Agent for PeopleSoft 8.3 to function correctly. This property file provides many configuration settings that can be modified in order to customize the Agent's operation for your deployment scenario. This section provides a brief explanation of all the properties that are listed in the properties file.
Before proceeding, it is important to note that this file and the information within it are critical for the operation of the Agent. It is strongly recommended that you always create a backup of this file before modifying it. Also it is strongly recommended that you do not modify this file unless it is absolutely necessary. Please note that invalid data entries present in this file can lead to the malfunction of the Agent, the malfunction of the deployed applications, and could render the entire system unusable.
After you make the changes to AMAgent.properties, you must perform the following steps:

Restart WebLogic server.

Reboot PeopleSoft Application Server domain.
If WebLogic server and PeopleSoft Application Server are installed on different systems, make sure that the Agent Core Configuration properties in the AMAgent.properties file on both the systems are the same.
The settings provided in this file can be classified as follows:
Agent Core Configuration: These are general settings that impact the behavior of the Agent at runtime.
Audit Configuration: These settings are used to configure the Audit Engine used by the Agent.
Debug Engine Configuration: These settings help configure the Debug Engine to generate diagnostic information.

Agent Core Configuration

SSO Token Name

Key: com.sun.am.policy.config.ssoTokenName
Description: This property specifies the name of the Cookie that represents SSO Token.
Valid Values: A String that represents the name of the SSO Token Cookie issued by Sun ONE Identity Server authentication service.

Note This property is set during Agent installation and need not be changed unless absolutely necessary.

Example: com.sun.am.policy.config.ssoTokenName=iPlanetDirectoryPro

Get LDAP Attribute Flag

Key: com.sun.am.policy.config.getLDAPAttribute
Description: This property specifies whether the LDAP attribute representing a PeopleSoft user should be got from Identity Server.
Valid Values: This property can have one of these two values:
true, indicates that PeopleCode will retrieve the attribute.
false, indicates that it will rely on the HTTP header for the PeopleSoft user value. This value is used only if you have installed the agent as a proxy solution.

Note Default value of this property is "true" and should be changed as necessary. It is mandatory to set the value of this property to true if you have deployed the Agent on PeopleSoft-provided WebLogic Server. If you are deploying the Agent as a Proxy Solution, setting the value to true will provide extra security.

Example: com.sun.am.policy.config.getLDAPAttribute=true

LDAP Attribute Name

Key: com.sun.am.policy.config.LDAPAttribute
Description: This property specifies the LDAP Attribute, in Identity Server, to be mapped to a PeopleSoft user. This is used only if the property com.sun.am.policy.config.getLDAPAttribute is set to true.
Valid Values: String representing the valid LDAP Attribute in Identity Server.

Note This property is set during Agent installation and need not be changed unless absolutely necessary.

Example: com.sun.am.policy.config.LDAPAttribute=employeenumber

HTTP Header Attribute Name

Key: com.sun.am.policy.config.headerAttribute
Description: This property specifies the HTTP Header Attribute in the http request representing the PeopleSoft user. This is used if the property com.sun.am.policy.config.getLDAPAttribute is set to false. In this case, you need to edit iWS Agent's AMAgent.properties available in /etc/opt/SUNWam/confIWS4.1/_pathinstancename to ensure that com.iplanet.am.policy.agents.forward_ldapattr_in_http_headers.enable=true and that com.iplanet.am.policy.agents.ldapattr contains the value of HTTP Header Attribute Name as one of the value pairs. You can get more information on this at http://docs.sun.com/source/816-5428-10/iws60.html#35377.
Valid Values: String representing the HTTP Header Attribute

Note This property is set during Agent installation and need not be changed unless absolutely necessary.

Example: com.sun.am.policy.config.headerAttribute=employee-number

Validate SSO Token Flag

Key: com.sun.am.policy.config.validateSSO
Description: This property specifies if validation of Identity Server SSO token should be done in PeopleSoft Application server for extra security.
Valid Values: This property should have one of these values:
true: indicates that the validation will be done.
false: indicates that no validation will be performed.

Note Default value of this property is "true" and should be changed as necessary.

Example: com.sun.am.policy.config.validateSSO=true

Simple Policy Flag

Key: com.sun.am.policy.config.simplePolicy
Description: This property specifies if Simple Policy should be enforced by Agent. This property is applicable only if you deploy Agent on PeopleSoft Provided WebLogic 5.1 Server (Deployment Option 1).
Valid Values: This property should have one of these values:
true: indicates that Simple Policy will be enforced. This ensures that a user can access only the URI starting with /servlets or /peoplesoft8 (PIA site name). If a user tries to access any other URI, it will invalidate the SSOToken and show the Identity Server Login page. This means that the user will not get WebLogic's index page when she tries to access a URI with just http://domainname:port/.
false: indicates that Simple Policy will not be enforced. For example, the user will be able to access WebLogic's index.html page even with a URI such as http://domainname:port/.

Note The default value of this property is "true" and is mandatory for security reasons.

Example: com.sun.am.policy.config.simplePolicy=true

Audit Configuration

Language Code

Key: com.sun.am.policy.config.audit.localeLanguageCode
Description: This property specifies the Locale for Audit log messages.
Valid Values: The localeLanguageCode must be a valid ISO Language Code. Default value of this property is `en'.

Note For more information, refer to ISO 639 specification: http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt

Example: com.sun.am.policy.config.audit.localeLanguageCode=en

Country Code

Key: com.sun.am.policy.config.audit.localeCountryCode
Description: This property specifies the Locale for Audit log messages.
Valid Values: The localeCountryCode must be a valid ISO Country Code. Default value of this property is `US'.

Note For more information, refer to ISO 3166 specification: http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html

Example: com.sun.am.policy.config.audit.localeCountryCode=US

Audit Log File

Key: com.sun.am.policy.config.audit.logfile.name.
Description: This property specifies the Audit log file to be used for recording Audit messages.
Valid Values: String representing the complete path name of the file to be used by Agent to record Audit messages.
No default value is set for this property. A valid value must be specified before the Application Server is started.

Note
Be sure the Application Server process has sufficient permissions to write to this file. Invalid value specified for this property may result in the failure of the system to start up correctly.

Example:com.sun.am.policy.config.audit.logfile.name=/var/opt/SUNWam/asAgent/audit/agent.log

Audit Log File Rotation Flag

Key: com.sun.am.policy.config.audit.logfile.rotate
Description: This property specifies if the Audit log file should be rotated by the Agent.
Valid Values: true/false

Note
Default value of this property is false and should be changed as necessary.

Example: com.sun.am.policy.config.audit.logfile.rotate=false

Audit Log File Rotation Size

Key: com.sun.am.policy.config.audit.logfile.rotate.size
Description: This property specifies the approximate size of the Audit log file in bytes, which should be used to evaluate when the log file needs to be rotated.
Valid Values: Non-zero unsigned integer indicating the size in bytes to be used to evaluate when the log file needs to be rotated.

Note Default value of this property is 52428800 bytes (~ 50 MB) and should be changed as necessary. This property is not used if the Audit Log File Rotation Flag is set to false.

Example: com.sun.am.policy.config.audit.logfile.rotate.size=52428800

Debug Engine Configuration

Debug Level

Key: com.sun.am.policy.config.debug.level
Description: This property specifies the amount of debug messages that will be emitted by the Agent's Debug Engine.
Valid Values: Any of 0, 1, 3, 7, 15, and 31. These values indicate the following:
0 : No debugging
1 : Only Error messages
3 : Error and Warning messages
7 : Error, Warning and Brief Informational messages
15: Error, Warning and Verbose Informational messages
31: Error, Warning and Very Verbose Informational messages

Note For better performance of the system, this property should be set to a value 0. Values other than that will affect the system performance depending upon the amount of information the Debug Engine has to emit.
Values other than the ones specified in the Valid Values list above will lead to invalid configuration of the Debug Engine, thereby affecting the volume of messages that will be emitted.

Example: com.sun.am.policy.config.debug.level=7

Debug Log File

Key: com.sun.am.policy.config.debug.logfile.name
Description: This property specifies the Debug log file to be used for recording Debug messages.
Valid Values: String representing the complete path name of the file to be used by Agent to record Debug messages.

Note Be sure that the Application Server process has sufficient permissions to be able to write to this file.
Invalid or empty value of this property will lead to Debug messages not being logged in the log file.

Example: com.sun.am.policy.config.debug.logfile.name=/debug/agent_debug.log

Debug Log File Rotation Flag

Key: com.sun.am.policy.config.debug.logfile.rotate
Description: This property specifies if the Debug log file should be rotated by the Agent.
Valid Values: true/false

Note Default value of this property is false and should be changed as necessary.

Example: com.sun.am.policy.config.debug.logfile.rotate=false

Debug Log File Rotation Size

Key: com.sun.am.policy.config.debug.logfile.rotate.size
Description: This property specifies the approximate size of the Debug log file in bytes, which should be used to evaluate when the log file needs to be rotated.
Valid Values: Non-zero unsigned integer indicating the size in bytes to be used to evaluate when the log file needs to be rotated.

Note Default value of this property is 52428800 bytes (~ 50 MB) and should be changed as necessary.
This property is not used if the Debug Log File Rotation Flag is set to false.

Example: com.sun.am.policy.config.debug.logfile.rotate.size=52428800

Debug Time/Date Format String

Key: com.sun.am.policy.config.debug.date.format
Description: This property specifies the format of time stamp that is used to mark the exact time when the Debug message was recorded.
Valid Values: Valid java.text.SimpleDateFormat Time Format Syntax string. For more information, refer to:
http://java.sun.com/j2se/1.4/docs/api/java/text/SimpleDateFormat.html

Note The default value of this property is set to: [yyyy/MM/dd HH:mm:ss zzz] and should be changed as necessary.
Invalid value of this property will result in loss of time stamp data with debug messages.

Example: com.sun.am.policy.config.debug.date.format=[yyyy/MM/dd HH:mm:ss zzz]

Debug Print STDOUT Flag

Key: com.sun.am.policy.config.debug.print.stdout
Description: This property specifies if the Debug Engine should print the debug messages on Standard Output stream.
Valid Values: This property can have one of the following values:
true, indicates that the debug messages should be printed on STDOUT.
false, indicates that the debug messages should not be printed on STDOUT.

Note The default value of this property is true and should be changed as necessary. When set to true, the Debug Engine prints all debug messages on the Standard output stream. This results in the debug messages being displayed on the console window from where the WebLogic Server startup script was executed.
This property has no effect on the ability of Debug Engine to write to debug log files.

Example: com.sun.am.policy.config.debug.print.stdout=true

Troubleshooting Information

After installing the Agent, if you encounter any problems, the following could be the reasons:

Not supplied the fully qualified hostname while accessing PeopleSoft applications.

File Permission problems while creating Debug files.

The policy was not configured correctly on Sun ONE Identity Server. For information on configuring policy, refer Sun ONE Identity Server Administration Guide.

Sun ONE Identity Server user profile not updated with PeopleSoft userid.

Not used the same password while creating the DEFAULT_USER user that was supplied during setup. See "To Create DEFAULT_USER."

Incorrect Sun ONE Identity Server shared password supplied for agentadmin.

PeopleSoft application URL and Sun ONE Identity Server server are not in same DNS domain.

To enable this, install CDSSO component on Sun ONE Identity Server. Refer Sun ONE Identity Server Installation and Configuration Guide.

After installing the Agent, if the PeopleSoft Application does not start up generate a debug file to determine the problem.

Enable PeopleCode tracing on the Application Server using psadmin. The file LOGS/DEFAULT_USER_192.18.123.173.tracesqlis located at PS_HOME/appserv/domain/ is generated with the following trace/error message:

"..Java Exception..." messages indicates Sun ONE Identity Server jar setup problems.

Check the SSO Token validation invoked by PeopleCode:

/agent_install_dir/SUNWam/debug/PSAuthFilter

/agent_install_dir/SUNWam/debug/amPeopleCode file

Set the Sun ONE Identity Server Debug to identify and fix the Sun ONE Identity Server problems.

Uninstalling the Agent

When you install the Sun ONE Identity Server Policy Agent for PeopleSoft 8.3 software, an uninstallation program is created in the installation directory. Using this uninstallation program, the Agent can be removed completely from your system. While the uninstallation program deletes all the installed files from your system, certain files such as audit log messages are not deleted. You can delete them manually.
The uninstallation program for Sun ONE Identity Server Policy Agent for PeopleSoft 8.3 should be launched according to the steps detailed for Solaris or HP-UX platforms as applicable.

Note Make sure that WebLogic server and the PeopleSoft Application server are shut down before you uninstall the agent.

Launching the Uninstallation Program on Solaris 8

The uninstallation program for Solaris platform may be launched by executing the generated uninstall script located in the installation directory. The following steps provide details on how to achieve this:

Login as a PeopleSoft user. Example: psft

Go to the directory where the Agent is installed.

Set your JAVA_HOME environment variable to JDK version 1.3.1 or higher. If your system does not have the required version of JDK, use the JDK supplied with PeopleSoft. This JDK is located at:

PS_HOME/jre

Run the uninstall script. You'll find the script in the directory where you have installed the Agent. At the command line, enter the following command:

./uninstall_psagent

The installation program requires that you set up your JAVA_HOME variable correctly as pointed out in the Step 3. However, if you have set the JAVA_HOME variable incorrectly, the setup script will prompt you for the correct JAVA_HOME value:

Enter JAVA_HOME location (Enter "." to abort):

Specify the JAVA_HOME value to the installation program by typing the full path to the JDK installation directory. Otherwise, enter a period (.) to abort the installation.

In order that the GUI uninstallation program be displayed on your console, the DISPLAY environment variable of your shell must be set correctly. If your DISPLAY environment variable is not set at the time of invoking the setup script, the installation program will prompt you for the DISPLAY environment variable value as follows:

Please enter the value of DISPLAY variable (Enter "." to abort):

Provide the DISPLAY value to the installation program by typing the exact value at the above prompt. Otherwise, enter a period (.) to abort the installation.

Launching the Uninstallation Program on HP-UX 11

The uninstallation program for HP-UX platform may be launched by executing the generated uninstall script located in the installation directory. The following steps provide details on how to achieve this:

Login as PeopleSoft user. Example: psft

Go to the directory where the Agent is installed.

Set your JAVA_HOME environment variable to JDK version 1.3.1 or higher. If your system does not have the required version of JDK, use the JDK supplied with PeopleSoft. This JDK is located at:

PS_HOME/jre

Run the uninstall script. You'll find the script in the directory where you have installed the Agent. At the command line, enter the following command:

./uninstall_psagent

The installation program requires that you set up your JAVA_HOME variable correctly as pointed out in the Step 3. However, if you have incorrectly set the JAVA_HOME variable, the setup script will prompt you for the correct JAVA_HOME value:

Enter JAVA_HOME location (Enter "." to abort):

Provide the JAVA_HOME value to the installation program by typing the full path to the JDK installation directory. Otherwise, enter a period (.) to abort the installation.

In order that the GUI installation program be displayed on your console, the DISPLAY environment variable of your shell must be set correctly. If your DISPLAY environment variable is not set at the time of invoking the setup script, the installation program will prompt you for the DISPLAY environment variable value as follows:

Please enter the value of DISPLAY variable (Enter "." to abort):

Provide the DISPLAY value to the installation program by typing the exact value at the above prompt. Otherwise, enter a period (.) to abort the installation.

Uninstalling the Agent Using GUI

When you run the uninstallation script, the uninstallation program starts up. It alerts you that you must have Administrative privileges to run the uninstallation program.

Click Next to open the Welcome panel.

Click Next to open the Ready to Uninstall panel. This panel displays the product you are going to uninstall.

Click Uninstall Now to start uninstalling the Agent. The Agent is uninstalled. In the Uninstallation Summary panel, you can click Details for detailed information about the uninstallation. Click Close to end the program.

Uninstalling from the Command Line

To run the uninstallation program from the Command Line, you must run the setup program in the `nodisplay' mode. To do this:

Change to the directory where you have installed the agent.

Run the following command:

./uninstall_psagent -nodisplay

Follow the instructions on the screen to proceed with uninstallation.

At the following prompt, press Enter to uninstall the agent.

PRODUCT: Sun_TM_ONE Identity Server Policy Agent
LOCATION: /export/home/psft/agent
SIZE: 4.40 MB
------------------------------------------------
Sun(TM) ONE Identity Server Policy Agent 1.0 for PeopleSoft 8.3
Ready to Uninstall
1. Uninstall Now
2. Start Over
3. Exit
Choose one option from above [1] {"<" goes back, "!" exits}

**Code Example 5-1**
Init fn="load-modules" funcs="wl-proxy,wl-init"\
shlib=_libproxy_Dir/libproxy.so
Init fn="wl-init"

**Code Example 5-2**
<Object name="weblogic" ppath="*">
Service fn=wl-proxy WebLogicHost=myserver.com\
WebLogicPort=7001
</Object>

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

Last Updated January 20, 2003