E-PORTAL: Configuring and Troubleshooting PeopleSoft Single Signon [ID 635969.

1] -------------------------------------------------------------------------------Modified 06-JAN-2010 In this Document Goal Solution References Type HOWTO Status PUBLISHED

--------------------------------------------------------------------------------

Applies to: PeopleSoft Enterprise PRTL Enterprise Portal - Version: 8.4 Information in this document applies to any platform. This document was previously published as Customer Connection Solution 200951811 Goal Documentation is needed to understand how Single Signon should be setup and what to do when there are problems encountered during the setup or after a migration , upgrade, environment change, etc. Solution This resolution is meant to address the most common issues encountered when impl ementing or modifying Single Signon between PeopleSoft Applications (Enterprise Portal and HR for example). It doesn't cover 3rd Party authentication or custom izations required to authenticate to/from PeopleSoft. Please note that we requi re the Portal's PeopleTools version to be >= the Content Provider's PeopleTools version. We have seen where they run without complying with that rule, but if t here is any issue, it will need to be replicated under this configuration before reporting it to development. *** Definition: Single Signon means that after a user has been authenticated by one PeopleSoft application server, that user can access a second PeopleSoft appl ication server without entering user ID and password again.

*** EXAMPLE TRANSACTION: See Enterprise PeopleTools 8.49 PeopleBook: Security Administration > Implementi ng Single Signon > Sample Single Signon Transaction for more details: 1) User Signs on to Enterprise Portal (PA) 2) PA Application Server Authenticates User 3) PA Application Server Generates SSO Token 4) Web Server Creates Cookie in User's Browser 5) User Accesses Content Provider Application (CP) 6) CP Web Server Receives PS_TOKEN Cookie 7) CP Application Server Authenticates PS_TOKEN

*** PS_TOKEN: is generated using either the database's SSL Certificate or User I D, Language Code, Timestamp, Issuing

System Default Local Node, Default Local Node Password which is encrypted using SHA1_Hash

*** CONFIGURATION FOR SINGLE SIGNON: 1) The Default Local Node of one system must match in Name and Password to a Rem ote Node on the second system. The reverse is also true; the Default Local Node of the second system must be re presented with a Remote node of identical Name and Password on the first system. This is a basic trust relation ship model. 2) The AuthTokenDomains must match between systems. This means that the followi ng must be consistent: a) Authentication Domain in the General Tab of the Web Profile must be set b) CookieDomain session parameter value must be set in the %PS_HOME%\webserv\s itename\applications\peoplesoft\PORTAL\WEB-INF\weblogic.xml file. c) URI values on all nodes involved must include the fully qualified domain na me, not simple machine names. 3) If systems use the same web server, defaultPort and defaultScheme must be set on the configuration.properties. If using 8.44+ PeopleTools, the Protocol and Port must be set on the Virtual Addressing tab of the Web Prof ile. 4) Nodes MUST use passwords or an SSL certificate. 5) The Nodes (both the Default Local and Remote node) must be trusted in all dat abases. 6) User ID must exist with same name (not necessarily same password) in both sys tems.

*** TROUBLESHOOTING COMMON ERRORS: 1) Your User ID and/or Password are invalid a) AppServ Log: PeopleSoft Token authentication failed: invalid token signatur e a) Resolution: Password needs to be set on Default Local Node and the password needs to match the remote node in Content provider b) AppServ Log: PeopleSoft Token authentication failed: invalid token signatur e b) Resolution: Password needs to match exactly between the two environments, P ortal and content provider nodes c) AppServ Log: Token authentication failed: issuing node PSFT_PA is not a tru sted node c) Resolution: Default Local Node of portal should be defined as a trusted nod e in content provider Navigate to PeopleTools > Security > Security Objects > Single Signon to add a trusted node (8.4 and above) Navigate to PeopleTools > Maintain Security > Setup > Single Signon (8.1x) d) AppServ Log: Error Setting Sign on PeopleCode context for User Error Setting App Server context to user d) Resolution: Userid need to match in both the environment for single signon to work successfully 2) STR_PCMINVPORTAL: Invalid portal name EMPLOYEE in request. Portal not defined . Unable to process request with an invalid portal. Resolution: Make sure that the Hosted by node of portal is defined as a remote

