Publishing PeopleSoft with UAG

PeopleSoft is an extremely popular piece of software, but publishing it with UAG has always been a serious pain. The challenge with PeopleSoft is due to the fact that the PeopleSoft server generates cookies, but the application uses client-side code (Java and AJAX) to interact with these cookies. As UAG receives cookies from the backend server, it signs them with a unique signature (similar to how it signs URLs with the HAT mechanism) before passing them to the client computer. The reason for this process is so that if a client sends a subsequent request to UAG with these cookies, UAG can know to which application they pertain, so it can send them to the right server, and only it (you wouldn’t want a published SharePoint server to receive cookies generated by another SharePoint server…would you? That could lead to all sorts of problems…).

The client-side JavaScript or AJAX code uses these cookies to manage various things, like application data and session state, and so it looks for the cookies by their name. Since UAG changes the cookies name as part of the HAT process, the client side code is unable to find them, and goes nuts. Sadly, despite being such a complex and advanced application, PeopleSoft doesn’t have error-handling code and instead of alerting the user that there is a cookie problem, it errors out in various ways. The most common symptom is that it goes into a loop, saying that the session has expired. Another symptom is various JavaScript errors displayed by the browser, such as “Object expected” or “ 'ptGridObj_win0' is undefined”.

The good news is that these issues can be fixed(*), though it might be a bit of a struggle for those not familiar with UAG’s SRA mechanism. The trick is to tell UAG to avoid performing the HAT process on PeopleSoft’s cookies. To do so, you need to tell UAG to “touch” these cookies, which voids the signing process that would normally happen. “Touching” in this context is simply telling UAG to adjust a minor property of the cookie. As you may or may not know, UAG’s SRA mechanism is capable, among other things, to edit HTTP Headers. Cookies are a type of HTTP Header, and as such, UAG can create them, edit them, or delete them. When SRA modifies a cookie, it can change most of the cookie’s properties, which include the cookie’s name, cookie’s path, cookie’s domain and more.

* One exception to this is publishing multiple PeopleSoft applications. To make PS work, we have to prevent UAG from signing the cookies, and that means that if you publish multiple PeopleSoft applications, their respective cookies will overwrite each other, and would lead to session-related errors by the application. This is to be expected, and unfortunately, there’s no solution to this. The UAG HAT mechanism is specifically designed to prevent cookies from one application from conflicting with another, but since we’re overriding it here, this cannot be resolved. This means that publishing multiple PeopleSoft applications on the same UAG trunk, or on trunks with the same domain name is not supported.

The first step to making this happen is to make a list of the cookies we need to touch. The cookies that are in use differ between different PeopleSoft versions and applications, but here’s a general list:

.*PORTAL-PSJSESSIONID
SignOnDefault
ExpirePage
PS_LOGINLIST
PS_TOKENEXPIRE
.*https.*
PS_TOKEN

What I suggest is to start with the above list, and if it doesn’t work, enumerate your cookies (see below), and if you find another that’s not signed, expand the list. To touch the cookies, you need to create a custom SRA file, and place it in the trunk’s CustomUpdate folder:

<UAG Path>\von\conf\websites\<trunk>\conf\CustomUpdate

The file needs to be named WhlFiltSecureRemote_HTTPS.xml if your trunk is an HTTPS trunk, and WhlFiltSecureRemote_HTTP.xml if it’s an HTTP trunk (those are pretty rare because no sane administrator will let his finances to go out on the internet with no encryption, right?!). The structure of the file would be like this:

<WHLFILTSECUREREMOTE ver="2.2">            <COOKIES_HANDLING>                   <APPLICATION>                          <APPLICATION_TYPE>PeopleSoft</APPLICATION_TYPE>                           <URL>.*</URL>                           <Set-Cookie>                                   <NAME>.*PSJSESSIONID</NAME>                                   <Domain remove="true">WHL_SERVER_NAME</Domain>                                   <Path remove="true"></Path>                            </Set-Cookie>                      </APPLICATION>               </COOKIES_HANDLING> </WHLFILTSECUREREMOTE>

The indention is just for readability, and not mandatory. Beyond that, this is an XML file, so structure is very important – make sure you don’t forget to ‘close’ tags or mangle the structure otherwise. The above example shows “touching” only one cookie, but to touch multiple ones, you would simple repeat the structure that starts with <Set-Cookie> and ends with </Set-Cookie> as many times as you need. Another thing that might require editing is the Application Type. When publishing PeopleSoft, you would typically use the “Other Web Application(Portal Hostname) ” application type, which has you typing in a manual application-type in the 2nd page of the application wizard. Most people will simply type in “PeopleSoft”, but if you typed in something else, use it in your XML, on the 4th line of the file instead of PeopleSoft.

clip_image002

