7006122 configuring ps 8 portal v1

Configuring a PeopleSoft 8 Portal

Contains:

√ Portal Roadmap

√ Configuration Instructions

√ Troubleshooting Tips Prepared by: Michael Hillerman

December 24, 2001

Comments on this document can be submitted to [email protected]. We encourage you provide feedback onthis Red Paper and will ensure that it is updated based on feedback received.

When you send information to PeopleSoft, you grant PeopleSoft a non-exclusive right to use or distribute theinformation in any way it believes appropriate without incurring any obligation to you.

This material has not been submitted to any formal PeopleSoft test and is published AS IS. It has not been thesubject of rigorous review. PeopleSoft assumes no responsibility for its accuracy or completeness. The use of thisinformation or the implementation of any of these techniques is a customer responsibility and depends upon thecustomer's ability to evaluate and integrate them into the customer’s operational environment.

Configuring a PeopleSoft 8 Portal

3

Table of Contents

TABLE OF CONTENTS 3

CHAPTER 1 - INTRODUCTION 6

Structure of this Red Paper 6

Related Materials 6

CHAPTER 2 – PORTAL ROADMAP 7

Introduction 7

Configure the network and server environment 7

Configure the Portal 7

Configure Security 8

Define Users 9

Define Content 9

Customize the look and feel of the portal 10

CHAPTER 3 – CONFIGURATION OPTIONS 11

Load Balancing 11

Configuring a portal running under SSL to use HTTP connections to PIA on the same server. 16

Using an SSL Accelerator 18

Using a reverse proxy server 20

Configuring the portal to use a proxy server to access the Internet. 22

CHAPTER 4 - SESSION COOKIES 23

Weblogic session cookie settings. 23

Apache/JServ session cookie settings. 24

CHAPTER 5 – PORTAL CONTENT PROVIDERS 26

Configuring the portal content providers 26

CHAPTER 6 – CONFIGURATION PROPERTIES FOR THE PORTAL 27

AuthTokenDomain 27

PortalUseHttpForSameServer 29

DefaultScheme 29

DefaultPort 29

pswebservername 29

PortalHTTPPort 30

CHAPTER 7 – DELEGATING PORTAL ADMINISTRATION TO MULTIPLE GROUPS 30

Define an administrative permission list 31

Define an administrative role 32

Define which parts of the portal registry can be administered. 33

Define an administrative userid 36

CHAPTER 8 - SETTING UP SINGLE SIGNON 38

Scenario 1 – One database and one Webserver 39

Scenario 2 – Two or more databases with one web server 41

Scenario 3 – Two or more databases and two or more web servers 42

CHAPTER 9 – VERITY 44

Introduction 44

Verity Collections 45

Build Process 45

Searching a Collection 50

Debugging Checklist 51

CHAPTER 10 – TROUBLESHOOTING 52

Error Getting Content 52

You must have cookies enabled in order to sign in to your PeopleSoft application. 54

APPENDIX A – SPECIAL NOTICES 54

APPENDIX B – VALIDATION AND FEEDBACK 56

Customer Validation 56

Field Validation 56

APPENDIX C – REVISION HISTORY 57

APPENDIX D - BLOCKING NON-SSL CONNECTIONS 57

FilterEntry.java 57

FastFilterEntry.java 58

SlowFilterEntry.java 59

SimpleConnectionFilter.java 60

filter 72

2/21/2002

5

© Copyright PeopleSoft Corporation 2001. All rights reserved. 6

2/21/2002

Chapter 1 - Introduction

This Red Paper is a practical guide for technical users, installers, system administrators, and programmers whoimplement, maintain, or develop applications for your PeopleSoft system. In this Red Paper, we discuss guidelines onhow to diagnose a PeopleSoft Online Transaction environment, including PeopleSoft Internet Architecture and Portalconfiguration. Configuration of Batch processes is not covered in this document.

Much of the information contained in this document originated within the PeopleSoft Global Support Center and istherefore based on "real-life" problems encountered in the field. Although every conceivable problem that one couldencounter with Tuxedo, the PeopleSoft Application Server, or your web server is not addressed in this document, theissues that appear in this document are the problems that prove to be the most common or troublesome.

STRUCTURE OF THIS RED PAPER

This Red Paper provides guidance on a variety of aspects involved in configuring a PeopleSoft portal. It is organizedinto topics that prove to often be problematic for portal implementation teams.

Keep in mind that PeopleSoft updates this document as needed so that it reflects the most current feedback wereceive from the field. Therefore, the structure, headings, content, and length of this document are likely to vary witheach posted version. To see if the document has been updated since you last downloaded it, compare the date of yourversion to the date of the version posted on Customer Connection.

RELATED MATERIALS

This paper is not a general introduction to environment tuning and we assume that our readers are experienced ITprofessionals, with a good understanding of PeopleSoft’s Internet Architecture. To take full advantage of theinformation covered in this document, we recommend that you have a basic understanding of system administration,basic Internet architecture, relational database concepts/SQL, and how to use PeopleSoft applications.

This document is not intended to replace the documentation delivered with the PeopleTools 8 or 8.14 PeopleBooks.We recommend that before you read this document, you read the PIA related information in the PeopleToolsPeopleBooks to ensure that you have a well-rounded understanding of our PIA technology. Note: Much of theinformation in this document eventually gets incorporated into subsequent versions of the PeopleBooks.

Many of the fundamental concepts related to PIA are discussed in the following PeopleSoft PeopleBooks:

• PeopleSoft Internet Architecture Administration (PeopleTools|Administration Tools|PeopleSoft InternetArchitecture Administration)

• Application Designer (Development Tools|Application Designer)

• Application Messaging (Integration Tools|Application Messaging)

• PeopleCode (Development Tools|PeopleCode Reference)

• PeopleSoft Installation and Administration

• PeopleSoft Hardware and Software Requirements

Additionally, we recommend that you read the BEA documentation (in HTML format) delivered with the BEA CD-ROM,to gain a thorough understanding of the BEA products that PeopleSoft uses, Tuxedo, Jolt, and Weblogic Server 5.1.Refer to your PeopleSoft Installation and Administration book for directions on accessing the delivered BEAdocumentation.

2/21/2002


Chapter 2 – Portal Roadmap

INTRODUCTION

The initial installation of your PeolpleSoft portal is complete. The PeopleSoft installer has just departed to catch thelast flight home and has left you with a portal that is configured to work for a small number of sample users. The onlycontent in the portal is that which came pre-delivered with the product.

Now what?

This chapter will discuss the major areas that need to be configured to prepare your PeopleSoft portal to operate in aproduction environment. It will not attempt to address the details of how to configure each area, but will rather directyou to other chapters in this document as well as other PeopleSoft documents that will guide you through each task.

CONFIGURE THE NETWORK AND SERVER ENVIRONMENT

Build the physical network and server architecture necessary to support your development, testing, and productionenvironments. Customers must plan how to address the following topics:

Network

• Design – creation of subnets with appropriate routers and switches

• Security – appropriate use of firewalls, proxy servers, reverse proxy servers, and SSL

Webserver

• Hardware – appropriately sized servers

• Software – configured to optimize portal performance

• Load Balancing – solution to scale up to load requirements

Who should be involved

Network Administrators, Database Administrators

More information

Load Balancing and Network Architecture : Red Paper - Clustering and High Availability for PeopleSoft 8 - This redpaper provides instructions on how to configure your network switches, subnets, DMZ, webserver load balancer, andmore.

Webserver Tuning: Red Paper - Online Performance Configuration Guidelines for PeopleTools 8 – This red paperprovides useful information on tuning the BEA Weblogic webserver.

Configuring Webserver Session Cookies - This Document: Chapter 4 – Session Cookies. This chapter explainshow to configure the session cookie’s name and domain for the portal and content provider webservers.

CONFIGURE THE PORTAL

2/21/2002


The portal has a number of configuration options that facilitate its operation under a diverse set of physicalenvironments. Once the network and server environments are in place, then portal servlet will need to be configured forthe specific network and webserver configuration the customer has chosen.


Network Administrators, Webserver Administrators

More information

How to Use the Configuration Options of the Portal: This Document: Chapter 3 - Configuration Options. Thischapter explains how the portal configuration properties must be used with different combinations of networkconfigurations.

Configuration Properties of the Portal: This Document: Chapter 6 - Configuration Properties for the Portal. Thischapter defines the various properties in PeopleTools’ configuration.properties file that impact the portal.

CONFIGURE SECURITY

Establish security access control through the definition of permission lists and roles. The portal comes pre-configuredwith a set of roles and permissions that the customer can choose to customize or use as delivered. Roles definewhat groups of people have what set of permission lists. Permission lists define a group of securable objects. Acomprehensive role and permission list design is necessary to best manage which users can access each piece ofcontent in the portal.

A very powerful feature of PeopleTools security is the dynamic role. User membership to these roles is definedprogrammatically instead of via manually updating a membership list. They can significantly simplify managing roleassignments to users.


Security Administrators

More information

PeopleSoft Security Overview: PeopleBooks Library > Security > Understanding PeopleSoft Security – Discussesthe various options available to security administrators. Note the sections on Authentication and Signon PeopleCode,Role Assignments, and Cross System Synchronization.

Overview of security roles: PeopleBooks Library > Security > Roles - This PeopleBook chapter provides anoverview of how roles are defined and used to manage security access for users. It includes a discussion of usingdynamic roles to automate the management of role membership.

Batch process to rebuild all dynamic roles: PeopleBooks Library > Security > Setup Options and Processes >Execute Role Rules. This PeopleBook section describes the application engine program that can be used toregenerate role memberships for all dynamic roles.

2/21/2002


How to execute a role rule for one user: PeopleBooks Library > Security > User Profiles > Working with DynamicRole Rules.

PeopleCode functions used to implement dynamic role rules: PeopleBooks Library > PeopleCode Reference >PeopleCode Built-in Functions > ExecuteRolePeopleCode, ExecuteRoleQuery, and ExecuteRoleWorkflowQuery

Delegating Administration of Portal Content: This Document: Chapter 7 – Delegating Portal Administration toMultiple Groups This chapter discusses how to set up security to enable different organizations administering contentin the portal.

Configuring PeopleSoft Single Sigon: This Document: Chapter 8 – Setting up Single Sigon This chapterdiscusses how to configure PeopleSoft systems to “trust” one another and enable single signon.

DEFINE USERS

Most PeopleSoft Portal customers choose to define their user population in an LDAP compatible directory server.Doing so makes single signon between PeopleSoft systems simpler and provides a centralized definition of userprofiles that can be access by a variety of systems.


Security Administrators

More information

Overview of Directory Authentication: PeopleBooks Library > Security > Understanding PeopleSoft Security >Directory Server Integration.

Configuring Directory Authentication: PeopleBooks Library > Security > Setup Options and Processes > DirectoryAuthentication

Directories and PeopleSoft Red Paper: Red Paper - Directories and PeopleSoft

DEFINE CONTENT

Folders and Content References

