Single Sign-On Guide. PrismHR API 1.14

Transcription

1 Single Sign-On Guide PrismHR API 1.14

2 Copyright Notice The information in this document is subject to change without notice. PrismHR shall not be liable for any technical or editorial errors contained herein or for incidental or consequential damages resulting from the performance, furnishing, or use of this publication. The software described in this document is furnished under license and may be used or copied only in accordance with the terms of that license. No part of this documentation may be reproduced or transmitted in any form or by any means, electronic or mechanical, including (but not limited to) photocopying, recording, scanning, or retrieval system, for any other than the purchaser s personal use without the express written permission of PrismHR. The company data contained in the examples within this document are fictitious and any resemblance to real people, places, or companies is purely coincidental. PrismHR, HRPyramid, and HRPyramid Web Edition are trademarks of PrismHR. All other brand and product names are trademarks or registered trademarks of their respective owners. Company Website: Customer Resource Center: HRP-14.2-SSOV September 2018 by PrismHR. All rights reserved.

3 Table of Contents Table of Contents Copyright Notice ii Table of Contents iii Chapter 1: Introduction 1 Intended Audience 1 Requirements 1 Conventions 1 Chapter 2: Overview 3 Security 3 Token Validation 3 Outbound Mechanism 4 User Information Returned 4 Inbound Mechanism 5 Supported Protocols 6 Chapter 3: API Access Setup 7 Granting Web Service Access in PrismHR 7 Granting Web Service Access in HRPyramid 9 Chapter 4: Outbound Configuration 12 Single Sign-On Services Setup 12 Setting Up SSO Services in PrismHR 12 Setting Up SSO Services for HRPyramid 13 Outbound Menu Setup 14 PrismHR Menu Setup 14 Creating the PrismHR Menu Item 15 Adding the SSO Menu Item to a User Role 16 Employee Self-Service (ESS) Menu Setup PrismHR iii

4 Table of Contents Adding ESS Menu Definitions in PrismHR 19 Adding Menu Item to ESS Menus in PrismHR 20 Employee Portal Menu Setup 22 Adding Menu Item in Employee Portal Configuration Tool 22 HRPyramid Web Edition Menu Setup 23 Adding Web Menu Definitions in HRPyramid 23 Configuring the HRPyramid Web Edition Menu 24 Outbound SSO Code Examples 25 PEO Identifier 26 Chapter 5: Inbound Configuration 28 Inbound SSO Configuration 28 Inbound SSO Code Examples 29 Appendix A: Sequence Diagrams 30 Outbound Sequence Diagram 30 Inbound Sequence Diagram 31 Appendix B: SSO and TSSO 32 Single Sign-On Guide 2018 PrismHR iv

5 Chapter 1: Introduction Cha pte r 1 :Intr oduc tion Use this document to learn about PrismHR s support for single sign-on between PrismHR products and thirdparty vendor products. Intended Audience These contents are intended for: Vendors who want to link from their product to PrismHR products. Service providers who want to configure their systems to support single sign-on (SSO) for PrismHR and third-party vendor products. PrismHR employees who need to configure single sign-on. Developers implementing SSO should be familiar with the terminology used in this document, as well as the technology used to build the product so that they can integrate it with the PrismHR products. The setup at the service provider would typically be performed by an administrator, who should be familiar with the products that require configuration. Requirements To use the PrismHR single sign-on features: The third-party vendor must alter their software to communicate with PrismHR. If the service provider is on-premise, they must have purchased and installed the PrismHR Web Service API. Conventions These are the formatting conventions used. Formatting Example Indicates Client Details Notes tab Client Notes panel Name of the form (screen) Name of the tab in a form Name of a panel within a form or tab Single Sign-On Guide 2018 PrismHR 1