The Set-Cookie function itself needs only editing of the cookies name, to match the cookies you want to touch. The Domain remove and Path remove lines should remain as-is. As I said, some of the cookie names used by PeopleSoft change from server to server, and so when listing the cookies above, I listed a them above using RegEx, where the dynamic part of the cookie is replaced with the RegEx wild-card .* structure. Here’s an example of a file that contains all the above 7 cookies:

<WHLFILTSECUREREMOTE ver="2.2"> <COOKIES_HANDLING> <APPLICATION> <APPLICATION_TYPE>PeopleSoft</APPLICATION_TYPE> <URL>.*</URL> <Set-Cookie> <NAME>.*PORTAL-PSJSESSIONID</NAME> <Domain remove="true">WHL_SERVER_NAME</Domain> <Path remove="true"></Path> </Set-Cookie> <Set-Cookie> <NAME>SignOnDefault</NAME> <Domain remove="true">WHL_SERVER_NAME</Domain> <Path remove="true"></Path> </Set-Cookie> <Set-Cookie> <NAME>ExpirePage</NAME> <Domain remove="true">WHL_SERVER_NAME</Domain> <Path remove="true"></Path> </Set-Cookie> <Set-Cookie> <NAME>PS_LOGINLIST</NAME> <Domain remove="true">WHL_SERVER_NAME</Domain> <Path remove="true"></Path> </Set-Cookie> <Set-Cookie> <NAME>PS_TOKENEXPIRE</NAME> <Domain remove="true">WHL_SERVER_NAME</Domain> <Path remove="true"></Path> </Set-Cookie> <Set-Cookie> <NAME>.*http.*</NAME> <Domain remove="true">WHL_SERVER_NAME</Domain> <Path remove="true"></Path> </Set-Cookie> <Set-Cookie> <NAME>PS_TOKEN</NAME> <Domain remove="true">WHL_SERVER_NAME</Domain> <Path remove="true"></Path> </Set-Cookie> </APPLICATION> </COOKIES_HANDLING> </WHLFILTSECUREREMOTE>

Once your file is ready, place it in the target folder, and activate the UAG configuration. Before testing, make sure you clear the cache and cookies on the test client, and keep in mind that things don’t always go smoothly the 1st time around. With something as complex as PeopleSoft, it’s not unusual to go through a few iterations to get it all to play nice.

SRA not working?

Sometimes, you put in your SRA, but things still don’t work. Before you start fishing around for more cookies, the 1st thing you need to confirm is that your SRA itself is taking effect. To do so, record the session with a tool such as Fiddler or HTTPWatch, and inspect the resulting cookies. If you’re using Fiddler, for example, click on one of the URLs (preferably as close to the bottom of the list, so you can see all the cookies generated during the session). Then, click on Inspectors. On the top part of the screen, click on Cookies and observe:

clip_image004

As you can see above, the cookies are semi-colon delimited, and you can clearly see the names. If they were signed, it would look like this instead:

clip_image006

If you see all of the cookies carrying their original names (not the HATted names), then that means your SRA has taken effect, but the problem is caused by something else other than the cookies. If some of the cookies have been “fixed” (un-signed), then you might have specified the wrong names for some cookies in your SRA. If, however, none of the cookies have been taken-care of, and all are still signed (except UAG’s cookies, which are always unsigned anyway), then your SRA is not taking effect at all. Assuming you activated the configuration correctly, waited for the TMG storage to synchronize, cleared the client cookies and started a fresh session on the client, then perhaps something is wrong with the SRA structure. The most common cause for that is missing the application type. It’s possible that you set it right, but UAG is not identifying the incoming requests correctly. To check this, get a UAG trace, and look for the keyword TypeName, which show the application type like this:

[c]1890.1bc8 10/02/2012-08:44:02.372 [whlfiltsecureremote CGeneralManager::ProcessRequestHeader GeneralManager.cpp@1088] Info:ProcessRequestHeader(F85D091F-76D5-479D-8DF3-6277E94F878E): AppID(D8EF5151017D423EB8F7E4EBAE), AppName(FinancePortal), TypeName(PeopleSoft)

***If your server is in production, then it might be handling requests from many users, so you’ll have to first isolate your request based on the URL, and then, within that request, find the TypeName. A line such as the one above would typically appear in the trace within about 800-900 lines after the request begins.

If the TypeName you see in the context of your request is different than what you typed in the SRA file, adjust the SRA accordingly, activate and test again. You can also delete and re-create the app with a different TypeName, but changing the XML is usually easier and less risky.

Enumerating cookies

If things aren’t working, and you want to make sure you got the cookie list nailed down perfectly, the easiest way to do so is to connect to the application internally (from a computer on the corporate network, connected directly to the PeopleSoft web site, not through UAG), and record the session with a tool such as HTTPWatch or Fiddler. Don’t forget to clear your cookie store on the client first, so you don’t get dazed by irrelevant cookies. Then, inspect the cookie list, which would appear in plain-text similar to the screenshot above.