As delivered, the portal contains pre-registered content organized within a set of folders and subfolders. We will referto this set of folders as the portal taxonomy. The taxonomy may need to be customized to fit the needs of yourorganization. Folders can be renamed, rearranged, or augmented as needed by your organization. Designing thetaxonomy for your organization may be a significant task depending on the amount of content you wish to exposethrough the portal and the number of organizations within your enterprise that will contribute content. Plan forextensive design work on this taxonomy if it must support a large body of diverse content.

The portal also has references to PeopleSoft application pages pre-delivered in the portal registry. These pages, likefolders, can be moved to different locations within the portal taxonomy if necessary. In addition to these PeopleSoftpages the portal can contain references to any HTTP accessible document. The placement of these contentreferences must be carefully designed in conjunction with the design of the portal taxonomy.

2/21/2002



Portal Content Administrators, Subject Matter Experts

More information

Understanding the portal registry: PeopleBooks Library > Portal Technology > Understanding the Portal Registry.This PeopleBook chapter provides a high level overview of the portal registry, folders, and content references.

Managing Folders and Content References: PeopleBooks Library > Portal Technology > Using PortalAdministration Features > Managing Folders and Content References. This PeopleBook chapter contains instructionson how to add, change, or delete a folder or content reference. It also provides instructions on moving a folder orcontent reference to a new position in the portal taxonomy.

Pagelets

Pagelets are the boxes of content that appear on the homepage. Pagelets are simply HTML documents that aredesigned to be size appropriate for insertion into a homepage. They can be static HTML files or dynamicallygenerated HTML from a variety of technologies. PeopleSoft portals come with a suite of pagelets, which are builtusing PeopleSoft Internet Architecture (PIA) technology. Customers can create their own dynamic pagelets using PIAor any other leading web enabling technology such as Java Server Pages, Java Servlets, Microsoft Active ServerPages, Pearl Scripts, and CGI programs.


Portal Content Administrators, Portal Developers

More information

Developing Pagelets: PeopleBooks Library > Portal Technology > Developing Pagelets - This PeopleBook chapterprovides instruction on how to build pagelets using PIA technologies.

CUSTOMIZE THE LOOK AND FEEL OF THE PORTAL

Customers can alter every aspect of the HTML generated by the portal to match their corporate branding requirementsand web site design. This is technically an optional step to rolling out the portal to a production environment.Therefore it is left to the discretion of each organization to determine the extent of changes they wish to make to theuser interface generated by the portal.


Portal Developers, Website Designer

2/21/2002


More information

Customizing the Portal Interface : Red Paper - Portal GUI Tips - This red paper provides instructions on how tocustomize the look and feel of all major aspect of the portal user interface. Everything from headers and footers, totemplates and pagelet borders is covered.

Chapter 3 – Configuration Options

LOAD BALANCING

Please refer to the Clustering and High Availability for PeopleSoft 8 red paper for a detailed discussion of loadbalancing configuration options with the PeopleSoft Internet Architecture.

Load balancing the portal can be achieved by using a hardware load balancing solution to distribute load acrossmultiple instances of the Weblogic server on multiple webserver machines. Many of today’s hardware load balancershave SSL accelerating options that should also be considered. The number, and size, of web server machines andthe number of web server instances per machine will vary depending load requirements and hardware selection.

The hardware load balancing solution must be configured to enable “sticky sessions” which ensure that all requestsfrom a user’s browser session are delivered to the same web server session. Multiple web server sessions on a singlemachine are recommended to keep the heap size of the JVM manageable and allow Java garbage collection to workoptimally.

Please refer to the Online Performance Configuration Guidelines for PeopleTools 8 Red Paper for a useful discussionon tuning the BEA Weblogic webserver and Java Virtual Machine.

Load Balancing Alternatives

There are three options that may be used to load balance the portal, a simple WebLogic cluster, an advancedWebLogic cluster, and an Generic Webserver Cluster.

2/21/2002


Simple Weblogic Cluster

In a simple Weblogic cluster there are one or more Weblogic instances per webserver host and there are more thanone webserver hosts for redundancy. There is one WebLogic proxy server running on its own independent host. Thearchitecture diagram is shown below:

Figure 1: Simple Weblogic Cluster - Please refer to the Clustering and High Availability for PeopleSoft 8 red paper for a detaileddiscussion of the advantages and disadvantages of this load balancing option, as well as instructions on how it can be configured.

Configuration Properties

Configure the portal to use the server name and port of the Proxy Host instead of the server name and port of itsWebhost. Edit the configuration properties file for each web server instance and change the following properties:

Configuration Property Value

pswebservername The DNS name of the ProxyHost.

DefaultPort The port the WebLogic proxy is listening on for either HTTPor HTTPS depending on how you have defined the “Portal”content provider.

Example:

pswebservername=portal.corp.com

defaultPort=443

Content Provider setup

Follow the directions in Chapter 5 to configure the portal content providers. Update the two server names in the URLsfor the “Portal” and “PortalServlet” content providers to point to the server name and port of the load balancer.

Example:

UPDATE PSPRDMCNTPRV SET PORTAL_URI_TEXT ='https://portal.corp.com/servlets/iclientservlet/peoplesoft8/' WHEREPORTAL_CNTPRV_NAM = 'Portal';

2/21/2002


UPDATE PSPRDMCNTPRV SET PORTAL_URI_TEXT ='https://portal.corp.com/servlets/psportal/peoplesoft8/' WHERE PORTAL_CNTPRV_NAM ='PortalServlet';

Advanced Weblogic Cluster

Use this architecture only if you cannot use the Generic Webserver Cluster discussed in the next section.This architecture improves the Simple Weblogic cluster by removing the single point of failure of the Weblogic proxyserver. High Availability is achieved by using a load balancer. The architecture diagram is shown below:

Figure 2: Advanced Weblogic Cluster - Please refer to the Clustering and High Availability for PeopleSoft 8 red paper for a detaileddiscussion of the advantages and disadvantages of this load balancing option, as well as instructions on how it can be configured.


Configure the portal to use the server name and port of the Proxy Host instead of the server name and port of itsWebhost. Edit the configuration properties file for each web server instance and change the following properties:


pswebservername The DNS name of the load balancer

DefaultPort The port the hardware load balancer is listening on foreither HTTP or HTTPS depending on how you have definedthe “Portal” content provider.

Example:


defaultPort=443

Content Provider configuration


2/21/2002


Example:



Hosts file configuration

The hosts file on the portal web server machines (WebHost1 and WebHost2 in figure 1 above) may have an entry thatdirects DNS requests for the portal content provider server name (portal.corp.com) back to the local WebHost. Thiswill allow the portal to make requests for content hosted on the same server directly without going back through theload balancer.

Example hosts file on WebHost1

123.123.123.10 portal.corp.com

Generic Webserver Cluster

This configuration requires PeopleTools 8.17. In a generic webserver cluster there is no need to install Weblogicproxy server and therefore one layer of indirection can be avoided. There are one or more Weblogic instances perwebserver host and there are more than one webserver hosts for redundancy. This configuration is recommended forsites that need to flexible enough to have the ability to change capacity on demand. All web hosts need not beidentical and load can be distributed according to host capacity (with most load balancers). High scalability isachieved by using HW load balancer to distribute the load directly across all the webserver instances. This is by farthe most flexible and scalable configuration. The architecture diagram is shown below:

Figure 3: Generic Webserver Cluster - Please refer to the Clustering and High Availability for PeopleSoft 8 red paper for a detaileddiscussion of the advantages and disadvantages of this load balancing option, as well as instructions on how it can be configured.

2/21/2002



This load balancing option requires that a copy of the configuration properties file be made for each web instance aplace under:

weblogic/myserver/psftdocs/peoplesoft8/<instance_name>/configuration.properties

So on WebHost1 in our example above we would have:

weblogic/myserver/psftdocs/peoplesoft8/webinstance1/configuration.properties

weblogic/myserver/psftdocs/peoplesoft8/webinstance2/configuration.properties

Each copy of the configuration properties file is identical, with the exception of the “PortalHTTPPort” property thatmust be set to the port the specific web instance is listening on.

Configure the portal to use the server name and port of the hardware load balancer instead of the server name and portof its Webhost. Edit the configuration properties file for each web server instance and change the following properties:


Pswebservername The DNS name of the load balancer.

DefaultPort The port the load balancer is listening on for either HTTPor HTTPS depending on how you have defined the “Portal”content provider.

PortalHTTPPort The port the web instance is listening on.

Example (for WebInstance1 on WebHost1):


defaultPort=443

PortalHTTPPort=5010

Content Provider configuration


Example:



Web Instance configuration

Each web instance must be started with a parameter identifying the name of the instance. The portal uses thisparameter as the server name for HTTP requests to the PIA servlet running on the same web instance. This preventsthe portal’s requests to PIA from being routed through the load balancer.

2/21/2002


Example:

StartWebInstance1.cmd

%JAVA_HOME%\bin\java -ms64m -mx64m -classpath %JAVA_CLASSPATH% -Dweblogic.class.path=%WEBLOGIC_CLASSPATH% -Dweblogic.home=. -Djava.security.manager -Djava.security.policy==.\weblogic.policy -Dweblogic.system.name=webinstance1 -DPSInstanceHost=websintance1 Psweblogic

startWebInstance1.sh

$JAVA $JAVA_OPTIONS -ms64m -mx64m -classpath $JAVACLASSPATH -Dweblogic.class.path=$WEBLOGICCLASSPATH -Dweblogic.home=. -Djava.security.manager-Djava.security.policy==`pwd`/weblogic.policy -Dweblogic.system.name=webinstance1- DPSInstanceHost=websintance1 PSweblogic

Hosts file configuration

The hosts file on the portal web server machines (WebHost1 and WebHost2 in figure 1 above) must have an entry thatdefines the DNS address of each web instance running on the machine.

Example hosts file on WebHost1

123.123.123.10 webinstance1 webinstance2

CONFIGURING A PORTAL RUNNING UNDER SSL TO USE HTTP CONNECTIONS TO

PIA ON THE SAME SERVER.

Customers often chose to run their Portal and PIA applications using SSL connections to secure the transmissionsbetween the browser and the web server. However, defining each homepage pagelet as an HTTPS request can causethe portal's performance to degrade significantly. The answer to achieving secure transmissions between the browserand the server and acceptable homepage performance is to configure the portal to use HTTP connections whenever itneeds to talk to a PIA application that is hosted on the same server as the portal.

HTTPS

Browser

WebInstance 1

iclientservletpsportal

HTTP

WebInstance 2

iclientservletpsportal

HTTP

WebHost1 123.123.123.10

HTTPS

WebLogic ProxyPort: 80/443

ProxyHost123.123.123.100

HTTPS

portal.corp.com 123.123.123.100DNS

This configuration requires changes to the PeopleTools web configuration properties file, as well as requiring aWeblogic filter be setup to block non-SSL connections except those from the portal (see Appendix D).

2/21/2002



Configure the portal to use the server name and port of the hardware load balancer instead of the server name and portof its Webhost. Edit the configuration properties file for each web server instance and change the following properties:


Pswebservername The DNS name of the web proxy or load balancer