6 Conventions Formatting Example Client Details (found in the Client menu under Client Change Client Change > Client Details Press Enter or click Save. Click Employee to open the search window. Enter the Employee ID. Select Professional Employer. To exclude the report, enter The system displays the message The current record has been saved. Indicates Menu name and path Form name and path Keys on the keyboard or buttons in the interface Clickable field labels that open searches Field names Value that users can select from a drop-down Values that users can type System values Many topics include sample screens, which you can use as a graphical reference. The examples do not necessarily contain the information that you should type in the fields. Single Sign-On Guide 2018 PrismHR 2

7 Chapter 2: Overview Cha pte r 2 :Ov e r v ie w There are two mechanisms: inbound and outbound. Outbound: Users log in to one of the PrismHR products and then click a menu item or link to access a thirdparty vendor product. Inbound: Users log in to a third-party vendor product and then click a menu item or link to access a PrismHR product. Security 3 Token Validation 3 Outbound Mechanism 4 Inbound Mechanism 5 Supported Protocols 6 Security Security for both the outbound and inbound mechanisms relies on an out-of-band conversation between the two servers: a source and a target. Outbound mechanism: The source is the PrismHR product (PrismHR, ESS, or HRPyramid Web Edition) and the target is the third-party vendor product. Inbound mechanism: The source is the third-party vendor product, and the target is PrismHR, ESS, or HRPyramid Web Edition, depending on the user. When the request is made to go from the source product to the target, PrismHR creates a one-time use token. The token is good only once. After the user follows the link to the product, the token is deleted. The user must log back in to the system to access the other product again. Even if they save the URL, it will not work. OAuth calls this a nonce token, which means number used once. Token Validation The third-party vendor connects to the PrismHR system and validates or requests a token using the PrismHR Web Services API. Single Sign-On Guide 2018 PrismHR 3

8 Outbound Mechanism Outbound Mechanism In the outbound mechanism: 1. The user logs in to a PrismHR product (PrismHR, ESS, or HRPyramid Web Edition). 2. They click a menu item or link to access a third-party vendor product. The PrismHR system stores a token in the database, then sends the token to the user machine and redirects the user to the third-party server. The token is embedded in the redirect URL as a query string parameter. 3. The third-party product receives the token, then takes that token and makes a direct call to the PrismHR system. It asks for the identity of the user associated with the token. The PrismHR system sends one of two responses: Valid = Confirms that the user logged into the PrismHR system and then sends the user s information: name, company ID, user type, and so on. See "User Information Returned" below. Null = The PrismHR system did not recognize the token. With that information, the third-party product can identify the user and log them in. Figure 1: Outbound Process Related Topics Outbound Configuration (page 12) Outbound Sequence Diagram (page 30) User Information Returned Table 1 lists the values that the system returns when a third-party product makes a call to the PrismHR system; the values are for the user who is associated with the token. Single Sign-On Guide 2018 PrismHR 4

9 Inbound Mechanism Table 1: User Information and Associated Types Value Description Notes valid indicates whether the user is valid This returns 'true' if the user is valid, otherwise it returns 'false'. userid user identifier This is the username for in PrismHR, Employee Self-Service (ESS), or Employee Portal. usertype user type User types are: 'S' (SuperUser (HRPyramid Web Edition)), 'I' (Internal User (PrismHR)), 'C' (HRPWE Client Manager, PrismHR Worksite Manager, or PrismHR Worksite Trusted Advisor), and 'E' (Employee) employeeid employee identifier This is returned only for employee and worksite manager user types. clientid client identifier The identifier for the client specified in the call. clocknumber clock number This is returned only for employees or worksite managers accessing the third-party product from Employee Self-Service (ESS) or Employee Portal. The value comes from the Employee Details Work tab. clientname client name This is the name of the client specified in clientid. employeenumber employee number This is returned only for employees or worksite managers accessing the third-party product from Employee Self-Service (ESS) or Employee Portal. The value comes from the Employee Details Work tab. peoname service provider name This is the name of the employer assigned to the specified client. address The address specified on the user account. Inbound Mechanism In the inbound mechanism: 1. The user logs in to a third-party vendor product (external application). 2. They click a menu item or link to access a PrismHR product (PrismHR, Employee Self-Service (ESS), or HRPyramid Web Edition). The third-party product connects to the PrismHR system using the PrismHR Web Services API. The PrismHR Web Services API generates a one-use token, puts it in the database, and sends it to the thirdparty product along with the URL for the system to which the user should go: If the user belongs to a client that is on PrismHR, the user is directed to PrismHR or ESS. If the user belongs to a client that is on HRPyramid, the user is directed to HRPyramid Web Edition. The vendor does not need to know which one; the PrismHR system handles that. 3. The system checks the token against the stored value for that user and, if valid, automatically logs the user in to the appropriate PrismHR product. Finally, the system deletes the token to ensure that it cannot be used again. Single Sign-On Guide 2018 PrismHR 5

10 Supported Protocols Figure 2: Inbound Process Related Topics Inbound Configuration (page 28) Inbound Sequence Diagram (page 31) Supported Protocols The PrismHR API single sign-on uses an out-of-band token-based communication similar to the OAuth 2.0 pattern. Single Sign-On Guide 2018 PrismHR 6

11 Chapter 3: API Access Setup Cha pte r 3 :APIAc c e s s S e tup Whether you are configuring your system for links to or from a third-party vendor product (outbound or inbound, respectively), you need to set up a web service user for that product. Granting Web Service Access in PrismHR 7 Granting Web Service Access in HRPyramid 9 Granting Web Service Access in PrismHR Each vendor requires a web service username and password to connect to PrismHR, Employee Self-Service (ESS), or Employee Portal. 1. While logged in to PrismHR as a service provider user, open System Parameters (found in the Back Office menu under System Change). 2. Open the Action bar and then select Web Service Users. The Web Service User Profile form opens. Figure 3: Web Service User Profile Example 3. Enter the User ID. Single Sign-On Guide 2018 PrismHR 7

12 4. Enter the User Name. 5. Enter the Contact Information, such as the user s phone number and address. 6. Enter the Password. 7. You would only select Account Disabled to deactivate the user account. Granting Web Service Access in PrismHR By default, web service users can see only active clients. With some API methods, they can see inactive clients. Companies in other statuses (pending, pre-terminated, and terminated) are not available. 8. Select the Company Access method to use to define the companies that the user can access. Grant Access by Default, Deny Access to Specified: This is the most commonly used option. The user has access to all companies by default. If the user should not have access to some client companies, enter those company IDs in the table below. Deny Access by Default; Grant Access to Only Specified Companies: The user can access only the companies listed in the table below. 9. (Optional) Enter each Company ID. The Company Name displays. Depending on the Company Access setting, the user is either restricted from accessing those companies or they have access to only those companies. 10. You can select Disable IP Restrictions to disable the IP restriction feature. This is not recommended for use aside from development. 11. Enter the Allowed IPs, which are the IPs allowed to access the web service engine with this user's credentials. The service provider is responsible for getting the IP address list from the developers of the third-party product. They are also responsible for keeping the list up-to-date when changes occur. The vendor hosts the third-party product on their own servers and so they maintain the IP addresses associated with those servers. 12. You can select Disable Method Restriction to disable method restriction. This is not recommended for use aside from development. 13. Specifying the Allowed Methods enables you to grant certain web service users access to only some features of the PrismHR Web Services API. For example, you might want a time clock vendor to have access only to time-related methods. Note that any changes you make will be applied the next time the user logs in to the system; if the user is currently logged in, there will be no change to their access. a. Enter each Allowed Method that the user is allowed to call. See the table below for the methods used for single sign-on. Leave the Allowed From and Allowed To fields blank if there should be no time of day restriction for the method. b. Enter the Allowed From time of day when the method can be called. Single Sign-On Guide 2018 PrismHR 8

13 Granting Web Service Access in HRPyramid c. Enter the Allowed To time, which is the end time of day when the method can be called. If there is a time in the Allowed From field but no value in the Allowed To field, then the system defaults to midnight. 14. Click Save. The Method... Login.createPeoSession SignOnResponse.redirectUrlByEmployee SignOnResponse.redirectUrlByUser SignOnResponse.validateTssoToken Table 2: Single Sign-On Methods Is Used For Single Sign-On When... Creating session token required for using method in the SignOn service. Redirecting only employee users for inbound SSO from a third-party product to Employee Self-Service (ESS). Redirecting any user type for inbound SSO from a third-party product to PrismHR, Employee Self-Service (ESS), or HRPyramid Web Edition. Redirecting any user from a PrismHR product to a third-party product. Granting Web Service Access in HRPyramid If you need to connect the vendor to HRPyramid Web Edition, you must set up a web service username and password in HRPyramid. 1. In HRPyramid, select System Administration > File > Web Administration > Web Service Access. The Web Service Access Control form opens (Figure 4). Figure 4: Web Service Access Control 2. Enter the vendor s information. a. Enter a unique User ID. b. Enter the User Name that the vendor uses to access the system. Single Sign-On Guide 2018 PrismHR 9

14 c. Enter the Password that the vendors uses to access the system. Granting Web Service Access in HRPyramid d. Use the Account Disabled field to control whether the vendor can access your system at all. e. You can enter the vendor s Contact Info. 3. You can use F5-IP List to enter specific IP addresses used by the vendor to help enforce security. a. Enter N in IP Restriction Disabled to enable IP restrictions. (You can also enter Y to disable the IP restriction feature, but this is not recommended for use aside from development. If you choose to enter Y, you can proceed to step c. ) b. Enter each of the Allowed IPs, which are the vendor s IP addresses that are allowed to connect to the system. c. Click F2-Accept. 4. You should use F6-Methods List to restrict the methods that the vendor can use. For example, you might want a time clock vendor to access only features related to time sheets. a. Enter N in Method Restriction Disabled to enable method restrictions. (You can also enter Y to disable method restriction. This is not recommended for use aside from development. If you choose to enter Y, you can proceed to step d. ) b. Enter each of the Allowed Methods; see the table below for the methods used for single sign-on. c. If you want to restrict the hours of the day when the vendor can use the methods, enter times in the Allowed From and Allowed To fields. For example, you might not want the vendor to access certain methods during business hours to prevent them from overwhelming and slowing down the system. d. Click F2-Accept. 5. You can use F7-Company List to control the clients that the vendor can access. This feature allows you to specify either a white list or a black list. a. In the Company List Grant/Deny field: Enter G if you want to grant access to specific clients. If you enter G and do not enter any client company IDs in the list, then the vendor cannot access any clients. Enter D to deny access to specific clients. If you enter D and do not specify any clients, then the vendor can access all clients. b. Enter each Company ID. c. Click F2-Accept. 6. Click F2-Save. The Method... Login.createPeoSession Table 3: Single Sign-On Methods Is Used For Single Sign-On When... Creating session token required for using method in the SignOn service. Single Sign-On Guide 2018 PrismHR 10

15 Granting Web Service Access in HRPyramid The Method... SignOnResponse.redirectUrlByEmployee SignOnResponse.redirectUrlByUser SignOnResponse.validateTssoToken Table 3: Single Sign-On Methods Is Used For Single Sign-On When... Redirecting only employee users for inbound SSO from a third-party product to Employee Self-Service (ESS). Redirecting any user type for inbound SSO from a third-party product to PrismHR, Employee Self-Service (ESS), or HRPyramid Web Edition. Redirecting any user from a PrismHR product to a third-party product. Single Sign-On Guide 2018 PrismHR 11

16 Chapter 4: Outbound Configuration Cha pte r 4 :OutboundConfig ur a tion To support single sign-on from a PrismHR product to a third-party product, the service provider and the developers need to make sure that the system and code are ready. Single Sign-On Services Setup 12 Outbound Menu Setup 14 Outbound SSO Code Examples 25 PEO Identifier 26 Single Sign-On Services Setup To add a menu item that links to the third-party product from a PrismHR product, you must define the SSO service. If your organization uses any of the PrismHR products, you can set up the SSO service in PrismHR; see "Setting Up SSO Services in PrismHR" below. If your organization uses only HRPyramid and HRPyramid Web Edition, then you must set up the SSO service in HRPyramid; see "Setting Up SSO Services for HRPyramid" on the next page. Setting Up SSO Services in PrismHR If you need to link from a PrismHR product to a third-party vendor product, you must set up the SSO services. You specify it when you set up the menu item. 1. Open System Parameters (found in the Back Office menu under System Change). 2. Open the Action bar and then select SSO Services. Figure 5: SSO Services 3. Click + to add a new row. 4. Enter the Service ID, which is a unique identifier for the service. Single Sign-On Guide 2018 PrismHR 12

17 5. Enter the service Description. Setting Up SSO Services for HRPyramid 6. Select the service Type, which is typically External for a vendor and Internal for services hosted on your organization s servers. 7. Enter the Service URL, which is the location of the product. 8. Click Save. Setting Up SSO Services for HRPyramid These instructions are for organizations that use only on-premise HRPyramid and want to create a link to a third-party product from HRPyramid Web Edition, you need to set up the SSO services in HRPyramid. If your organization uses only HRPyramid for the cloud, you need to submit a support ticket to set up SSO services. If your organization has clients in both PrismHR and HRPyramid (on-prem or cloud) (or only PrismHR), use the instructions in "Setting Up SSO Services in PrismHR" to link from Employee Self-Service (ESS) to a third-party product. 1. Log in to HRPyramid. 2. Press the / key on the keyboard. The TCL command line prompt opens. 3. Enter SSO.SERVICES.MNT (Figure 6) and then click Accept. Figure 6: TCL command line prompt 4. In the Screen for setting up SSO URLs, you can enter the SSO information. a. Enter the SSO Key, which is a unique identifier for the service. b. Enter the SSO URL, which is the location of the product Single Sign-On Guide 2018 PrismHR 13

18 Outbound Menu Setup Figure 7: Screen for setting up SSO URLs 5. Click F2-Save. Outbound Menu Setup There are different setups required for each of the PrismHR products. Refer to the appropriate instructions to create the link from the PrismHR product to the third-party vendor product PrismHR Menu Setup 14 Employee Self-Service (ESS) Menu Setup 19 Employee Portal Menu Setup 22 HRPyramid Web Edition Menu Setup 23 PrismHR Menu Setup There are steps you need to perform to enable users to access the third-party vendor product from PrismHR. 1. Granting Web Service Access in PrismHR (page 7) 2. Setting Up SSO Services in PrismHR (page 12) 3. Creating the PrismHR Menu Item (page 15) 4. Adding the SSO Menu Item to a User Role (page 16) Single Sign-On Guide 2018 PrismHR 14

19 Creating the PrismHR Menu Item Creating the PrismHR Menu Item You define a Custom Process to make the SSO service a menu item. 1. Open System Parameters (found in the Back Office menu under System Change). 2. Open the Action bar and then select Custom Process. Figure 8: Custom Process 3. Enter a unique Process ID. 4. Enter a Name for the process. This will display in menus and the search (where applicable). 5. Select the Category to indicate the menu where the SSO menu item belongs. 6. Select the Sub-Category to indicate where the SSO menu item belongs within the selected menu. If you select Other, you can enter a custom sub-category. 7. Select Disabled only if you do not want the SSO menu item to display anywhere. 8. Select Display in Menus to show the SSO menu item in the menu to users who have access to the menu item. 9. Select Display in Search to show the SSO menu item to users who have access to it and use the search field to find it. 10. Select Disable Resizing if you do not want the SSO feature to adjust its size based on the browser window. 11. If the menu item should be limited to a specific user role, select Service Provider or Worksite Manager as appropriate. If the menu item should be available to user roles of either type, leave this drop-down set to Select. Single Sign-On Guide 2018 PrismHR 15

20 Adding the SSO Menu Item to a User Role 12. Version Type: For future development. Does not currently impact the functionality of PrismHR. 13. Select the SSO Service that you set up in the previous procedure. 14. Leave SSO Action blank. It is not used by the tandem SSO. 15. From the SSO Init, drop-down, select Tandem SSO. 16. External App indicates whether this was defined as an external application in SSO Services. You cannot edit it here. 17. Parameters: For future development. Does not currently impact the functionality of PrismHR. 18. Click Save. Adding the SSO Menu Item to a User Role Once the custom process for the SSO menu item exists, you need to add it to the appropriate user roles so that users can see it. This is the basic process for adding the form to the role; see User Roles in the PrismHR System Administration Guide for specifics. Service provider users and worksite manager or trusted advisor users have separate user roles. When you add multiple roles to a user, and one role denies access to menu item while another role grants access, then the system denies the user access to that menu item. You must make sure that a user who should have access to a menu item does not also have a role that denies them access to it. Refer to the PrismHR in-product help or the chapter on users and security in the PrismHR System Administration Guide. There are different approaches to granting access to the menu item that a PrismHR user with permission to access the User Roles and Users forms can take: Add the menu for all service provider or worksite manager/trusted advisor users that share a user role. Use this method when many users who have the same roles will need to access the menu item. Create a role specifically granting access to the menu and then assign it to the appropriate users. Use this method when only a handful of users require access to the menu item. You could use a combination of these methods; for example: Add the menu item to a service providers user role to grant all associated service provider users access to that menu item, then Create a worksite manager user role that you assign to only specific worksite manager and trusted provider users who need access to the menu item. Adding the Menu Item for Groups of Service Providers and Managers You add access to the menu to the role for service provider or worksite manager/trusted advisor users in the User Roles form. It is a new menu item in addition to other items that they should be able to access. 1. Open the User Roles form (found in the Back Office menu under System Change). 2. Click the Role ID link and select the role that should have access to the SSO menu item. Single Sign-On Guide 2018 PrismHR 16

21 Adding the SSO Menu Item to a User Role 3. Click the Add button. The User Role Maintenance form opens. 4. Locate the SSO menu item in the list and place a checkmark in the Select checkbox. Figure 9: User Role Maintenance 5. Click Accept. You return to the User Roles form, where the SSO menu item now displays. Figure 10: Sample SSO Menu Item in User Role 6. Click Save. The next time users with that role log in to the system, they can access that form as indicated in Custom Process (in the menu, the search, or both). 7. Repeat the process for each role that needs to access the SSO menu item. Adding the Menu Item for Select Users If you intend to grant access to only certain users, you can create a user role that grants access to the SSO menu item and then assign it to those user accounts. 1. First, create a new specialized worksite user role that grants access to the menu item: a. Open the User Roles form (found in the Back Office menu under System Change). b. Open the Action bar and select New Role. The Role Maintenance form opens. c. Enter a unique Role identifier that briefly indicates the role s purpose. d. Enter a Description of the user role that clearly explains the role s purpose. e. From the User Type drop-down, select the user role type; for example, Worksite Manager. If you want to have a special user role granting access to the menu item for service provider roles, you would create a separate role and specify that user type. Single Sign-On Guide 2018 PrismHR 17

22 Figure 11: Role Maintenance (New Role) Adding the SSO Menu Item to a User Role f. Click Save. The User Role form populates with the information you entered for the new role, with no forms assigned. g. Click the Add button. The User Role Maintenance form opens. h. Locate the SSO menu item in the list and place a checkmark in the Select checkbox (Figure 9). i. Click Accept. You return to the User Roles form, where the SSO menu item now displays. Figure 12: Sample SSO Menu Item in Specialized User Role j. Click Save. 2. Second, assign the role to the users who should be able to access the menu item: a. Open the Users form (found in the Back Office menu under System Change). b. Enter the User ID of the user who should be able to access the SSO menu item. c. In the User Roles table, click + to add a new row at the bottom of the table. d. Enter the user role you created in the earlier steps. Figure 13: Worksite Manager User Note that the user type you specified in step 1.e. must match the type of user you are editing. For example, you cannot add a worksite manager-type user role to a service provider user. Single Sign-On Guide 2018 PrismHR 18

23 e. Click Save. Employee Self-Service (ESS) Menu Setup The next time the user logs in to the system, they can access that form as indicated in Custom Process (in the menu, the search, or both). f. Repeat the process for each user who needs to access the SSO menu item. Employee Self-Service (ESS) Menu Setup There are steps you need to perform to enable users to access the third-party vendor product in Employee Self-Service (ESS). 1. Granting Web Service Access in PrismHR (page 7) 2. Setting Up SSO Services in PrismHR (page 12) 3. Adding ESS Menu Definitions in PrismHR (page 19) 4. Adding Menu Item to ESS Menus in PrismHR (page 20) Adding ESS Menu Definitions in PrismHR Use the ESS Menu Definition form (Figure 14) to define the menu item for the third-party vendor product that you can then add to Employee Self-Service (ESS) menus. 1. Open ESS Menu Definitions (Back Office menu > System Parameters > Action bar > ESS Menu Definitions). You can select an existing menu to edit from the drop-down at the top of the form. Most likely you will create a new menu item. 2. Enter the Menu Title for the SSO menu item. 3. Enter the Menu Tooltip that should display when a user hovers the mouse over the menu header. 4. Enter a unique Menu Code. 5. Do not select Is this Menu for a Single Sign On. This is only for backward compatibility to legacy features. 6. Select Internal Component and enter tsso. This is required to use the Web Service API s single sign-on features. 7. To display an icon for the menu, enter the Image URL, which is the file path for the image, for example, img/flatimages/svg/tiles/myself.svg. See the in-product help for a list of available images and the associated file paths. Single Sign-On Guide 2018 PrismHR 19

24 Figure 14: ESS Menu Definition Adding Menu Item to ESS Menus in PrismHR 8. Click + to expand the Additional Params. 9. Enter vendor as the Key. 10. For the Value, enter the service ID set up for the vendor in SSO Services. 11. Click Save. Adding Menu Item to ESS Menus in PrismHR You need to add the menu item defined in ESS Menu Definitions for the third-party vendor product to a menu. 1. You can add the menu item to the default (global) menu and individual client s menus. To add it to the default ESS menu, select Back Office menu > System Parameters > Action bar > ESS Default Menu Builder (Figure 15). Single Sign-On Guide 2018 PrismHR 20

25 Adding Menu Item to ESS Menus in PrismHR To add it to a client s ESS menu (a client that is not using the default menu structure), open Client Details and then select ESS Menu Builder from the Action bar (Figure 16). 2. Expand the menu header where you want to add the menu item. 3. Locate the menu item in the Available Menu Items list. (Menu items are created in ESS Menu Definitions; see "Adding ESS Menu Definitions in PrismHR" on page 19.) 4. Click and drag the item to the spot in the menu where you want it to display. Figure 15: Adding a menu item in the ESS Default Menu Builder Figure 16: Adding a menu item in the client ESS Menu Builder Single Sign-On Guide 2018 PrismHR 21

26 Employee Portal Menu Setup See the in-product help to learn more about using the ESS Default Menu Builder or ESS Menu Builder. Employee Portal Menu Setup There are steps you need to perform to enable users to access the third-party vendor product in Employee Portal. You must have access to the Employee Portal Configuration Tool. 1. Granting Web Service Access in PrismHR (page 7) 2. Setting Up SSO Services in PrismHR (page 12) 3. Adding Menu Item in Employee Portal Configuration Tool (page 22) Adding Menu Item in Employee Portal Configuration Tool Use the the EP Configuration Tool to add the menu item for the third-party vendor product in Employee Portal. 1. Log in to the EP Configuration Tool. 2. Open the Configuration menu and select Templates. 3. Select the appropriate template. 4. Select the Menu tab. 5. Determine where the single sign-on menu item belongs in the menu: If it belongs at the top level, click New Top-Level Menu. It displays at the bottom of the list; you can move it by using the arrow buttons. If it belongs in another menu item, select that item and then click New Sub Menu. It displays underneath that top-level menu item; you can change its position within the sub menu by using the arrow buttons. 6. In the Title (en) field, enter the name for the menu item. 7. In the Hover Text (en) field, enter the tooltip that should display when a user hovers the mouse over the menu header. 8. If appropriate, enter the Spanish versions of the menu item and tooltip in the Title (es) and Hover Text (es) fields. 9. Select the Component option. 10. From the Component drop-down, select Single Sign-On. This is required to use the Web Service API s single sign-on features. (Do not select Legacy Single Sign-On. This only is for backward compatibility to legacy features.) 11. From the SSO Service drop-down, select the service ID set up for the vendor in SSO Services. 12. If you want, select an Icon to display next to the menu item. Single Sign-On Guide 2018 PrismHR 22

27 Figure 17: Menu Item Setup in the EP Configuration Tool HRPyramid Web Edition Menu Setup 13. Click Save. The menu item now dislays in Employee Portal. See the in-product help to learn more about using the EP Configuration Tool. HRPyramid Web Edition Menu Setup If you need to enable users to access the third-party vendor product from HRPyramid Web Edition, there are steps you must perform. 1. Granting Web Service Access in HRPyramid (page 9) 2. Setting Up SSO Services for HRPyramid (page 13) 3. Adding Web Menu Definitions in HRPyramid (page 23) 4. Configuring the HRPyramid Web Edition Menu (page 24) Adding Web Menu Definitions in HRPyramid Use the Web Menu Definitions Maintenance form to define the menu item for the third-party vendor product that you can then add to HRPyramid Web Edition menus. 1. Select System Administration > File > Web Administration > Menu Definitions. The Web Menu Definitions Maintenance form opens (Figure 18). Single Sign-On Guide 2018 PrismHR 23

28 Figure 18: Web Menu Definitions Maintenance Configuring the HRPyramid Web Edition Menu 2. Enter a unique Menu Name. 3. Enter the Text for the menu name. 4. Enter the Alt Text that should display when a user hovers the mouse over the menu header. 5. Enter the Link to the third-party vendor product in the format tsso?vendor=<vendor KEY>. You map the vendor key to a URL in the SSO Services form. 6. Indicate who should have Access to the menu item: E = employees C = clients B = both employees and companies 7. If employees should be notified, indicate who should receive notification: P = payroll representatives H = human resources representatives B = benefits representatives 8. Click F2-Save. Configuring the HRPyramid Web Edition Menu Use Menu Configuration to add the menu item for the third-party vendor product to the HRPyramid Web Edition menu. Single Sign-On Guide 2018 PrismHR 24

29 Outbound SSO Code Examples Figure 19: Menu Configuration 1. Open the Administration menu and select Menu Configuration. 2. Select the appropriate option from the User drop-down. 3. Select the menu where you want to add the item in the Header Menu list. 4. Locate the menu item in the Available Menu Items list and drag it to the Sub Menus list. 5. Click SAVE Changes. Outbound SSO Code Examples To register the user session, you must first get a session token (sessionid) by calling the LoginService s createpeosession method in the PrismHR Web Service API with the credentials set up for the web service user (username and password) and the service provider s identifier (peoid). login/createpeosession ( username, password, peoid ) Single Sign-On Guide 2018 PrismHR 25

30 PEO Identifier You then use the SignOnService s validatetssotoken method to validate the token that comes in the querystring. signon/validatetssotoken ( sessionid, tssotoken ) When you validate with the validatetssotoken method, you receive a payload (either SOAP or JSON, depending on how you connect) that contains the user s information. Related Topics Granting Web Service Access in PrismHR (page 7) Granting Web Service Access in HRPyramid (page 9) PEO Identifier (page 26) PEO Identifier Users with the necessary permissions can locate the PEO ID in the System Parameters for PrismHR. 1. Open System Parameters (found in the Back Office menu under System Change). 2. Locate the PEO ID (Figure 20). Figure 20: PEO ID field in System Parameters Single Sign-On Guide 2018 PrismHR 26

31 PEO Identifier If there is no value in the PEO ID field, submit a ticket through the Customer Resource Center. Single Sign-On Guide 2018 PrismHR 27

32 Chapter 5: Inbound Configuration Cha pte r 5 :InboundConfig ur a tion To support single sign-on from a third-party product to a PrismHR product, the service provider and the developers need to make sure that the system and code are ready. Inbound SSO Configuration 28 Inbound SSO Code Examples 29 Inbound SSO Configuration You would need an inbound SSO configuration if you want a third-party product to have a single sign-on to PrismHR, Employee Self-Service (ESS), Benefits Enrollment, or HRPyramid Web Edition. If you have ever been configured for an inbound SSO, you do not need further configuration for any new products. If your organization has never been configured with an inbound SSO configuration, submit a request through the Customer Resource Center at similar to the one shown in Figure 21. Single Sign-On Guide 2018 PrismHR 28

33 Inbound SSO Code Examples Figure 21: Sample Inbound SSO Configuration Request Inbound SSO Code Examples To register the user session, you must first get a session token (sessionid) by calling the LoginService s createpeosession method in the PrismHR Web Service API with the credentials set up for the web service user (username and password) and the peoid. login/createpeosession ( username, password, peoid ) Then the third-party vendor application must make a web service call to one of the SignOnService s redirect methods: For any user (service provider, worksite manager or trusted advisor, and employee users): signonservice/redirecturlbyuser ( sessionid, clientid, userid, usertype, {componentid}, {siteid} ) For employee users only: signonservice/redirecturlbyemployee ( sessionid, clientid, employeeid, {componentid}, {siteid} ) Single Sign-On Guide 2018 PrismHR 29

34 Appendix A: Sequence Diagrams Appe ndix A:S e que nc e Dia g r a ms The sequence diagrams illustrate the processes that occur in the outbound and inbound mechanisms for single sign-on. Outbound Sequence Diagram Figure 22 illustrates what happens, technically, when a user links from a PrismHR product to a third-party vendor s product. Figure 22: Outbound Sequence Related Topics Outbound Mechanism (page 4) Outbound Configuration (page 12) Single Sign-On Guide 2018 PrismHR 30

35 Inbound Sequence Diagram Inbound Sequence Diagram Figure 23 illustrates what happens, technically, when a user links from a third-party vendor s product to a PrismHR product. Figure 23: Inbound Sequence Related Topics Inbound Mechanism (page 5) Inbound Configuration (page 28) Single Sign-On Guide 2018 PrismHR 31

36 Appendix B: SSO and TSSO Ap p e n d ix B:S S Oa n d T S S O Single sign-on (SSO) enables users of PrismHR products to link directly to and from third-party vendor products without needing to sign in to the product again. The PrismHR products are: PrismHR Employee Self-Service (ESS) Employee Portal HRPyramid Web Edition Service providers may also be using all of the products in what is called tandem, where some clients are in PrismHR/ESS and others are in HRPyramid/HRPyramid Web Edition. Based on the user information, the system knows what product to link the user to; the vendor does not need to determine whether to point the user to PrismHR/ESS or HRPyramid Web Edition. This is called tandem single sign-on (TSSO). Single Sign-On Guide 2018 PrismHR 32