VAM PeopleSoft Value-Added Module (VAM) Deployment Guide
Copyright Information 2018. SecureAuth is a registered trademark of SecureAuth Corporation. SecureAuth s IdP software, appliances, and other products and solutions are copyrighted products of SecureAuth Corporation. Revision History Version Date Notes 0.1 2017-03-16 Initial draft 1.0 2018-05-25 First draft completed 2.0 2018-09-27 Second version (largely rewritten) For information on support for this module, contact your SecureAuth support or sales representative: Email: support@secureauth.com inside-sales@secureauth.com Phone: +1.949.777.6959 or +1-866- 859-1526 Website: https://www.secureauth.com/support https://www.secureauth.com/contact 2
Table of Contents Introduction... 4 System Prerequisites... 4 Intended Audience... 4 Deploying & Configuring PeopleSoft... 5 Importing the SA_CIPHER Project... 5 Creating the SALOGIN User Profile... 8 Update Web Profile... 13 PeopleSoft PSCIPHER Encryption Key & Version Retrieval... 17 Adding PeopleSoft Signon PeopleCode... 22 Updating PeopleSoft to Default Requiring SecureAuth IdP Authentication (SP-Initiated)... 26 Setting Up Signon PeopleCode... 26 PeopleSoft Server Pages Update... 31 Deploying & Configuring a SecureAuth Appliance... 32 Setting Up the SecureAuth Realm... 32 Validating the Workflow... 33 Troubleshooting... 36 References... 37 Oracle: Employing Signon PeopleCode... 37 Version Review... 37 Penetration Testing... 37 3
Introduction This document details the deployment and configuration of the PeopleSoft Value-Added Module (VAM) on a SecureAuth IdP appliance that enables authentication and authorization of applications on PeopleSoft. System Prerequisites This documentation has been prepared using the following systems. PeopleSoft should be previously installed and operational and PeopleTools configured to support a two-tier connection to complete all required deployment steps. A three-tier connection cannot be used. + PeopleSoft 9.2 running on Linux 4.x (Tested using Oracle Linux Server UEK4 4.1.12-124.17.1.el6uek.x6_64) + PeopleTools 8.56.09 + Oracle Database 12c Intended Audience This guide is meant for technical staff tasked with setting up and configuring PeopleSoft for use with SecureAuth IdP through the deployment of the PeopleSoft VAM. This guide helps the reader perform the following: + Import a project from file to the PeopleSoft Oracle database to support encryption of the user name between SecureAuth and PeopleSoft + Create a user profile in PeopleSoft + Update the web profile to accept the new user profile + Obtain the encryption key and version used by PeopleSoft to be used between systems + Modify the system PeopleCode to process a protected cookie or URL parameter to provide a validated user to PeopleSoft originating from a SecureAuth realm + Modify the PeopleSoft system to support links embedded in the redirection from SecureAuth to support redirecting a user to an internal PeopleSoft page following a seamless login + Modify the expiration page used by the PeopleSoft instance for redirecting a user back to SecureAuth when their session has expired + Configure a SecureAuth realm to validate a credential and redirect the user to PeopleSoft server for seamless login 4
Deploying & Configuring PeopleSoft Please read this section to become familiar with the steps required to deploy and configure PeopleSoft. Importing the SA_CIPHER Project Before starting this task, the PeopleTools Application Designer must be configured to connect to the PeopleSoft database using two-tier. An application server connection cannot be used for database modifications. This project is imported to the system so the encryption key and version information can be extracted (shown in PeopleSoft PSCIPHER Encryption Key & Version Retrieval on page 14). This information can be used by the SecureAuth IdP to encrypt the user ID using the PeopleSoft defined private key. Steps to remove it are outlined later in this document. 1. Log into the PeopleSoft database using PeopleTools Application Designer. 2. Select Tools Copy Project From File 5
3. Navigate to the location where the PeopleSoft VAM was decompressed and select the PeopleSoft subfolder. 4. Click to select SA_CIPHER then the Select button. 6
5. Click to select the File radio button under the Use Project definition from section, then click OK. 6. Click Select All then click the Copy button. This completes the import of the encryption project to the PeopleSoft database. 7
Creating the SALOGIN User Profile To create the SALOGIN user profile, do this: 1. Using a web browser, log into PeopleSoft. The Oracle PeopleSoft website appears like this example. 2. Navigate to User Profiles. This can be found by using the Navigation bar (compass icon located at the top-right) then selecting Navigator PeopleTools Security, 8
9
... or by switching to PeopleSoft Developer at the top of the main page then click Security. The main User Profiles page appears like this example: 10
3. Select the Add New Value tab. The page like this appears: 4. Enter SALOGIN in the User ID field, create a password, and click Add as shown below. 11
5. Enter the password for the new User ID. 6. Select the ID tab and choose None for the ID Type as shown in the following example. 7. Click Save. A screen like the following example appears. 12
8. Accept this Warning by clicking OK. Update Web Profile To update the web profile, perform these steps: 1. Navigate to PeopleTools Web Profile Web Profile Configuration. 13
14
2. Leave the Profile Name begins with text box blank, then click Search to query for a list of available web profiles. 3. Select the active web profile. If you do not know which web profile is active (since the location of configuration.properties that determines which web profile is used can vary from system to system), you can determine the active web profile by searching Web Profile History. 15
Click Search and note the profile name. 4. Open the designated Web Profile Configuration page. 16
5. In the Public Users section, check the Allow Public Access box and set the User ID to SALOGIN then provide the password for the account created in Step 3 on page 12. 6. Click Save. PeopleSoft PSCIPHER Encryption Key & Version Retrieval To procure the PSCIPHER encryption key and retrieve the version number, do this: 1. Using the NavBar panel, navigate to the Enterprise Components option. 17
18
2. Enter CA_CIPHER:cipher in *Classpath field and getkey in the Class Method field, then click Submit. 19
3. Copy the key and Version values to a text editor then save them. You need these values in order to configure the SecureAuth realm starting in Deploying & Configuring a SecureAuth Appliance on page 29. 4. After you have copied the key and version values, delete the SA_CIPHER package from PeopleSoft for security purposes. 20
5. Select File Open then in the Definition text box, select Project. 6. In the Name field, enter SA_CIPHER then click Open. 7. From the left pane, expand the Application Packages folder. 8. Right-click the SA_CIPHER item and select Remove From Project. 21
Adding PeopleSoft Signon PeopleCode The record associated with PeopleCode must be configured for the Signon PeopleCode page. This code is triggered when a login attempt is made. 1. Select File New Field. 2. In the Label ID column, enter SA_AUTH. 3. Save the field definition by pressing CTRL-S then enter SA_AUTH in the Save Name As dialog box and click OK. 4. Create a new record by selecting File New Record. 22
5. Click OK. 6. In the Record dialog box, click the Record Type tab and select the Derived/Work radio button. 7. Select Insert Field. 8. In the Name field, enter SA_AUTH and select Insert, then click Cancel. 23
9. Press CTRL-S to save the new record. 10. At the Save As dialog box, enter SA_SIGNON then click OK. 11. Right-click the SA_AUTH entry and select View PeopleCode. 24
12. Copy/paste the contents of the SA_SIGNON_SA_AUTH.FieldDefault.ValidateUser.txt file located in the decompressed file under \PeopleSoft to the empty window. 13. Press CTRL-S to save the new PeopleCode to the record. 25
Updating PeopleSoft to Default Requiring SecureAuth IdP Authentication (SP-Initiated) You can set up a redirection to SecureAuth whenever a user attempts to navigate to and log in directly to the PeopleSoft server using their web browser. To do this, perform these steps. 1. Navigate to Web Profile Configuration Look & Feel (located at the bottom of the page as a hyperlink). 2. Change the Signon Result Doc Page field from signonresultdoctext.html to signonresultdocredirect.html. Notice the change is from doctext to docredirect. 3. Restart the web server(s) in order for the changes to take effect. Setting Up Signon PeopleCode The record associated with PeopleCode has to be configured for the Signon PeopleCode page. The code is triggered using the public guest credentials (that is, SALOGIN). The code has to be enabled along with the function, that is COMPANY_AUTH(), as explained below. 1. Navigate to PeopleTools Security Objects Signon PeopleCode. 26
27
28
2. Add a new row to the Signon PeopleCode matrix by clicking the + button on the last row to the far-right. 3. Enter the next incremental value available in Sequence. In this example, it is the number 7. 4. In the Record field, type FUNCLIB_LDAP2. It should auto-populate as you type. 29
5. In the Field Name field, type SA_AUTH. 30
6. In the Function Name field, enter Valid User. 7. Check the Exec Auth Fail box. 8. Click Save. PeopleSoft Server Pages Update To manage the logging out of a SecureAuth user when the user s session has expired in PeopleSoft, perform these steps: 1. Edit this page to specify the correct values: <<PS_HOME>>\webserv\peoplesoft\applications\peoplesoft\PORTAL. war\web- INF\psftdocs\<<SITENAME>>\Expire.html. 2. Replace the URL to SecureAuth expiry or Login URL in this manner: <meta http-equiv = "refresh" content = "0; url = <<SECUREAUTHURL>>.Restart.aspx" />. 3. After the code is updated, stop all application domains and the PIA web server. Clear the cache for all and restart the domains/pia. This is required before changes can take effect. This change updates the hyperlink and points to SecureAuth instead of the standard PeopleSoft login page. 31
Deploying & Configuring a SecureAuth Appliance This section provides detailed instructions on how to deploy and configure a SecureAuth IdP appliance for working with PeopleSoft and the SecureAuth VAM. Setting Up the SecureAuth Realm 1. In SecureAuth IdP Web Admin console, create a realm to handle this PeopleSoft integration. Configure the following tabs in the Web Admin Console before configuring the Post Authentication tab: Overview - the description of the realm and SMTP connections must be defined Data - an enterprise directory must be integrated with SecureAuth IdP Workflow - the way in which users access this application must be defined Multi-Factor Methods - the MFA methods that are used to access this page (if any) must be defined For information on doing this, refer to the SecureAuth IdP Realm Guide. 2. Copy the PSCipherLoginSSO.aspx and PSCipherLoginSSO.aspx.vb files located under the decompressed zip file s \SecureAuth directory to the SecureAuth IdP realm being used to handle SSO in PeopleSoft. For example, copy the files to D:\SecureAuth\SecureAuth1\Customized. 3. Open the realm s web.config editor. For instructions, click here. 4. Update the realm settings (web.config) to include the following values: <appsettings> </appsettings> /* obtained from PeopleSoft server. see deployment guide */ <add key="psversion" value="{v1.1}" /> /* obtained from PeopleSoft server. see deployment guide */ <add key="pskey" value="t0qn4iasdyoxtffll0wcoakxv6fdq8fr" /> /* example: http://<<fqdn>>:<<port>>/psc/ps/employee/hrms/c/nui_framework.pt_landingpage.gbl? <add key="psredirecturl" value="https://<<fqdn>>" /> /* when using PSAuthenticationMode=cookie, enter the common domain */ <add key="psdomain" value="domain.com" /> Do not replace the <appsettings> section. 5. Close the web.config and save the realm settings. 32
Validating the Workflow To validate the workflow: 1. Launch a browser session and direct to the SecureAuth realm used for PeopleSoft. For example: https://localhost/securauth/secureauth1/secureauth.aspx. 2. Log in with the user account you want to test. This account must be an valid account that is in the user store configured for the realm and accessible by PeopleSoft. 3. The browser redirects to PeopleSoft and logs the user in, taking them to the page specified in the PSRedirectURL configuration of the realm. 4. If an optional target was specified in the URL which may have come from a portal or email the user has access to, the browser redirects to the target URL. This example displays the home page for the user GMILES that was verified by the SecureAuth IdP realm after redirection from SecureAuth and successfully logged into PeopleSoft. 33
34
If an error is encountered during the process this screen is displayed. Further information is available in the log file outlined below for troubleshooting. 35
Troubleshooting To troubleshoot this deployment and configuration, consider the following steps: + If you experience any difficulty, close all browser sessions and attempt to enter the workflow again. If this does not solve the issue, restart the PeopleSoft system. + Credential validation is handled by standard SecureAuth realm functionality. Contact SecureAuth Technical Support if you encounter an issue with logging a user in at the SecureAuth realm level. + If you encounter the issue noted above where the user is logged in as SALOGIN, contact SecureAuth Technical Support and arrange for an online support session with your local PeopleSoft administrator that has access to PeopleSoft administrative functions as well as access to the operating system file system to retrieve log files. The log file for Signon PeopleCode can be found at the location specified in the Validate_User function described earlier in this document. A copy of the file SecureAuth.txt can be retrieved using SFTP to the server at \root\tmp\secureauth_sa_signon_sa_auth.fielddefault.txt. 36
References Oracle: Employing Signon PeopleCode Refer to: https://docs.oracle.com/cd/e26239_01/pt851h3/eng/psbooks/tsec/ chapter.htm?file=tsec/htm/tsec09.htm Version Review Compatibility PeopleSoft 9.2 PeopleTools 8.56.09 Oracle 12c Tested with PeopleSoft Fluid user interface Version 1.0 6/15/2018 Initial release supporting SSO from SecureAuth to PeopleSoft Version 2.0-9/15/2018 Replaced secure cookie with querystring parameter to support both on-premises and SaaS implementations Added support for SP-initiated workflow so when a user enters their credentials at a PeopleSoft login they will be redirected to SecureAuth Added expiration to encrypted token Added support for redirection after login to support deep links Redesigned the PeopleCode distribution to use a new Record instead of adding to FUN- CLIB_LDAP2 for PeopleCode Signon Penetration Testing Penetration testing validation is not within the scope of this document. Please contact SecureAuth for further information. 37