PortalUseHttpForSameServer “true”

DefaultScheme “https”

DefaultPort The port the web proxy or load balancer is listening on forHTTPS.

PortalHTTPPort The value of this property varies depending on the loadbalancing option selected by the customer.

Simple WebLogic Cluster

The port the WebLogic Proxy is listening on for HTTP

Advanced WebLogic Cluster

The port the WebLogic Proxy is listening on for HTTPS


The port the web instance is listening on for HTTP

Examples using the configuration examples from the load balancing option section:



portalUseHttpForSameServer=true

defaultScheme=https

defaultPort=443

PortalHTTPPort=80

Advanced WebLogic Cluster (WebHost1)



defaultScheme=https

defaultPort=443

PortalHTTPPort=5000

Generic Webserver Cluster (WebInstance1 on WebHost1)



defaultScheme=https

defaultPort=443

2/21/2002


PortalHTTPPort=5010


Follow the directions in Chapter 5 to configure the portal content providers. Update the server name in the URLs forthe “Portal” and “PortalServlet” content providers to point to the server name and port of the load balancer.

Example:



USING AN SSL ACCELERATOR

It is recommended that customers use an SSL accelerator in front of their load balancer for optimal performance.

SSL Acceleratorport 443Browser

HTTPHTTPS

WebInstance 1123.123.123.11Port: 5010/5011


WebHost1 123.123.123.10

HTTPS

ProxyHost123.123.123.100




The configuration is very similar to that for configuring a portal running under SSL to use HTTP connections to PIA onthe same server, however you must change the default port to point to the port that the SSL accelerator is configuredto listen on. Note: you must continue to configure WebLogic to listen for HTTPS request, even though the acceleratorwill intercept all SSL connections. Failure to do so will cause the portal to not function correctly.

2/21/2002



pswebservername The DNS name of the load balancer



DefaultPort The port the SSL accelerator is listening on








Example:




defaultScheme=https

defaultPort=443

PortalHTTPPort=80




defaultScheme=https

defaultPort=443

PortalHTTPPort=5000




defaultScheme=https

defaultPort=443

PortalHTTPPort=5010

2/21/2002



Follow the directions in Chapter 5 to configure the portal content providers. Update the server name in the URLs forthe “Portal” and “PortalServlet” content providers to point to the server name of the web proxy or load balancer and theport of the SSL accelerator.

Example:



USING A REVERSE PROXY SERVER

Customers may want to set up a "DMZ" in front of the portal web server. This helps prevent unauthorized access tothe portal web server and creates a more secure environment. A "DMZ" is typically configured with a firewall allowingaccess to a reverse proxy server, which relays incoming request through a second firewall to the portal webserver.The second firewall is configured to only allow connections from the reverse proxy server.

BrowserFirewall

Reverse Proxy Serverportal.corp.com

IP: 123.123.123.100Port: 443

HTTPS HTTPS HTTPS

Firewall

HTTPS

portal.corp.com 123.123.123.110WebHost1: /etc/hosts



HTTPS

ProxyHost123.123.123.110



WebHost1 123.123.123.10


The configuration is very similar to that for configuring a portal running under SSL to use HTTP connections to PIA onthe same server, however you must make the following adjustments.

2/21/2002



Pswebservername The DNS name of the reverse proxy server.



DefaultPort The port the reverse proxy server is listening on for HTTPS.








Example:




defaultScheme=https

defaultPort=443

PortalHTTPPort=80




defaultScheme=https

defaultPort=443

PortalHTTPPort=5000




defaultScheme=https

defaultPort=443

PortalHTTPPort=5010

2/21/2002



Follow the directions in Chapter 5 to configure the portal content providers. Update the server name in the URLs forthe “Portal” and “PortalServlet” content providers to point to the server name and port of the reverse proxy server.

Example:



Hosts file setup

Environments using the Simple WebLogic Cluster option for load balancing must have an entry in the hosts file on theweb host that directs DNS requests for the content provider server name (the reverse proxy server) to the load balanceror web proxy. This will allow the portal to make requests for content hosted on the same server without going backthrough the reverse proxy server.

The hosts file is already setup for the Advanced WebLogic Cluster option and is not needed with the GenericWebserver Cluster option.

Example for a Simple WebLogic Cluster web host:

123.123.123.110 portal.corp.com

CONFIGURING THE PORTAL TO USE A PROXY SERVER TO ACCESS THE INTERNET.

It is often necessary for the portal to be running on a server that is connected to a secured subnet that does not havedirect access to the Internet. A proxy server is often setup to regulate access to the Internet. In this case the portalmust be configured to communicate with the proxy server in order to access these networks.

2/21/2002


For information on how to configure the portal to make HTTP(S) requests via a proxy server see PeopleBooks Library> Portal Technology > Miscellaneous Portal Information > HTTPS Support Through a Proxy Server.

Chapter 4 - Session Cookies

The BEA Weblogic and Apache JServ webservers use browser cookies to establish session identity. These cookieshave a default name that is used to retrieve the cookie on each request to the webserver. In an environment wheremultiple Weblogic or JServ webservers are in use with the portal it is necessary to define unique session cookienames between web servers to prevent one cookie from overwriting a cookie of the same name set by a different webserver.

Below are the procedures for setting the session cookie name and domain for both Weblogic and Apache/JServ.These procedures will make reference to the term PIAInstallName that represents a single logical instance of awebserver running a PeopleSoft application. As an example, consider a customer who has the followingenvironments:

Production: HRMS, Employee Portal

Test: HRMS, Employee Portal

Development: HRMS, Employee Portal.

This environment would normally have six webservers, one for each product in each environment and would requireeach webserver to use a distinct session cookie name.

We will give each webserver a distinct PIAInstallName:

Production: "PS_HRMS", "PS_Portal"

Test: "PS_HRMS_Test", "PS_Portal_Test"

Development: "PS_HRMS_Dev", "PS_Portal_Dev"

WEBLOGIC SESSION COOKIE SETTINGS.

2/21/2002


Edit the ..\weblogic\weblogic.properties file and add the following two lines:

weblogic.httpd.session.cookie.name=<PIAInstallName>_PSJSESSIONID

weblogic.httpd.session.cookie.domain=<AuthTokenDomain>

Where:

<PIAInstallName> = A distinct name from that of other WebLogic webservers that have PeopleToolsinstalled.

<AuthTokenDomain> = The domain used to set up single signon between PeopleTools systems. See thesection on the AuthTokenDomain configuration property in Chapter 6 for more information on defining thisdomain.

Example:

weblogic.httpd.session.cookie.name=PS_HRMS_Test_PSJSESSIONID

weblogic.httpd.session.cookie.domain=.corp.com

Restart the Weblogic webserver.

See http://www.weblogic.com/docs51/admindocs/http.html#session for more information of configuring WebLogicsession cookies.

APACHE/JSERV SESSION COOKIE SETTINGS.

You have to define unique JServ "zones" in order to have session cookies with unique names. Here are the steps torename the zone that is installed by default:

1. Edit the file ..\Apache JServ 1.1.2\conf\jserv.properties Change the name of the zone. For example:

Change

zones=root

root.properties=C:\Program Files\Apache JServ 1.1.2\servlets\zone.properties

to

zones=<PIAInstallName>

<PIAInstallName>.properties=C:\Program Files\Apache JServ 1.1.2\servlets\zone.properties

Where

<PIAInstallName> = A distinct name from that of other WebLogic webservers that have PeopleTools installed.

Example:

zones=PS_HRMS_Test

PS_HRMS_Test.properties=C:\Program Files\Apache JServ 1.1.2\servlets\zone.properties

2/21/2002


2. Edit the file ..\Apache JServ 1.1.2\conf\jserv.conf Bind the servlets directory to the new zone name.

Change

ApJServMount /servlets /root

ApJServMount /servlet /root

to

ApJServMount /servlets /<PIAInstallName>

ApJServMount /servlet /<PIAInstallName>

Where

<PIAInstallName> = A distinct name from that of other WebLogic webservers that have PeopleTools installed.

Example:

ApJServMount /servlets /PS_HRMS_Test

ApJServMount /servlet /PS_HRMS_Test

3. Edit the file ..\Apache JServ 1.1.2\servlets\zone.properties. Set the domain of the session cookie by changing thesession.topleveldomain property.

Change

#session.topleveldomain=.foo.com

to

session.topleveldomain=<AuthTokenDomain>

Where

<AuthTokenDomain> = The domain used to set up single signon between PeopleTools systems. See the section onthe AuthTokenDomain configuration property in Chapter 6 for more information on defining this domain.

Example:

session.topleveldomain=.corp.com

4. Restart your Apache webserver.

See http://java.apache.org/jserv/zones.html for more information of configuring JServ zones.

Important note regarding session cookie names.

The cookierules.xml file has been designed to work with the session cookie naming convention that all PeopleSoftwebserver session cookie names contain the string "PSJSESSIONID". If you choose not to follow this convention,you will need to add a section to cookierules.xml to specify that the session cookie must be deleted upon logout. Forexample, if your session cookie name is MYSESSION, then you must add the rule:

2/21/2002


<cookie name="MYSESSION" secure="false" > <delete_on_logout delete="true" /> </cookie>

Chapter 5 – Portal Content Providers

The portal depends upon the configuration of two content provider definitions in the portal database. Content providersdefine a web server and path used by the portal to access one or more web pages or applications. The portal has twoservlets that must be registered as content providers in order for the portal to function properly.

The “Portal” content provider

This content provider defines the PeopleSoft servlet named “iclientservlet” that responsible for serving up PeopleSoftInternet Architecture pages. All pages and pagelets that are delivered with the portal, including the portaladministrative pages are rendered by this servlet.

The “PortalServlet” content provider

This content provider defines the PeopleSoft servlet named “psportal” that is responsible for assembling homepagesand pages wrapped by portal templates.

Both of these content providers must be configured to point to the DNS name of the hardware device that each user’sbrowser will connect to. In a simple environment, this device would be the webserver that the PeopleSoft servlets arerunning on. In a more complicated environment, the device the browser is connecting to could be a load balancer orreverse proxy server.

CONFIGURING THE PORTAL CONTENT PROVIDERS

• Go to Start > Programs > PeopleTools 8.1x > Data Mover

• Open the ../scripts/PORTAL_SETUP.DMS file.

• Update the two server names in the URLs for the “Portal” and “PortalServlet” content providers to point to theserver name of the device that the end user’s browser will connect to.

• Make sure the scheme indicates the proper connection type. If you plan to use SSL connections then thescheme must be set to “https”.

• Run the data mover script.

Example:

UPDATE PSPRDMCNTPRV SET PORTAL_URI_TEXT ='http://portal.corp.com/servlets/iclientservlet/peoplesoft8/' WHEREPORTAL_CNTPRV_NAM = 'Portal';

UPDATE PSPRDMCNTPRV SET PORTAL_URI_TEXT ='http://portal.corp.com/servlets/psportal/peoplesoft8/' WHERE PORTAL_CNTPRV_NAM ='PortalServlet';

2/21/2002


Chapter 6 – Configuration properties for the portal