node in the content provider with the URL pointing back to portal. Typically this involves logging into the Content Provider Database (HR, Financi als, CRM , etc.) and opening the EMPL node in that system. The EMPL node URI values are setup to point back to the Enterprise Portal. The EMPL node within the Enterprise Portal system hosts the EMPLOYEE registry by default, so if any change has been made, a different node would hav e to be used. If The EMPL node of the Content Provider is setup, but is pointing to the wrong domain, the error message should say that the domai n is incorrect. 3) Cannot open http://url. Configuration.properties Resolution: Move one web server to a different machine. Add a second DNS entry for the web server in the same domain. Set the defaultPort and defaultScheme or In 8.44+, the Default Addressing on the Virtual Addressing tab of the Web Profile on both systems. Fix the PIA sitename 4) Authorization Error -- Contact your Security Administrator Resolution: Make sure to use the content provider node or a node with the same URI value while creating a CRef. If any other local node is used, it will result in the authorization error 5) You are not authorized to access this component Resolution: Content Provider node should always be a remote node and not a loc al node in portal. 6) Link Errors Resolution: Although not specifically a part of Single Signon, it's related, a nd the GSC gets many cases on this. Our delivered Single Link and Application links (e.g. EPM to Financials for led gers) use a node, which is not the same as the remote node in your Portal database. This node is defined as the HPNODENAM E in the Portal URL weblib parameter. In other words, a delivered link may fail because it is trying to pull content f rom the Portal registry simply because the node it's using hasn't been properly defined. Let's say you configure your portal wi th a remote node for the content provider. Since PeopleSoft has no way of knowing what that node is, we default everything to ERP, HRMS, CRM, etc. to correlate with our applications. Those delivered nodes do not have the proper URI values in order to attempt a l ink to the content provider, so the Portal is stuck trying to retrieve that content from it's own registry. It fails in this, and the error m essage depends on the Tools versions involved. Generally, there will be nothing on the screen but a URL which includes the Content Reference URI + the Portal Server URI. Be sure that the HPNODENAME value is set to a remote node that has it's URI information populated. The Node Name for th e content Reference itself should remain blank or set to LOCAL_NODE. 7) "This is not a valid site. The site name is case sensitive." is received in t he PIA window for SSO. This error can be resolved by using the proper case for the PIA SiteName in the URI value of your Node Definition. For example, if a customer is using http://server.company.com/psc/epprd/ in the URI value, but the actual URL value when you navigate to the site is http://server.company.com/psc/EPPRD/ it will cause this error. 8) Your Portal and content provider webserver time are not in sync. Make sure th e time and timezone are match on both servers.

***NOTES: For 8.1x PeopleTools, it has been noted that there can only be a 7-character pas sword on the nodes max. (so corresponding nodes must be the same as well). Also for 8.1x, there is only one Local Node (thus it is default) and node values are configured via App Designer, not online. If the AuthTokenDomain wasn't setup when PIA was installed (on either the conten t provider or the portal) then typically we see expiration issues with the content provider. Thus you get the signon screen. This is because customer s add the AuthTokenDomain to the webprofile, but fail to add the domain to the webserver's configuration. When seeing single signon related expiration issues, that you check the weblogic.xml for the session cookie domain and if it's not there, re-run the PIA install. Check this for the portal and all we b server content providers. If re-running the PIA install is not an option, an administrator can modify the %PS_HOME%\webserv\sitename\applications\peoplesoft\PORTAL\WEB-INF \weblogic.xml file manually by adding the following with the proper domain value. Additionally, the Authent ication Domain value (General tab) must be se t in all WebProfiles in use. Here is a sample of how it looks in the WebLogic X ML: - <session-param> <param-name>CookieDomain</param-name> <param-value>.us.oracle.com</param-value> </session-param> In OAS orion-web.xml, when authentication domain is not set during PIA install, will be missing. Here's example of OAS orion-web.xml when authentication domain is set during PIA install. Here's an example: <session-tracking cookie-domain=".domaintest.com" /> Strange behavior, such as missing images and the following error message, especi ally on Windows 2000 machines using IE can indicate that the Virtual Addressing tab of the webprofile needs a protocol, server and port set. Site name is not valid. Check your URL syntax and try again. On Pre 8.44 systems, this would be the default port and default scheme.

