CONFIGURING AND TROUBLESHOOTING PEOPLESOFT SINGLE SIGNON
This resolution is meant to address the most common issues encountered when implementing or modifying Single Signon between PeopleSoft Applications (Enterprise Portal and HR for example). It doesn't cover 3rd Party authentication or customizations required to authenticate to/from PeopleSoft. Please note that we require 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 there 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 application server without entering user ID and password again.
*** Definition: Single Signon means that after a user has been authenticated by one PeopleSoft application server, that user can access a second PeopleSoft application server without entering user ID and password again.
*** EXAMPLE TRANSACTION:
See Enterprise PeopleTools 8.49 PeopleBook: Security Administration > Implementing 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
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 ID, 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 Remote Node on the second system. The reverse is also true; the Default Local Node of the second system must be represented with a Remote node of identical Name and Password on the first system. This is a basic trust relationship model.
2) The AuthTokenDomains must match between systems. This means that the following 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\sitename\applications\peoplesoft\PORTAL\WEB-INF\weblogic.xml file.
c) URI values on all nodes involved must include the fully qualified domain name, 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 Profile.
4) Nodes MUST use passwords or an SSL certificate.
5) The Nodes (both the Default Local and Remote node) must be trusted in all databases.
6) User ID must exist with same name (not necessarily same password) in both systems.
4) Nodes MUST use passwords or an SSL certificate.
5) The Nodes (both the Default Local and Remote node) must be trusted in all databases.
6) User ID must exist with same name (not necessarily same password) in both systems.
*** TROUBLESHOOTING COMMON ERRORS:
1) Your User ID and/or Password are invalid
a) AppServ Log: PeopleSoft Token authentication failed: invalid token signature
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 signature
b) Resolution: Password needs to match exactly between the two environments, Portal and content provider nodes
c) AppServ Log: Token authentication failed: issuing node PSFT_PA is not a trusted node
c) Resolution: Default Local Node of portal should be defined as a trusted node 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, Financials, 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 have 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 domain 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 local node in portal.
6) Link Errors
Resolution: Although not specifically a part of Single Signon, it's related, and the GSC gets many cases on this. Our delivered Single Link and Application links (e.g. EPM to Financials for ledgers) use a node, which is not the same as the remote node in your Portal database. This node is defined as the HPNODENAME in the Portal URL weblib parameter. In other words, a delivered link may fail because it is trying to pull content from the Portal registry simply because the node it's using hasn't been properly defined. Let's say you configure your portal with 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 link 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 message 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 the 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 the 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 the 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 password 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 content provider or the portal) then typically we see expiration issues with the content provider. Thus you get the signon screen. This is because customers 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 web 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 Authentication Domain value (General tab) must be set in all WebProfiles in use. Here is a sample of how it looks in the WebLogic XML:
-
CookieDomain .us.oracle.com
-
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:
Strange behavior, such as missing images and the following error message, especially 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.
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, we 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 still listed with the old protocol type.
Further, if both systems are using HTTPS, it will be necessary to load the ROOTCA and Public Key of the Portal into the Content Provider via PeopleTools > Security > Security Objects, Digital Certificates. This is required or you will 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 making the call (remote). For two way single signon, the reverse would also be true. So for Portal <> CRM SSO, the above needs to be completed and then the Portal not only has to have the ROOTCA and it's own public key (local), but also the 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 Internet. Unfortunately, the PeopleSoft database only has one default local node. Due to this fact, single signon to content providers will only accept one valid URL for a Portal system. In this regard, for example, an Enterprise Portal which is access via a Reverse Proxy webserver in a corporate DMZ would have a different URL from it's direct access via the internal (inside the firewall) webserver. Due to this, the content providers, such as Financials, CRM, HCM, etc. can only validate one of those addresses. Either the externally available or internally available URL. This poses a problem for customers who wish to setup SSO for 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 Solutions 9 Installation (Doc ID <<701192.1>>)
3. PeopleTools 8.49 PeopleBook: Security Administration > Implementing Single Signon
Every customer's situation is unique, as are their security requirements and infrastructure. For this reason, the GSC can not make recommendations for which path 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 implement SSO is considered out of scope. However, general information can be provided which may help and doing the actual setup is straightforward and supported:
Every customer's situation is unique, as are their security requirements and infrastructure. For this reason, the GSC can not make recommendations for which path 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 implement SSO is considered out of scope. However, general information can be provided 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 incoming traffic and redirect to the internal website through 1 port in the firewall. 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 because the end-user's browser actually makes the connection directly to SSO applications 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 same 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. This latter setup for redirection is out of scope. The PeopleSoft GSC supports setting up the rest of this environment where the internal and external users share 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 Balancer handles the session affinity and traffic redirection. Implementations such as this are out of scope, but more information can be found in the documentation listed above. The idea here being that an internal user touching the internal URL is actually remapped to the load balancer URL which is what is used for the Single 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 essentially puts them on the LAN/WAN and allows for access to content. However, this doesn't usually work for large external customer bases. It has been used for suppliers, contractors, and the like. This is likely the most secure scenario available. and there is no RPS involved in the configuration unless desired as another internal layer of security. In this scenario all users access the system via 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 internally behind the DMZ. The EP system would collect the content from the other PeopleSoft Applications and present it without the need for the users browser to actually "touch" those other applications. For this scenario, the EP system is granted access through an RPS in the DMZ, and the entire system must utilize an HTML template instead of the Default Dynamic Template. The problem here is that most of the Enterprise Portal features rely on dynamic templates and as such this option would limit functionality. This is generally never recommended and is only 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 provider.
8) AppServer log entry from the Content Provider time-stamped to the failure with test UserID info.
1. Enable a Reverse Proxy Server (RPS) inside the DMZ. This RPS would handle incoming traffic and redirect to the internal website through 1 port in the firewall. 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 because the end-user's browser actually makes the connection directly to SSO applications 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 same 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. This latter setup for redirection is out of scope. The PeopleSoft GSC supports setting up the rest of this environment where the internal and external users share 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 Balancer handles the session affinity and traffic redirection. Implementations such as this are out of scope, but more information can be found in the documentation listed above. The idea here being that an internal user touching the internal URL is actually remapped to the load balancer URL which is what is used for the Single 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 essentially puts them on the LAN/WAN and allows for access to content. However, this doesn't usually work for large external customer bases. It has been used for suppliers, contractors, and the like. This is likely the most secure scenario available. and there is no RPS involved in the configuration unless desired as another internal layer of security. In this scenario all users access the system via 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 internally behind the DMZ. The EP system would collect the content from the other PeopleSoft Applications and present it without the need for the users browser to actually "touch" those other applications. For this scenario, the EP system is granted access through an RPS in the DMZ, and the entire system must utilize an HTML template instead of the Default Dynamic Template. The problem here is that most of the Enterprise Portal features rely on dynamic templates and as such this option would limit functionality. This is generally never recommended and is only 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 provider.
8) AppServer log entry from the Content Provider time-stamped to the failure with test UserID info.