There are a number of configuration options within the configuration.properties file that can be used to control how theportal behaves in various network configurations. You can find the configuration.properties file located on thewebserver under:

../psftdocs/<sitename>/configuration.properties

Example

Windows: C:\weblogic\myserver\psftdocs\peoplesoft8\configuration.properties

Unix: /weblogic/myserver/psftdocs/peplesoft8/configuration.properties

AUTHTOKENDOMAIN

This property defines the DNS domain that the portal is running under. This property is used extensively throughoutthe PIA and portal runtime systems and it must be set for all websites, both portal and content. Some of the featuresthat depend upon this setting are:

• Single Signon between PeopleSoft applications. Failure to set the AuthTokenDomain correctly will prevent thePeopleSoft authentication cookie from being passed to the target PeopleSoft application that will force the targetsystem to re-authenticate the user.

• Cross frame JavaScript updates between PIA and the portal. Failure to set the AuthTokenDomain correctly on theportal and other PIA applications will cause JavaScript security errors to appear in the browser when PIA pagesare access through a portal frame based template (the default template that all PIA pages are displayed through isframe based).

• Cookie sharing between the portal and both PeopleSoft and third party web applications. If cookies need to beshared between web applications then each of the web applications must be accessed over a common domainname.

• PeopleCode global variable sharing between components running on the homepage and components runningwithin a frame. Failure to set the AuthTokenDomain correctly on the portal and other PIA applications will cause anew session to be created on the PIA webserver when the user accesses a component through a frame basedtemplate.

Webservers that provide content to the portal that wish to enable single signon or cookie sharing must run under asingle domain. This domain must be defined in the following four areas:

1. The domain set for the “AuthTokenDomain” configuration property on the web server.

..WebLogic/myserver/psftdocs/configuration.properties

AuthTokenDomain=.corp.com

Warning: Note that you need the leading ".". So it is ".corp.com” not "corp.com"

2. The domain set in the forwarding domain rule defined in the cookierules.xml file on the web server.

..WebLogic/myserver/psftdocs/cookierules.xml

2/21/2002


<cookie name="*" secure="false" >

<forward domain="*.corp.com" />

<delete_on_logout delete="true" />

</cookie>

3. The domain of the webserver session cookie. See the chapter on Session Cookies for more information ondefining session cookies for a webserver.

Apache: ../Apache JServ 1.1.2/servlets/zone.properties

session.topleveldomain=.corp.com

Weblogic: ../WebLogic/weblogic.properties

weblogic.httpd.session.cookie.domain=.corp.com

4. The domain of the URI of the portal content providers in the database.

..<pshome>/scripts/PORTAL_SETUP.dms

UPDATE PSPRDMCNTPRV SET PORTAL_URI_TEXT ='http://portal.corp.com/servlets/iclientservlet/peoplesoft8/' WHEREPORTAL_CNTPRV_NAM = 'Portal';

UPDATE PSPRDMCNTPRV SET PORTAL_URI_TEXT ='http://portal.corp.com/servlets/psportal/peoplesoft8/' WHERE PORTAL_CNTPRV_NAM= 'PortalServlet';

In addition to the setting the portal’s domain in the four areas described above, the same domain must be set for eachPeopleSoft application that the portal interacts with.

sales.i

Corporate Intranet

Browser Browser

hrms.corp.comcrm.corp.comportal.corp.com

Browser

In the example above the CRM and HRMS webservers would need to be defined with DNS names that include thesame domain name as the DNS name of the portal web server. They would also each need the “AuthTokenDomain”property set to this domain in their configuration properties file.

Web servers that do not have the same server domain as the portal can still be used to serve content to the portal.However, cookies set by the portal will not be forwarded to these servers. The sales server in our example abovewould be able to provide pages and applications to the portal, but it would not be able to host a PeopleSoft applicationthat supported single signon with the portal. If a content providing system is a PeopleSoft 8 system it must have it’sAuthTokenDomain set

2/21/2002


Þ Note: The example above would also require that unique session cookies are defined for each web server. Pleasereview Chapter 4 – Session Cookies for more information.

PORTALUSEHTTPFORSAMESERVER

Setting this property to “true” tells the portal to use HTTP connections for requests to the PIA servlet running on thesame webserver as the portal. When this property is set to “true” the DefaultScheme, DefaultPort, andPortalHTTPPort properties must also be set.

Setting this property is necessary when the portal webserver is behind an SSL accelerator or when SSL is terminatedon a device in front of the portal web server such as a reverse proxy server.

This property can also be used to improve the performance of homepage pagelets that are provided by the PIA servletrunning on the same webserver as the portal when that webserver is receiving SSL requests directly (i.e. SSL has notbeen terminated by a device in front of the web server).

Þ See Chapter 3 – Configuration Options for more information on using the PortalUseHttpForSameServerconfiguration property.

DEFAULTSCHEME

This property is used to override the scheme used by PIA and the Portal to construct HREFs. When this property isnot set the scheme of the incoming request to the PIA servlet is used to construct HREFs on a PIA or Portal page.

It is necessary to set this property when the browser makes an SSL connection and SSL is terminated prior to thePIA servlet using a device such as an SSL accelerator or a reverse proxy server, or by setting the configurationproperty PortalUseHttpForSameServer to “true”. In this situation the scheme of request to the PIA servlet is HTTP,however PIA must generate HREFs with an HTTPS scheme.

DEFAULTPORT

This property is used to override the port used by PIA and the Portal to construct HREFs. When this property is notset the port of the incoming request to the PIA servlet is used to construct link on a PIA or Portal page.

It is necessary to set this property when the port that the PIA servlet is accessed through is different than the port thebrowser connected to. This can occur when an SSL accelerator is used or when a reverse proxy server (RPS) isconfigured in front of the webserver, and the RPS listens on a different port than the webserver. It is also necessarywhen the configuration property PortalUseHttpForSameServer to “true” or when a load balancer is in use directlyrequest to webservers listening on different ports. In these situations PIA must generate HREFs with the port used bythe browser for its initial connection.

PSWEBSERVERNAME

This property is used to override the server name used by PIA and the Portal to construct HREFs. When this propertyis not set the server name of the incoming request to the PIA servlet is used to construct HREFs.

2/21/2002


It is necessary to set this property when the server that the PIA servlet is on is different than the server the browserconnected to. This can occur when a reverse proxy server (RPS) or load balancer is configured in front of thewebserver. In these situations PIA must generate HREFs with the server used by the browser for its initial connection.

PORTALHTTPPORT

Used by the portal to know what port to use for HTTP connections to the PIA servlet. This property is only used inconjunction with the PortalUseHttpForSameServer property.

Chapter 7 – Delegating portal administration to multiple groups

The portal administration pages will only allow a user to administer pages to which their userid has access. In orderto segment the administration of the portal registry between different groups of people it will be necessary to create aset of userids, roles, and permission lists for administrative access that are separate from the userids, roles andpermission lists assigned to people for general purpose access to the portal. For example, a user that is allowed toenroll in benefits and enter customer interactions as a general purpose user would not be allowed to administer bothsets of pages. Instead, a new userid is created that is granted roles that only have access to the content that the useris allowed to administer. Although the administrative userid has access to view the links and administer the foldersand content references, this userid does not actually have access to the application pages (e.g. actually processingcustomer interactions) because it doesn’t have the necessary menu item security in the PeopleSoft application.

Create one administrator role and permission list for each segment of the portal you wish to administer. For example,you might create a permission list such as HRAdmin with a corresponding role. The HRAdmin role would be grantedaccess to the HRAdmin permission list. Each person you wish to grant administrative privileges to would be given anadministrator userid that is distinct from their userid used for general-purpose access to the portal.

Note: The terms “Administrative Userid”, “Administrative Role”, and “Administrative Permission List” are used todescribe standard PeopleTools userid, role, and permission list security objects that have been created specifically foradministrative purposes.

For example Jane Doe might be given a userid called “Admin-Jane Doe” in addition to her general-purpose userid of“Jane Doe”. The userid “Admin-Jane Doe” would then be assigned to one or more of the administrative roles such as“HRAdmin”. When Jane logs in with her “Jane Doe” userid, she can not access the portal administration pages. Shecan only access the content that her general purpose roles provides access to. When she logs in with here “Admin-Jane Doe” userid, Jane can only see the HRMS content that she is allowed to administer along with the portaladministration pages.

The number of administrative roles you will need will depending on how granularly you wish to segment the content inthe portal. Consider the example portal registry below:

2/21/2002


We will create a segment in this registry for the HRMS department that will manage all content under the “ProcessGlobal Payroll” and “Benefits” folders. The HR department will also manage some of the content under the “EmployeeSelf-Service” and “Manager Self-Service” folders.

DEFINE AN ADMINISTRATIVE PERMISSION LIST

Create the administrative permission list: HRAdmin

Add the portal administrative pages to the list of pages that an HR Administrator can access. . This will eventually givethe Jane Doe administrative userid the ability to view and update the Portal admin pages. Permission to edit individualcrefs and folders is granted in a following step.

Grant authorization to access all components within the portal administration and portal personalize homepagemenus.

2/21/2002


Grant access to the following web libraries with full access to all scripts within each library.

DEFINE AN ADMINISTRATIVE ROLE

• Create the administrative role: HRAdministrator

• Assign the HRAdmin permission list to the HRAdministrator role.

2/21/2002


DEFINE WHICH PARTS OF THE PORTAL REGISTRY CAN BE ADMINISTERED.

Use cascading permission lists to indicate which parts of the portal registry the permission lists will grantadministrative access to.

• Add the HRAdmin permission list to the folders that have HR content within them. Specify “Cascade” on thosefolders that only contain content that is managed by the HR Administrator. You only need to specify a cascadingpermission at the highest point in the folder tree where HR only content begins. In our example we are addingHRAdmin to the “Benefits” folder that lives at the top of the folder hierarchy.

• Add the HRAdmin permission list to the “Portal Administration” folder and specify “Cascade”.

2/21/2002


All content registered below these folders will now automatically be assigned the correct administrative permissionlist. All userids that have the HRAdministrator role assigned to them will now be able to administer all content belowthe “Benefits” and “Process Global Payroll” folders. These userids will not have access to administer content in any ofthe sales or customer service folders.

Manually assign permission lists to folders that contain content administered by more than one group.

Assign the HRAdmin permission list to the Employee and Manager Self-Service folders. Do not make thesepermission lists cascade.

2/21/2002


These folders will contain content references to application pages managed by both groups. Our goal is to ensure thatthe HRMS Administrator can only administer content references owned by the HRMS department. If the HRAdminpermission list were made to cascade, then all content references under the Employee Self-Service folder, includingthose owned by customer service, would be visible to the HRMS Administrator. If content below these folders isorganized in department specific subfolders then cascading permission lists can be used at the subfolder level as inthe above section.

If a folder contains content references that belong to more than one group, then each content reference will need to beindividually assigned to the correct administrative permission list. Make sure that you assign the permission list toeach of the parent folders that the content reference is defined under. In the example below, the HRAdmin permissionlist would be added to the “Emergency Contacts” content reference as well as the “Personal Information” and“Employee Self-Service” (this was already added in our example in an earlier step) folders. These permission listassignments should not be made to cascade.