***HTTP/HTTPS: If the Portal is pulling in HTTPS content, it must be on HTTPS itself. Anytime SSL is used on the content providers, the Portal source must have SSL as well. This is a requirement. Also, when reconfiguring/cloning databases, w e often see where the original was HTTPS, but the subsequent clone doesn't have HTTPS setup yet. So, while it is using HTTP, all of the URI values are st ill listed with the old protocol type. Further, if both systems are using HTTPS, it will be necessary to load the ROOTC A and Public Key of the Portal into the Content Provider via PeopleTools > Security > Security Objects, Digital Certificates. This is required or you wil

l get an error similar to ' Untrusted Server Certificate Chain '. This simply means that the encrypted request from the Portal can't be decrypted by the Content provider. Since typically both system's share the ROOTCA when generating their public keys, both systems generally just load all of the following: 1) ROOTCA (generally shared) 2) Local Public Key 3) Remote Public Key of the calling system. For example, in a Portal > CRM SSO configuration, the CRM system would need the ROOTCA, it's own public key (local), and the public key of the Portal which is m aking the call (remote). For two way single signon, the reverse would also be t rue. So for Portal <> CRM SSO, the above needs to be completed and then the Por tal not only has to have the ROOTCA and it's own public key (local), but also th e public key of the CRM system (remote)

***ENVIRONMENTAL CONSIDERATIONS: When considering setting up Single Signon, many customers wish to have different internal vs. external access. This means one Intranet website setup and one In ternet. Unfortunately, the PeopleSoft database only has one default local node. Due to this fact, single signon to content providers will only accept one vali d URL for a Portal system. In this regard, for example, an Enterprise Portal wh ich is access via a Reverse Proxy webserver in a corporate DMZ would have a diff erent URL from it's direct access via the internal (inside the firewall) webserv er. Due to this, the content providers, such as Financials, CRM, HCM, etc. can only validate one of those addresses. Either the externally available or intern ally available URL. This poses a problem for customers who wish to setup SSO fo r internal users at one URL and for external users at a different URL. More information about this functionality can be found in the following: 1. Red Paper: Clustering and High Availability for Enterprise Tools 8.4x (Doc ID <<747378.1>>) 2. The Enterprise Portal Installation Guide: PeopleSoft Enterprise Portal Soluti ons 9 Installation (Doc ID <<701192.1>>) 3. PeopleTools 8.49 PeopleBook: Security Administration > Implementing Single Si gnon Every customer's situation is unique, as are their security requirements and inf rastructure. For this reason, the GSC can not make recommendations for which pat h to utilize for Single Signon, as it is considered a Consulting/Implementation matter. Each customer should evaluate their needs to make appropriate decisions based on requirements. As the GSC isn't equipped to make recommendations in general, selecting how to i mplement SSO is considered out of scope. However, general information can be pro vided which may help and doing the actual setup is straightforward and supported : Options Available: 1. Enable a Reverse Proxy Server (RPS) inside the DMZ. This RPS would handle in coming traffic and redirect to the internal website through 1 port in the firewa ll. However, since the browser makes direct connections to any content providers , Single Signon (SSO) will not function unless the PeopleSoft Applications (such