2/21/2002


Assign the administrative permission list to appropriate pagelets and pagelet categories

Indicate which homepage pagelets can be administered via this permission list by assigning it to pagelet categoryfolders and pagelet content references. Within the portal administration structure and content application navigate toBase Portal Data > Pagelets. Add the HRAdmin permission list to each folder containing pagelets that an HRAdministrator should be able to access. If a folder contains pagelets that are to be managed by only one group, thenyou can set the cascade option on the HRAdmin permission list assignment. All pagelets within this folder will beaccessible to the HRAdministrator role. If a folder contains pagelets managed by more than one group, then do notset the cascade option on the HRAdmin permission list assignment to the folder. In this case you will need to assignthe HRAdmin permission list to each content reference within the folder that an HR Administrator should be able tochange.

DEFINE AN ADMINISTRATIVE USERID

Now that you have administrative roles and permission lists defined which grant access to subset of the portalregistry, you must create new administrative userids for the people who are to administrator content in the portal. Donot assign the new administrative roles to a person general-purpose userid. Doing so will allow them to access theportal administrative pages and make administrative changes to objects that the user has general purpose access toas well as the content they have administrative access to. For example, a user that is allow to enroll in benefits andenter customer interactions as a general purpose user would not be allowed to administer both sets of pages. Instead,create a new administrative userid that only has access to the content they are allowed to administer.

Create the userid: Admin-JaneDoe

Add the “HRAdministrator” role to the Admin-JaneDoe userid.

2/21/2002


Log in as “Admin-JaneDoe” and you will see the following navigation pagelet:

Navigate to the “Structure and Content” page within Portal Administration and you will see:

The “Admin-JaneDoe” user id can now administer only the content that the HR department is responsible for.Navigating into the Benefits folder you will see:

2/21/2002


Navigating to the Employee Self-Service folder should look like this:

Chapter 8 - Setting up Single Signon

2/21/2002


Single Sign on is a feature in Tools 8.1 that allows a user to log in to a second PeopleSoft application serverwithout typing their id and password -- after they've successfully logged in to a first application server by typingtheir id and password.

This feature is critical to our Portal -- since the main purpose of the Portal is to aggregate application content fromvarious application servers. Users wouldn't tolerate a bunch of signon screens. Single signon is supported withPIA as well.

SCENARIO 1 – ONE DATABASE AND ONE WEBSERVER

In this scenario you have one database, and you want to sign on to the portal -- signing on to the portal is thecommon way you can use single signon with one database.

While single signon is configured at the database level (i.e. you specify time out minutes and trusted nodes for theentire database) its actually used any time you have two different PIA servlets connecting to the same database.When you sign onto the portal, there are two servlets involved -- the portal servlet, which proxies content andassembles pages, and the iClient servlet which executes iScripts to actually mark up the navigation header, thebreadcrumbs etc. Since the user only wants to see one signon page, we use single signon to propagate the loginfrom one servlet to the next.

Step 1. Make sure there is a "Local Message Node" defined in app designer. You can see if a local node isdefined by doing File --> Open --> Message Node, hit "enter" to search for all nodes defined for this system

The "X" in the "Local" column means the QE_LOCAL node is the "Local" node for this system.

You control which node is "Local" using the "Use" tab on the message node properties page. Open "QE_LOCAL"and go to File --> Object Properties

2/21/2002


If your system doesn't have a local node define, define one using this dialog.

Step 2. Make the local node a "Trusted" node for single signon, for your system. You control the trusted nodesusing Maintain Security--> Setup --> Single Sign on

You'll see this page

Make sure you're local node is in the list of "Trust Authentication Tokens issued by these Nodes"

Make sure the timeout min. is set to something reasonable like 720. Note that 720 minutes would be themaximum age of a token that this system will accept. This timeout parameter is controlled by the systemaccepting the token, not the system issuing a token. The system accepting a token for authentication controlshow old of a token it will accept, and which systems it trusts.

2/21/2002


SCENARIO 2 – TWO OR MORE DATABASES WITH ONE WEB SERVER

This scenario is similar to scenario 1, except you have to set up the application database to "trust" the portaldatabase. You also have one webserver with two different “sites”, one for the portal and one for a PeopleSoftapplication.

Step 1. Make sure databases A and B both have local nodes set up. For this example, we'll call the local nodein A "NODE_A" and in B "NODE_B". See the instruction in Scenario 1 for how to set up local nodes.

Step 2. Make sure databases A and B both have node definitions for each other. For example, A has a nodedefinition called "NODE_B" and B has a node definition called "NODE_A". Here's what it should look like in A.. (Bwould be the same except the X would be by B)

Step 3. Make sure the node password for "NODE_A" node definitions in A and "NODE_A" in B match. Do thesame for "NODE_B" in both databases. You set the node password for a node on the "Use" tab of the propertiespage for the definitions. Note that by default, nodes have a blank password, or "". If you create two new nodedefinitions in two databases, and leave the node password field blank (don't change it). Single signon will work. Ifyou change one however, and not the other, it won't work.

2/21/2002


Step 4. Make sure the nodes for the PeopleSoft application "Trusts" the portal node for single signon. In node A(the application database) add "NODE B" to the "Trust these Nodes list".

SCENARIO 3 – TWO OR MORE DATABASES AND TWO OR MORE WEB SERVERS

Follow the steps for Scenario 2. In addition, you need to do a couple more things...

Since single signon is implemented using browser cookies, you have to configure things so the user's browsersends the single signon cookie to each web server / machine they want to "single sign" on to. By default, thebrowser only sends cookies back to the machine that set the cookie. So if web server a.peoplesoft.com sets acookie (the user types their id and password into the signon page on A) , the browser will only send it back there.

2/21/2002


It won't send it to b.peoplesoft.com. You can make the browser send the single signon cookie to all servers atpeoplesoft.com by following the instructions for setting an AuthTokenDomain in Chapter 6. You will also need tomake sure that the session cookie names for each web server are unique by following the instruction in Chapter 4– Session Cookies.

When you change AuthTokenDomain, you may have to change the way you navigate to the server using thebrowser. You have to reference the web server using the full domain name, rather than just the machine name.For example, if you used to navigate to http://a/peoplsoft8/signon.html, you now have to go tohttp://a.corp.com/peoplesoft8/signon.html. Single signon from a.peoplesoft.com to b.peoplesoft.com won't workunless you have static IP addresses and DNS entries, or you update your hosts file as described in the nextparagraph.

If you're doing single signon between machines that don't have DNS entries, you can still do single signon bymodifying the "hosts" file on the machine that's running the web browser. For example, if I'm using machinea.peoplesoft.com to signon to the web server a.peoplesoft.com, then single signon to b.peoplesoft.com, I'dupdate the "../etc/hosts" file on a.peoplesoft.com as follows..

# Copyright (c) 1993-1999 Microsoft Corp.

#

# This is a sample HOSTS file used by Microsoft TCP/IP for Windows.

#

# This file contains the mappings of IP addresses to host names. Each

# entry should be kept on an individual line. The IP address should

# be placed in the first column followed by the corresponding host name.

# The IP address and the host name should be separated by at least one

# space.

#

# Additionally, comments (such as these) may be inserted on individual

# lines or following the machine name denoted by a '#' symbol.

#

# For example:

#

# 102.54.94.97 rhino.acme.com # source server

# 38.25.63.10 x.acme.com # x client host

127.0.0.1 localhost

216.131.221.88 a.peoplesoft.com

216.131.221.33 b.peoplesoft.com

2/21/2002


Chapter 9 – Verity

INTRODUCTION

This will cover the PeopleTools 8.1x codeline. PeopleSoft uses a third party search engine technology to achievesuperior performance and search results with Portal content. This technology is called PeopleSoft Search or VeritySearch after the company who owns the technology. Below is a basic architectural diagram of how Verity workswithin the PeopleSoft architecture.

Application Server

PeopleCodeSearch API

VerityCollection

BIFFile DAT

File

VerityBinaries

Web Server

VerityCollection

PeopleSoftDB

Cached InfoData

Process Scheduler

App. EnginePeopleCode

URLs

Files

The majority of the ties between PeopleSoft and Verity occur within an API. You can not see the details of how thePortal Collections are built or queried. This document will help you understand what is going on in the background tobetter debug any Verity errors.

2/21/2002


VERITY COLLECTIONS

A Verity Collection is a collection of data in a format that can be searched by the Verity binaries. The build processtakes data from the Portal Registry or file directories and creates a Collection. This collection is searched with Veritybinaries through a PeopleSoft API into Verity. This API masks much of the details around this integration.

PeopleBooks use of Verity is very different then PeopleTools use of Verity. Successful PeopleBooks searching doesnot indicate that your PeopleTools will be successful. They are separate configurations.

PeopleSoft finds its collections through a collection path, a collection name, and a language. Your ApplicationServers and Process Scheduler Server have the following configuration property in psappsrv.cfg and psprcs.cfg:

;-------------------------------------------------------------------------; Verity Dir / PSVERITYDIR; This is the directory where the Verity toolset is installed.; NOTE: this is not used in 8.1x, since Verity is installed in the app server.Verity Dir=

; Search Collection Path; This is an alternate directory that you can put non-portal collections in.Search Collection Path=C:\PeopleTools\pt814\data\search

The Verity Dir property is not currently used in the PeopleTools 8.1x codeline. You can ignore this setting. Theimportant setting is the Search Collection Path. This points to the root directory of where your collections are stored.

Your Process Scheduler Server must match your Application Server setting for PeopleSoft to find your collection.

PeopleSoft’s API will concatenate the Search Collection path with the collection name and then the database name and then thelanguage. The portal collection name is hard-coded as “Portal”, so if your database were called “PA8SP2”, your collectionpath would be interpreted as:

C:\PeopleTools\pt814\data\search\Portal\PA8SP2\Eng

This path must be accessible with permissions from your Application Server to successfully access the collection.

BUILD PROCESS

Portal Registry Collection

The Collection build runs in the Process Scheduler Server as an Application Engine process called PORTAL_INDEX.This process builds the collection in the path specified above. The first step of the process is to create an input.bifand input.xml file in the collection directory. These files are used to index the Portal Registry data.

• In PeopleTools version 8.14 and earlier, input.xml was named input.dat. If you are using this version ofPeopleTools, check for input.dat instead.

• If your build fails, make sure input.bif and input.xml were created successfully first.

2/21/2002


If your build fails, make sure input.bif and input.xml were created successfully first. If these files are not gettinggenerated, it is not a Verity problem. You will want to check your paths for accuracy and check your directorypermissions for access. Make sure your Process Scheduler Server can write these files.

The files have this type of structure:

Input.bif

# Document 0VdkVgwKey:{Portal}?ICType=Panel&Menu=PORTAL_PERS_HOMEPAGE&Market=GBL&PanelGroupName=PORTAL_HP_REMOVEVALID_FROM_DATE: 2000-06-12VALID_TO_DATE:CREATION_DATE: 2000-06-12CONTENT_PROVIDER: PortalURL: ?ICType=Panel&Menu=PORTAL_PERS_HOMEPAGE&Market=GBL&PanelGroupName=PORTAL_HP_REMOVEDOC_FN: D:/PeopleTools/mss/pt814/data/search/PORTAL/PRTL814/ENG/input.xmlDOC_OF: 0DOC_SZ: 814<<EOD>>

Input.xml

<RECORD0> <NAME> Component Remove Confirm Page </NAME> <DESCRIPTION> Home page component removal </DESCRIPTION> <AUTHOR> PTDMO </AUTHOR> <PRODUCT> PRTL </PRODUCT> <VALID_FROM_DATE> 2000-06-12 </VALID_FROM_DATE> <VALID_TO_DATE> </VALID_TO_DATE> <CREATION_DATE> 2000-06-12 </CREATION_DATE> <CONTENT_PROVIDER> Portal </CONTENT_PROVIDER> <URL>?ICType=Panel&Menu=PORTAL_PERS_HOMEPAGE&Market=GBL&PanelGroupName=PORTAL_HP_REMOVE</URL> <PATH> Root{PORTAL_ROOT_OBJECT}.Base Portal Data{PORTAL_BASE_DATA}.Home Page{HOME_PAGE}</PATH> <ATTRIBUTES> <PORTAL_HIDE_FROM_NAV> TRUE </PORTAL_HIDE_FROM_NAV> </ATTRIBUTES> <Menu> PORTAL_PERS_HOMEPAGE </Menu> <Market> GBL </Market> <PanelGroupName> PORTAL_HP_REMOVE </PanelGroupName></RECORD0>

These files contain relevant Portal Registry data to be searched and the security settings on that data. The input.biffile contains fields that can be searched and retrieved from the result collection. Retrieving a field value form the resultcollection is done through the SearchFields object and the ItembyName() method (see code example in “Searching aCollection” section). Input.xml contains field that can be searched, but can not be returned from the result collection.

After the input.bif and input.xml are created, the PeopleSoft API calls a Verity executable called “mkvdk”. OnWindows this is in your PS_HOME\bin\server\winx86\ directory. On Unix it is in your PS_HOME/bin directory. Youcan run the mkvdk command with no parameters to see all of its options.

When the collection is first built, the following command is getting executed through the API. This example is inwindows. Unix commands would be identical except for where the output goes. See the note below about log files.In addition, the paths would vary on Unix.

mkvdk -locale englishx -create -style C:\PeopleTools\pt814\data\search\PORTAL\style

2/21/2002


-collection C:\PeopleTools\pt814\data\search\PORTAL\PRTL814\ENG -bulk -insertC:\PeopleTools\pt814\data\search\PORTAL\PRTL814\ENG\input.bif

2/21/2002


In Unix, mkvdk is a shell script wrapper for the executable, mkvdk.bin. Running mkvdk through the shell script isrecommended because the shell will set up PATHs for you.

Lets break down the command line.

-locale englishxThis instructs the collection to be built in the English language.

-createThis instructs mkvdk to build the collection directory structure. This means the target collection directory is empty. Ifit is not empty this command will fail because of this flag.

-style C:\PeopleTools\pt814\data\search\PORTAL\styleThis instructs mkvdk to use the style files in the specified directory. Style files determine the collection structure andproperties. You should never modify these files for Portal collections!

-collection C:\PeopleTools\pt814\data\search\PORTAL\PRTL814\ENGThis instructs mkvdk to build the collection into the specified directory.

-bulk -insert C:\PeopleTools\pt814\data\search\PORTAL\PRTL814\ENG\input.bifThis instructs mkvdk to do a bulk insert into the collection structure based on this input.bif file. The input.bif file pointsat the input.xml file for further information.

This is the verity output:

mkvdk - Verity, Inc. Version 2.6.1 (_nti40, Jul 19 2000)BulkInserting into C:/PeopleTools/pt814/data/search/PORTAL/PRTL814/ENG (1) fromC:/PeopleTools/pt814/data/search/PORTAL/PRTL814/ENG/input.bif (0, 0)Initializing dataset 00000001.ddd, index 00000001.didTotals (316 documents): 316 para 325 sent 5306 word (1392 Kb used)Optimizing database layout(6198 ms) Indexed 316 docs intoC:/PeopleTools/pt814/data/search/PORTAL/PRTL814/ENG/00000001Writing partition index datamkvdk done

You can see that it inserted 316 documents (or records). This was successful. If there were any errors, you wouldsee them here. Another indication of success is that you will see files inside the “parts” directory under the collectiondirectory.

Inside that parts directory you should see files named “00000001.did” and “00000001.ddd”. The number stands foreach partition of the collection. This example represents the first partition. If these files do not exist, you collectionwas not built.

This is the command that would run if the collection already existed:

mkvdk -locale englishx -purge -collectionC:\PeopleTools\pt814\data\search\PORTAL\PRTL814\ENG

This clears out the collection. The process would then run this command:

mkvdk -locale englishx -collectionC:\PeopleTools\pt814\data\search\PORTAL\PRTL814\ENG -bulk -insert

2/21/2002


C:\UserApps\PeopleTools\pt814\data\search\PORTAL\PRTL814\ENG\input.bif

If you cannot get your Verity builds to work correctly, but your input.bif and input.xml files are getting generated, try torun these mkvdk commands by hand so you can view the errors. Remember that in windows you must execute thecommand form your PS_HOME\bin\server\winx86 directory.

The mkvdk processes will also generate log files. In windows it will be under your collection directory named“Englog.out”, in Unix it can be found under your PS_HOME/appserv/prcs directory named “veritybuild.log”. Inspectthese files for errors and debug them by running mkvdk by the command line. If you run mkvdk from the commandline on Unix, veritybuild.log will be found in your current working directory or in PS_HOME/data/search.

Once you successfully get mkvdk running via the command line, the Application Engine process should run now.

Portal File Directory Collections

There is an APRD available to allow your Portal Search to search through file directories. You must have patch R-GBIERN-XF6X8 installed to use this functionality. This process adds a new Application Engine Process,“EO_PE_SIDX”, to build separate collections for file directories. This allows you to search through many different filetypes and return links inside your portal. The process is slightly different then the Portal build process and debuggingmay be different. The setup screen appears below.

2/21/2002


The first difference is that this AE process uses a Java File object named “EoPeFile”. This object is used to check fileexistence, delete directories, create directories and run command lines. The command line to build the file directorycollection above is as follows:

vspider -style c:\PeopleTools\pt814\data\search\pa_epp_common\style -localeenglishx -start \\cypher\docs51 -collectionc:\PeopleTools\pt814\data\search\PS_EPP_FILES\Eng

The example above is used under Windows. Unix paths would differ.

Because this uses a Java Object, your JVM settings must be accurate on your Application Server.

JavaVM Shared Library=C:\Apps\weblogic\jre1_2\jre\bin\classic\jvm

Without this setting, the build process will fail when it tries to instantiate the Java object EoPeFile. This build processuses style files stored under the \data\search\pa_epp_common\style. If you customize your Search Collection path,you must copy the pa_epp_common directory under the new path.

Once you build your file collection, you will see a new directory name “PA_EPP_<NAME>” under your SearchCollection Path. This is your new collection. Inside that directory is a set of logs under spider\log. Check those logsfor more information about possible errors or bad files.

SEARCHING A COLLECTION

The Portal Registry Object has one main method to get a search object called GetSearchQuery(). TheGetSearchQuery method will return the Search Query object. You then will search on the object with the Execute()method. The Execute() method has two parameters: StartPosition and ChunkSize. StartPosition and Chunksize areused to chunk search results for improved performance or user interface.

Here is an example of the Portal Search:

&SearchKey = "search keywords";&StartPosition = 1;SearchResultChunkSize = 100;/*----------------------------------------------------------------------------- Get a portal registry object.------------------------------------------------------------------------------*/&Portal = %Session.GetPortalRegistry();/*----------------------------------------------------------------------------- Open the desired portal.------------------------------------------------------------------------------*/&Portal.Open("PORTAL")/*---------------------------------------------------------------------------- Get a search query object.------------------------------------------------------------------------------*/&SearchQuery = &PORTAL.GetSearchQuery();/*---------------------------------------------------------------------------- Set the text of the query the user entered------------------------------------------------------------------------------*/&SearchQuery.QueryText = &SearchKey/*---------------------------------------------------------------------------- Execute the search passing in the starting position and "chunk size" (get me thefirst 20 result or the third 20)

2/21/2002


------------------------------------------------------------------------------*/&SearchResultsColl = &SearchQuery.Execute(&StartPosition, &SearchResultChunkSize);/*----------------------------------------------------------------------------Get the first result.------------------------------------------------------------------------------*/&SearchResult = &SearchResultsColl.First();

While (&SearchResult <> NULL)/*--------------------------------------------------------------------------- Example of getting the key. In the portal case, the key is the URL, but inthe general case it could be a product id or some kind of other database key. ---------------------------------------------------------------------------*/ &SearchKey = &SearchResult.Key;/*--------------------------------------------------------------------------- Example of getting the Field. In the portal case, the field is the URL. Yes,it is redundant with the key but the key includes some {} around the URL and thisjust makes it easier to get the URL. ---------------------------------------------------------------------------*/&URLSearchField = &SearchResult.SearchFields.ItemByName("URL")&URL = &URLSearchField.Value/*--------------------------------------------------------------------------- Another example of a field using dot notation to simplify the code. ---------------------------------------------------------------------------*/ &ContentProvider =&SearchResult.SearchFields.ItemByName("ContentProvider").Value /*--------------------------------------------------------------------------- Call a function to insert the result into the page. ---------------------------------------------------------------------------*/ AddStuffToPage(&URL, &ContentProvider); /*--------------------------------------------------------------------------- Get the next result of the search. ---------------------------------------------------------------------------*/ &SearchResult = &SearchResultsColl.Next();End-While;&Portal.Close();

The most common reason a search would fail is that a collection was not found or was not built. Assuming thecollection was built correctly using the steps detailed in preceding sections, there may be an incorrect configurationproperty. Every application server used to search your Portal collection needs to point at the root collection directoryin its psappsrv.cfg. The property is called Search Collection Path. This must point at the directory parent to all yourcollections. It is most often pointing at PS_HOME/data/search.

There are unique situations where this setting is correct, but your search still fails. Contact GSC with these issuesbecause there have been bugs associated with certain operating systems.

DEBUGGING CHECKLIST

Problems Searching on HPUXYou may encounter the following error submitting a search in the search bar, when your Application Server (not yourwebserver or database server) is running on HPUX:

2/21/2002


You can work around this problem on the Application Server by doing the following:

$ cd $PS_HOME/bin$ mkdir _hpux11$ cd _hpux11$ ln –s bin ..

Verity’s search path for libraries on the HPUX platform does not include the current directory, instead it expects thelibraries to be found in _hpux11/bin. Symlinking this directory to where the libraries exist solves the problem. Thisproblem should go away in PeopleTools 8.16.

Is Verity installed?Check for mkvdk.exe in bin\server\winx86 or mkvdk.bin in /bin. If it is not there, you do not have Verity installed. Ifyou are building portal search collections on file directories or URLs you must also have the vspider.exe/vspider.bin inthose directories.

Did your Collection Build process succeed?Did the Application Engine succeed? If not, follow the steps in this document to debug any problems. Make sureyour directory security permissions allow writing the input.bif and input.xml files. Check the log files for errors and runcommand lines by hand to see errors first hand.

Do you see files inside the collection “parts” directory?This is the best verification that the build succeeded.

Does your Application Server configuration point to the same Search Collection Path as your ProcessScheduler?Check psappsrv.cfg and psprcs.cfg Search Collection Path setting. Do these match? You must build in the samelocation that you are searching.

Chapter 10 – Troubleshooting

ERROR GETTING CONTENT

2/21/2002


Examine the webserver log file:

Weblogic: ../WebLogic/myserver/weblogic.log

Apache: ../Apache JServ 1.1.2/logs/jserv.log

Typical messages:

• Unable to signon to server – check app server log. You will likely find an authentication error message thattells you what is wrong (e.g. node is not trusted, node password didn’t match, token expired, invalid certificate,user not defined).

1. If no authentication error is in the app server log then the PeopleSoft security cookie did not get passed to thePIA webserver. This usually occurs when the “AuthTokenDomain” in configuration.properties is not set or setincorrectly. Make sure the content provider of the target system has the same domain as the portal webserver and that this domain is set in the “AuthTokenDomain” configuration property. See Chapter 6 for moreinformation on configuring this property.

2. This also error occurs when a user personalizes their homepage prior to the AuthTokenDomain configurationbeing completed correctly. In this case, the error will only occur when a pagelet’s “Edit”, “Minimize”, or“Remove” icons are selected. Have the user re-save their personalization settings by navigating to the“Personalize Content” page and clicking on the “Save” button.

• Unable to get document – there is usually a stack trace with this message. The URL that the portal tried toaccess is usually listed here. Issues commonly are:

1) The URL is invalid.