as HCM or CRM) are also accessible via an RPS system in the DMZ. This is becau se the end-user's browser actually makes the connection directly to SSO applicat ions as part of the transaction and from then on accesses that content directly even while Portal makes requests as well. For this setup, the node URI addresses as well as AuthTokenDomain, must reflect the URL the users will actually use to access the system (i.e. the external URL) . This generally means that either internal and external users must use the sam e URL to access the system (the external URL), or the internal URL is otherwise redirected or "spoofed" at the DNS level so while it might appear to users they are on the internal URL, they are actually accessing the system via another. Th is latter setup for redirection is out of scope. The PeopleSoft GSC supports se tting up the rest of this environment where the internal and external users shar e the same setup. For more detailed assistance, the Server Tools team in the GSC would need a new SR created asking for "how to setup Reverse Proxy Server". 2. Utilize Load Balancing systems to virtualize the URLs used. The Load Balance r handles the session affinity and traffic redirection. Implementations such as this are out of scope, but more information can be found in the documentation li sted above. The idea here being that an internal user touching the internal UR L is actually remapped to the load balancer URL which is what is used for the Si ngle Signon setup. The GSC has no documentation on this scenario and customers are urged to discuss with their consulting partner or seek assistance from other customers via Rugs and User Support group websites for PeopleSoft. 3. As is the case at many customers, external (internet) users access a Virtual Private Network, or VPN, system to gain internal access to the network. This ess entially puts them on the LAN/WAN and allows for access to content. However, thi s doesn't usually work for large external customer bases. It has been used for s uppliers, contractors, and the like. This is likely the most secure scenario ava ilable. and there is no RPS involved in the configuration unless desired as anot her internal layer of security. In this scenario all users access the system vi a an internal URL which is inaccessable via the DMZ. 4. It is possible, however not recommended, to utilize the Enterprise Portal (EP ) as a sort of Proxy server itself. Single Signon would take place, but all inte rnally behind the DMZ. The EP system would collect the content from the other Pe opleSoft Applications and present it without the need for the users browser to a ctually "touch" those other applications. For this scenario, the EP system is gr anted access through an RPS in the DMZ, and the entire system must utilize an HT ML template instead of the Default Dynamic Template. The problem here is that mo st of the Enterprise Portal features rely on dynamic templates and as such this option would limit functionality. This is generally never recommended and is onl y rarely implemented. ***GSC ASSISTANCE: If you are unable to resolve the issue, the following should be sent to your GSC analyst handling the case: 1) weblogic.xml or server.xml (Websphere) from both systems 2) Application and PeopleTools releases from both systems 3) SELECT * from PSMSGNODEDEFN from both systems 4) SELECT * from PSNODEURITEXT from both systems 5) SELECT * from PSTRUSTNODES from both systems 6) SELECT * from PSWEBPROFDEF from both systems or the configuration.properties file if 8.1x/8.2x PeopleTools 7) Screenshot of the Content Reference page used to connect to the content provi der. 8) AppServer log entry from the Content Provider time-stamped to the failure wit h test UserID info.

RELATED INFORMATION: Document:623401.1: E-PORTAL: e same WebServer Document:649989.1: E-PORTAL: f the Content Provider? Document:654804.1: E-PORTAL: Document:623401.1: E-PORTAL: e same WebServer Document:614537.1: E-PORTAL: Search (97,1) Document:652758.1: E-PORTAL: out:blank, not target

Single Signon is failing when both systems share th Will our Enterprise Portal work with this version o Missing Images on Homepage Header and CP Pagelets Single Signon is failing when both systems share th Can't Build Search Index on Portal - Failed to open "New Window" link in content provider page opens ab

Single Signon Advisor Session Presentation attached (contact GSC if unavailable) References NOTE:652029.1 - E-PORTAL: Implementing single signon between Oracle and PeopleSo ft applications Document:623401.1 - E-PORTAL: Single Signon is failing when both systems share t he same WebServer Document:649989.1: E-PORTAL - Will our Enterprise Portal work with this version of the Content Provider? Document:654804.1: E-PORTAL: Missing Images on Homepage Header and CP Pagelets Document:612426.1: E-PORTAL: Is it possible to Single Signon to a domain with a different name? Document:614537.1: E-PORTAL: Can't Build Search Index on Portal - Failed to open Search (97,1)