2) URL is valid, but the servlet can’t access the page. This can happen when:

a) The servlet is not talking to a required proxy server, or when it is going through a proxy server when itshouldn’t. Copy the URL and paste it into a browser running on the same machine as the portal servletto see if the webserver machine can access the URL.

b) Third-party security software is preventing the call from going through (example: Netegrity’s SiteMinder).Possible resolution: Configure the security system to allow those calls or make sure portal servletpasses appropriate information (headers, cookies, etc) with the http call.

3) The URL returned an empty response. This can happen when an iScript returns nothing.

4) The URL is malformed – can mean URL has some kind of a typo.

• No such file or directory – common sources of this problem are:

1. The AuthTokenDomain is not defined correctly. The AuthTokenDomain section in Chapter 6 for information onhow to configure it correctly. Make sure the AuthTokenDomain does not have two periods at the beginning ofits value in both the configuration.properties and cookierules.xml files.

2/21/2002


2. The URL is invalid. Make sure the content provider for the URL is pointing the correct path and resource onthe web server. If the page is a PIA page, then make sure the content provider URI is pointing to the correctlocation of the iclientservlet.

YOU MUST HAVE COOKIES ENABLED IN ORDER TO SIGN IN TO YOUR PEOPLESOFT

APPLICATION.

Domain mismatch

This error is often caused by a mismatch between the domains defined for the following items:

1. The domain of the URI of the “Portal” and “PortalServlet” content providers

2. The domain set for the “AuthTokenDomain” configuration property.

3. The domain set in the forwarding domain rule defined in the cookierules.xml file.

4. The domain of the webserver session cookie

Make sure the domains match between these files. See Chapter 6 for more information on configuring theAuthTokenDomain configuration property.

Blank default template

Make sure that you have added a Default Template Name for the Content Provider in the Portal Database where theContent Provider is another PeopleSoft database. This is done by going to Portal Administration > General Settings >Content Providers. Do not leave the “Default Template Name” blank. If you leave this blank, you may encounter theerror "You must have cookies enabled…." when attempting to log on to the Content Provider (e.g., logging on to theHRMS or FIN database).

Appendix A – Special Notices

All material contained in this documentation is proprietary and confidential to PeopleSoft, Inc., is protected bycopyright laws, and subject to the nondisclosure provisions of the applicable PeopleSoft agreement. No part of thisdocumentation may be reproduced, stored in a retrieval system, or transmitted in any form or by any means,including, but not limited to, electronic, graphic, mechanical, photocopying, recording, or otherwise without the priorwritten permission of PeopleSoft, Inc.

This documentation is subject to change without notice, and PeopleSoft, Inc. does not warrant that the materialcontained in this documentation is free of errors. Any errors found in this document should be reported to PeopleSoft,Inc. in writing.

2/21/2002


The copyrighted software that accompanies this documentation is licensed for use only in strict accordance with theapplicable license agreement, which should be read carefully as it governs the terms of use of the software and thisdocumentation, including the disclosure thereof. See Customer Connection or PeopleBooks for more informationabout what publications are considered to be product documentation.

PeopleSoft, the PeopleSoft logo, PeopleTools, PS/nVision, PeopleCode, PeopleBooks, and Vantive are registeredtrademarks, and PeopleTalk and "People power the internet." are trademarks of PeopleSoft, Inc. All other companyand product names may be trademarks of their respective owners. The information contained herein is subject tochange without notice.

Information in this book was developed in conjunction with use of the product specified, and is limited in application tothose specific hardware and software products and levels.

PeopleSoft may have patents or pending patent applications covering subject matter in this document. The furnishingof this document does not give you any license to these patents.

The information contained in this document has not been submitted to any formal PeopleSoft test and is distributedAS IS. The use of this information or the implementation of any of these techniques is a customer responsibility anddepends on the customer's ability to evaluate and integrate them into the customer's operational environment. WhilePeopleSoft may have reviewed each item for accuracy in a specific situation, there is no guarantee that the same orsimilar results will be obtained elsewhere. Customers attempting to adapt these techniques to their own environmentsdo so at their own risk. Any pointers in this publication to external Web sites are provided for convenience only anddo not in any manner serve as an endorsement of these Web sites.

2/21/2002


Appendix B – Validation and Feedback

This section documents that real-world validation that this Red Paper has received.

CUSTOMER VALIDATION

PeopleSoft is working with PeopleSoft customers to get feedback and validation on this document. Lessons learnedfrom these customer experiences will be posted here.

FIELD VALIDATION

PeopleSoft Consulting has provided feedback and validation on this document. Additional lessons learned from fieldexperience will be posted here.

2/21/2002


Appendix C – Revision History

Authors

Michael A. Hillerman, Portal Product Strategy – PeopleSoft Development

Andrew Bediz, Portal Product Lead – PeopleSoft Consulting

Todd McKinnon, Portal Development Engineer – PeopleSoft Development

Reviewers

The following people reviewed this Red Paper:

• Michael Imperiale – PeopleSoft Consulting

• Thomas Hassler – PeopleSoft Global Support Center

• Stephen Bossong – PeopleSoft Consulting

Revision History

1. November 30, 2001: Published for internal review.

2. December 13, 2001: Second revision.

3. December 24, 2001: Initial Publication to Customer Connection.

4. January 23, 2002: Corrected hyperlinks to Red Paper references.

Appendix D - Blocking non-SSL connections

Follow these steps to configure Weblogic to deny all non-SSL connection requests from all addresses except from theaddress of the portal.

• Follow this URL to the BEA’s directions on how to install and compile the five files below:http://www.weblogic.com/docs51/examples/security/net/package-examples.security.net.html

Note: SimpleConnectionFilter.java and FastFilterEntry.java are slightly different that the versions delivered asexamples from BEA. These changes were made to work around problems with the classes discovered atcustomer sites.

• Edit the "filter" file and change "portalserver.mydomain.com" to match your portal webserver DNS name.

• Restart the webserver.

For more information on Weblogic filtering see: http://www.weblogic.com/docs51/classdocs/API_acl.html#filtering

FILTERENTRY.JAVA

2/21/2002


package examples.security.net;

import java.net.InetAddress;

/**

* Abstract filter rule.

*

* @author Copyright (c) 1999-2000 by BEA Systems, Inc. All Rights Reserved.

*/

abstract class FilterEntry

{

static final int ALLOW = 0;

static final int DENY = 1;

static final int IGNORE = 2;

private int protomask;

private boolean action;

protected FilterEntry(boolean action, int protomask)

{

this.protomask = protomask;

this.action = action;

}

int check(InetAddress addr, int protocol)

{

if (match(addr) && match(protocol))

{

return action ? ALLOW : DENY;

}

return IGNORE;

}

protected abstract boolean match(InetAddress addr);

protected boolean match(int protocol)

{

return protomask == 0 || (protocol & protomask) != 0;

}

}

FASTFILTERENTRY.JAVA

2/21/2002




/**

* Fast filter rule.

*


*/

class FastFilterEntry

extends FilterEntry

{

private int addrMask;

private int netMask;

FastFilterEntry(boolean action, int protomask, int address, int netmask)

{

super(action, protomask);

addrMask = address & netmask;

netMask = netmask;

}

protected boolean match(InetAddress addr)

{

if (addrMask == 0)

{

return true;

}

return (SimpleConnectionFilter.addressToInt(addr) & netMask) == addrMask;

}

}

SLOWFILTERENTRY.JAVA



/**

* Slow filter rule.

*


*/

2/21/2002


class SlowFilterEntry

extends FilterEntry

{

private String pattern;

SlowFilterEntry(boolean action, int protomask, String pattern)

{

super(action, protomask);

this.pattern = pattern.toLowerCase().substring(1);

}

protected boolean match(InetAddress addr)

{

return addr.getHostName().toLowerCase().endsWith(pattern);

}

}

SIMPLECONNECTIONFILTER.JAVA


import java.io.FileInputStream;

import java.io.FileNotFoundException;

import java.io.InputStream;

import java.io.InputStreamReader;

import java.io.IOException;

import java.io.LineNumberReader;

import java.io.StreamCorruptedException;


import java.util.StringTokenizer;

import java.util.Vector;

import weblogic.security.net.ConnectionEvent;

import weblogic.security.net.ConnectionFilter;

import weblogic.security.net.FilterException;

/**

* Simple rule-based connection filter example. This example reads in

* a set of rules from a file and bases its filtering decisions on

* these rules. 

*

* Syntax of the rule file is as follows: each rule is written on a

* single line. Tokens in a rule are separated by whitespace. "#" is

2/21/2002


* the comment character; everything after it on a line is ignored.

* Whitespace before or after a rule is ignored. Lines consisting

* solely of whitespace or comments are skipped. 

*

* All rules follow this form:

*

* <pre>

target action protocols

</pre>

*

* where <tt>target</tt> is a specification of one or more hosts to

* filter, <tt>action</tt> is the action to perform (and must be

* either <tt>allow</tt> or <tt>deny</tt>), and <tt>protocols</tt> is

* the list of protocol names to match (must be one of <tt>http</tt>,

* <tt>https</tt>, <tt>t3</tt>, <tt>t3s</tt>, or <tt>giop</tt>; if no

* protocols are listed, all protocols will match a rule). 

*

* This example recognizes two kinds of rule:

*

* <ul>

*

* <li>A "fast" rule applies to a hostname or IP address, with an

* optional netmask. If a hostname corresponds to multiple IP

* addresses, multiple rules are generated (in no particular order).

* Netmasks can be specified either in numeric or dotted-quad form.

* Examples:

*

* <pre>

dialup-650-555-1212.pa.example.net deny t3 t3s # http and https OK

192.168.81.0/255.255.254.0 allow # 23-bit netmask

192.168.0.0/16 deny # like /255.255.0.0

</pre>

*

* Hostnames for fast rules are looked up once, at server startup

* time. While this greatly reduces connect-time overhead, it can

* result in the filter having an out-of-date idea of what addresses

* correspond to a hostname. For maximal comfort of mind, use numeric

* IP addresses instead.

*

* <li>A "slow" rule applies to part of a domain name. Since it

* requires a connect-time DNS lookup on a client in order to perform

* a match, it may be much slower than the "fast" rule, and it may

* also be subject to DNS spoofing. Slow rules are specified as follows:

*

* <pre>

*.script-kiddiez.org deny

</pre>

*

2/21/2002


* The "*" only matches at the head of a pattern. If you

* specify one anywhere else, it will be treated as part of the

* pattern (and so that pattern will never match anything, since "*"

* is not a legal part of a domain name).

*

* </ul>

*

* When a client connects, these rules are evaluated in the order in

* which they were written, and the first rule to match determines how

* the connection is treated. If no rules match, the connection is

* permitted. 

*

* If you want to "lock down" your server and only allow connections

* from certain addresses, you can specify <tt>0.0.0.0/0 deny</tt> as

* your last rule. 

*

* Note that this example does not take full advantage of the

* information provided by the connection filter. Further expansion

* is left as an exercise for the reader. Note further that this

* example assumes IPv4 addresses, but it should be easy to convert it

* to use IPv6 addresses, if necessary.

*


*/

public class SimpleConnectionFilter

implements ConnectionFilter

{

/**

* The name of the filter rule file.

*/

public static final String FILTER_FILE = "filter";

/**

* This is our set of filter rules.

*/

private FilterEntry[] rules;

/**

* Construct a new connection filter. This constructor attempts to

* find the rule file in either the current directory or as a

* resource in the server's classpath.

*

* @see #FILTER_FILE

* @exception IOException a problem occurred while reading the rule

* file

*/

2/21/2002


public SimpleConnectionFilter()

throws IOException

{

InputStream in = null;

try

{

in = new FileInputStream(FILTER_FILE);

}

catch (FileNotFoundException e)

{

// ignore

}

if (in == null)

{

in = SimpleConnectionFilter.class.getResourceAsStream(FILTER_FILE);

}

if (in == null)

{

throw new FileNotFoundException("cannot find \"" + FILTER_FILE +

"\" in current directory or classpath");

}

setup(in);

}

/**

* Construct a new connection filter. Rules are read from the given

* stream.

*

* @param is stream to read from


* file

*/

public SimpleConnectionFilter(InputStream is)

throws IOException

{

setup(is);

}

/**

* Read rules from the given stream.

*

* @param is stream to read from

2/21/2002



* file

*/

private void setup(InputStream is)

throws IOException

{

LineNumberReader r = new LineNumberReader(new InputStreamReader(is));

Vector entries = new Vector();

String line;

while ((line = r.readLine()) != null)

{

// Ignore comments, surrounding whitespace, and empty lines.

int hash = line.indexOf('#');

if (hash != -1)

{

line = line.substring(0, hash).trim();

}

if (line.length() == 0)

{

continue;

}

try

{

parseLine(line, entries);

}

catch (StreamCorruptedException e)

{

throw new IOException("line " + r.getLineNumber() + ": " + e.getMessage());

}

catch (IllegalArgumentException e)

{

throw new IOException("line " + r.getLineNumber() + ": " + e.getMessage());

}

}

rules = new FilterEntry[entries.size()];

entries.copyInto(rules);

}

2/21/2002


/**

* Parse an individual line of the rule file. Any resulting rules

* are added to the given entries vector.

*

* @param line the line to parse (guaranteed not to contain

* comments, surrounding whitespace, or be empty)

* @param entries the running list of rules

*/

protected void parseLine(String line, Vector entries)

throws IOException, IllegalArgumentException

{

StringTokenizer toks = new StringTokenizer(line);

String addr = toks.nextToken();

boolean allow = parseAction(toks.nextToken());

// If it starts with a star, it's a slow rule.

if (addr.startsWith("*"))

{

SlowFilterEntry sent = new SlowFilterEntry(allow,

parseProtocols(toks),

addr);

entries.addElement(sent);

} else {

// It doesn't start with a star; it's a fast rule. Check for a

// netmask.

int slash = addr.indexOf('/');

int[] addrs = null;

int netmask = 0xffffffff; // if no explicit netmask, require exact match

if (slash != -1)

{

addrs = parseAddresses(addr.substring(0, slash));

netmask = parseNetmask(addr.substring(slash + 1));

} else {

addrs = parseAddresses(addr);

}

int protomask = parseProtocols(toks);

// We may have obtained multiple addresses from a DNS lookup.

// Add a rule for each. Note that most DNS servers will return

// multiple addresses in different orders on every lookup.

2/21/2002


for (int i = 0; i < addrs.length; i++)

{

FastFilterEntry fent = new FastFilterEntry(allow,

protomask,

addrs[i],

netmask);

entries.addElement(fent);

}

}

}

/**

* Filter a client connection event. If the connection should be

* allowed, this method returns normally.

*

* @param evt the connection event

* @exception FilterException the connection should be rejected by

* the server

*/

public void accept(ConnectionEvent evt)

throws FilterException

{

InetAddress remoteAddress = evt.getRemoteAddress();

String protocol = evt.getProtocol().toLowerCase();

int bit = protocolToMaskBit(protocol);

if (bit == 0xdeadbeef)

{

bit = 0;

}

// Check rules in the order in which they were written.

for (int i = 0; i < rules.length; i++)

{

switch (rules[i].check(remoteAddress, bit))

{

case FilterEntry.ALLOW:

return;

case FilterEntry.DENY:

throw new FilterException("rule " + (i + 1));

case FilterEntry.IGNORE:

break;

2/21/2002


default:

throw new RuntimeException("connection filter internal error!");

}

}

// If no rule matched, we allow the connection to succeed.

return;

}

/**

* This array is used for quick matching of protocols to bits. It

* should only contain protocols that the server supports.

*/

private static final String[] PROTOCOLS = new String[]

{

"http", "t3", "https", "t3s", "giop"

};

/**

* Parse a list of protocols and return a bitmask that will let us

* match a protocol quickly at connect time.

*/

protected static final int parseProtocols(StringTokenizer toks)


{

int protomask = 0;

while (toks.hasMoreTokens())

{

String tok = toks.nextToken();

int bit = protocolToMaskBit(tok);

if (bit == 0xdeadbeef)

{

throw new IllegalArgumentException("unknown protocol \"" + tok + "\"");

}

protomask |= bit;

}

return protomask;

}

/**

2/21/2002


* Parse a single protocol description into a bit in a field.

*/

private static final int protocolToMaskBit(String proto)


{

if (proto == null)

{

return 0;

}

proto = proto.toLowerCase();

for (int i = 0; i < PROTOCOLS.length; i++)

{

if (proto.equals(PROTOCOLS[i]))

{

return 1 << i;

}

}

// Magic return indicating no match.

return 0xdeadbeef;

}

/**

* Given a string, return an array of IPv4 addresses corresponding

* to that string as a host.

*

* @param str hostname or IPv4 address in string form

*/

protected static final int[] parseAddresses(String str)

throws IOException

{

InetAddress[] addrs = InetAddress.getAllByName(str);

int[] raw = new int[addrs.length];


{

raw[i] = addressToInt(addrs[i]);

}

return raw;

}

2/21/2002


/**

* Turn an address object into a single IPv4 address.

*/

static final int addressToInt(InetAddress addr)

{

byte[] roh = addr.getAddress();

int raw = 0;

for (int j = 0; j < roh.length; j++)

{

raw |= (0xff & roh[j]) << (8 * (roh.length - j - 1));

}

return raw;

}

/**

* Return an IPv4 netmask, as derived from a spec string. The

* string can either be a number, for a mask length, or a

* dotted-quad mask.

*

* @param maskStr mask spec string

*/

protected static final int parseNetmask(String maskStr)

throws IOException

{

StringTokenizer toks = new StringTokenizer(maskStr, ".");

int ntoks = toks.countTokens();

try

{

if (ntoks == 1)

{

int bits = Integer.parseInt(toks.nextToken());

if (bits > 32 || bits < 0)

{

throw new StreamCorruptedException("bad netmask: \"" + maskStr + "\"");

}

return ~((1 << (32 - bits)) - 1);

}

int mask = 0;

if (ntoks != 4)

2/21/2002


{


} else {

for (int i = 24; toks.hasMoreTokens(); i -= 8)

{

int num = Integer.parseInt(toks.nextToken());

if (num < 0 || num > 255)

{


}

mask |= num << i;

}

}

return mask;

}

catch (NumberFormatException e)

{


}

}

/**

* Parse an action and return its meaning. True to allow, false to

* deny.

*

* @param whatever the action string

*/

protected static final boolean parseAction(String whatever)

throws IOException

{

String action = whatever.toLowerCase();

if (action.equals("allow"))

{

return true;

}

else if (action.equals("deny"))

{

return false;

} else {

throw new StreamCorruptedException("bad action \"" + action + "\"");

}

2/21/2002


}

/**

* Simple test harness. You can use this to write rules by hand,

* and then check them.

*/

public static void main(String[] args)

throws Exception

{

System.out.println("Enter rules on separate lines:");

ConnectionFilter cf = new SimpleConnectionFilter(System.in);

LineNumberReader r =

new LineNumberReader(new InputStreamReader(System.in));

String line;

System.out.println("Enter addresses on separate lines:");

while ((line = r.readLine()) != null)

{

try

{

StringTokenizer toks = new StringTokenizer(line.trim());

String addr = toks.nextToken();

String proto = toks.nextToken();

InetAddress[] addrs = InetAddress.getAllByName(addr);


{

try

{

cf.accept(new ConnectionEvent(addrs[i], 0, 0, proto));

System.out.println("ALLOW");

}

catch (FilterException e)

{

System.out.println("DENY: " + e.getMessage());

}

}

}

catch (Exception e)

{

e.printStackTrace();

}

}

}

2/21/2002


}

FILTER

# This is a sample connection filter file.

# The following two rules deny access to all non-https connections to all

# addresses, except for the portal webserver which can acess http and https.

portalserver.mydomain.com allow http

0.0.0.0/0 deny http t3 t3s

7006122 configuring ps 8 portal v1

Documents