SSO Setup Guide for Self-Service

Modified on Tue, 10 Dec, 2024 at 2:54 PM

Before you begin

Please read the SSO and Self Service - Technical Factsheet to see the background and requirements needed for a successful integration.

Introduction

This document specifies the steps required to set up SSO in Self-Service. SSO authentication in Self-Service is provided by SAML2 federated authentication and all SSO integrations will require the customer to have a technical resource that is familiar with SSO and SAML2 concepts and terminology.

Setting up SSO in Self-Service has been designed so that most of the initial configuration and any ongoing changes can be carried out by the customer. Therefore, this guide is written with the customer as the intended audience.

New Customer Implementation Checklist

The steps carried out by Cintra and the customer are included in this checklist - the steps required to be performed by the customer are highlighted in bold.

This list covers the steps that relate to only to SSO.

Other steps will be required as part of a new customer implementation but have been omitted from this list.

Step	Description	Who?	Required/Optional
1	IQ and Self-Service site is provisioned	Cintra	Required
2	IQ payroll data initialised (including employees)	Cintra	Required
3	Enable 'Employee Login ADFS' Web Feature License	Cintra	Required
4	Self-Service site URL and System Administrator account credentials provided to customer	Cintra	Required
5	Ensure Self-Service SSO Technical Factsheet & SSO Setup Guide URL are provided to customer	Cintra	Required
6	Enable SSO in Self-Service	Customer	Required
7	Agree the attribute name for the User Identifier GUID (or use the default)	Both	Required
8	Create Self-Service SAML2 application in the IdP	Customer	Required
9	Add the User Identifier GUID attribute to the IdP application	Customer	Required
10	Enter IdP SAML2 configuration data in Self-Service	Customer	Required
11	Alter SSO button appearance	Customer	Optional
12	Generate & add GUID to the nominated test users IdP profile	Customer	Required
13	Provide the test user GUID to Cintra	Customer	Required
14	Create the test user SSO account in Self-Service	Cintra	Required
15	Test user login attempt	Customer	Required
16	Evaluate failed test login attempt(s) in the Testing Error Log	Customer	Optional
17	Generate/Link all remaining user GUID to IdP user profiles in the IdP	Customer	Required

For existing customers already using Self-Service, this checklist can be followed up to step 17 with the following amendments:

Steps 1 & 2 are not required and can be omitted.
Step 14 (actioned by Cintra). If the test user already exists with a Self-Service account, they need to be changed to an SSO login

SO Setup Process

1 - 5. Actioned By Cintra

IQ and Self-Service site is provisioned.
IQ payroll data is initialised (including employees)
Web Feature License is enabled.
To securely provide the customer the Self-Service web application URL and System Administrator login credentials.
To ensure the customer has been given SSO setup documentation.

6. Enable the SSO feature within Self-Service

In a browser, visit the Self-Service application URL provided at step 4.
Log in using the System Administrator credentials provided at step 4.
Once logged, in the left navigation menu, go to Configuration > SSO Settings. (If the navigation menu is not visible - as in fig.1 below, use the top-left 3-line 'hamburger' icon to show the navigation menu.)
You will see the following screen. Click the Enable SSO button.
SSO will be enabled, the page will refresh and you will see a screen similar to the following:

7. Agree the attribute name for the User Identifier GUID

By default, Self-Service reads the SAML2 attribute for the User Identifier GUID from this attribute: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier

Note:

This is a Microsoft claim URI and not a URL for use in a web browser.

If you'll be sending the User Identifier GUID in a different SAML2 attribute, an update to Self-Service will be required and this can be done in step 10.

If you are using the default attribute, no additional update to Self-Service is required.

8. Create Self-Service SAML2 application in the IdP

With the Service Provider/SP SAML2 information provided on the '1. Self-Service Information' tab within SSO Settings of Self-Service (fig. 2 above), you should have sufficient information to create the IdP SAML2 application.

9. Add the User Identifier GUID attribute to the IdP application

The agreed User Identifier GUID attribute (from step 7) will need to be added to the SAML2 settings for the IdP application. This will allow the GUID set on the user's profile to be fetched and sent in the SAML2 response.

For example, if using Okta as the IdP, the below screenshot shows the section within the SAML2 settings of the application that allows this.

In this example, the agreed attribute name is PPID (not the Self-Service default).
The value being used is the user_guid parameter on the user profile.

10. Enter IdP SAML2 configuration data in Self-Service

Once the SAML2 application is created in the IdP, the SAML2 settings required by Self-Service should be available.

These values should be entered into Self-Service in the '2. SAML2 Settings' tab within SSO Settings.

fig.3: SSO Settings - SAML2 Settings Tab

Enter the IdP SAML2 settings

Values can be extracted from an IdP metadata endpoint URL, if the IdP provides one, or the three IdP values and the public certificate can be added/uploaded manually.

File icon

Self-Service does not monitor the IdP metadata URL for changes. Changes to any of the SAML2 values or the certificate in the IdP will require the details to be updated in this tab.

If using the metadata endpoint:

Enter the Metadata URL and click Extract Settings. The required values will be extracted and the IdP fields will be populated, including the IdP Public Certificate if present in the metadata.

Important

Self-Service does not monitor the IdP metadata URL for changes. Changes to any of the SAML2 values or the certificate in the IdP will require the details to be updated in this tab.

Unique Identifier GUID Attribute

If you are not using the default attribute for the Unique Identifier GUID (see step 7), please update the Attribute Name field with the name of the attribute you will be using. To revert this field back to the default attribute name, click the Use Default button.

Any changes on this tab only become active once Save Changes is clicked. To cancel any changes, click Discard Changes.

11. Alter SSO button appearance (Optional)

Self-Service is able to provide both SP-Initiated or IdP-initiated logins. If SP-Initiated logins are to be used, there is the ability to customise the appearance of the SSO login button on the Self-Service login page.

To make changes to the Log in with SSO button, go to the '3. Button Appearance' tab within SSO Settings.

It's possible to change the button text, foreground and background colours and the icon that appears on the button.

All changes can be previewed on this page in the SSO Login Button Preview area. The default button appearance is currently shown in fig.5 below.

fig.5: SSO Settings - Button Appearance tab

Any changes on this tab only become active once Save Changes is clicked. To cancel any changes, click Discard Changes.

12. Generate & add GUID to the nominated test users IdP profile

To prepare for an initial test, the nominated test user will need to be set up with a Unique Identifier GUID in the IdP.

See section 4.6 in the SSO and Self Service - Technical Factsheet for details on generating or obtaining GUIDs.

Once a new GUID is created/obtained, add it to the test user's IdP account profile. This should be set in the profile field where the attribute is configured to fetch it from (set in step 9).

13. Provide the test user GUID to Cintra

Contact your Implementation Consultant or raise a support ticket and provide the following information in order for the test user to be created:

The test users full name, email address and the GUID.

14. Create the test user SSO account in Self-Service - Actioned By Cintra

Once the test user SSO account has been created Self-Service, Cintra will advise when this has been done.

15. Test user login attempt

The nominated user can attempt the first SSO login. This can be done via an SP-initiated or IdP-initiated login process. The test user may or may not be asked to re-authenticate with their credentials, depending on IdP settings. Once they are past the authentication step they will be redirected to Self-Service.

If the SSO login attempt is successful, the user will see one of two pages:

An date of birth verification page. This can be enabled for first login attempts for users to prove their identity before getting access to Self-Service.
The main Self-Service application. With additional verification steps disabled, the user will go straight into the Self-Service application.

If the SSO login attempt is unsuccessful, the user will see a generic error page. Self-Service intentionally does not expose errors to the end user. The test user will not be able to provide any more details on the reason for the failure. If this is the case, please see the next step (Step 16 - Evaluate failed test login attempt(s) in the Testing Error Log.).

16. Evaluate failed test login attempt(s) in the Testing Error Log

Failed SSO Login attempts, and diagnostic information can be seen in the '4. Testing / Error Log' tab within SSO Settings.

fig.6: SSO Settings - Testing / Error Log tab

The entries in the log grid are ordered by most recent log in attempt first. The attribute and GUID information found in the SAML2 response is shown and a message describing the reason for the failure.

With this information the most common reasons for authentication failures can be discovered. This mainly involves making sure the attribute and GUID values are as expected.

The table below contains a list of the potential messages and further information:

Message	Description
GUID is not present or in invalid format in SAML2 response	The User Identifier GUID attribute value is empty or it is not correctly formatted as a GUID (or a base64 encoded GUID). The value that was found is shown in the 'Saml2 Response Guid / Attribute' column Impact ( Impact only relates to SSO authentication. Any users using standard username/password and AD logins will not be affected by any failing SSO authentication. ) Critical to the user. Other user GUID values may/may not be in the correct format. Customer Resolution Check the User Identifier GUID is being fetched from the IdP users profile and make sure it's in the correct format. See Section 4.6 in the SSO and Self Service - Technical Factsheet
No SAML2 settings configured in this Self Service	SSO is not enabled or configuration data has been removed from this Self Service instance Impact ( Impact only relates to SSO authentication. Any users using standard username/password and AD logins will not be affected by any failing SSO authentication. ) Critical. No SSO logins will be possible. Customer Resolution Attempt to re-enable SSO and set up configuration in Self-Service - steps 6-10.
Attribute name not found for this application (ID:1)	The expected User Identifier GUID attribute name can't be found in the SAML2 response. Impact* Critical. No SSO logins will be possible. Customer Resolution Check the Attribute Name specified in Self-Service (step 10) matches the attribute name setup on the IdP application (step 9)

Message

Description

GUID is not present or in invalid format in SAML2 response

The User Identifier GUID attribute value is empty or it is not correctly formatted as a GUID (or a base64 encoded GUID). The value that was found is shown in the 'Saml2 Response Guid / Attribute' column

Impact ( Impact only relates to SSO authentication. Any users using standard username/password and AD logins will not be affected by any failing SSO authentication. )

Critical to the user. Other user GUID values may/may not be in the correct format.

Customer Resolution

Check the User Identifier GUID is being fetched from the IdP users profile and make sure it's in the correct format. See Section 4.6 in the SSO and Self Service - Technical Factsheet

No SAML2 settings configured in this Self Service

SSO is not enabled or configuration data has been removed from this Self Service instance

Impact ( Impact only relates to SSO authentication. Any users using standard username/password and AD logins will not be affected by any failing SSO authentication. )

Critical. No SSO logins will be possible.

Customer Resolution

Attempt to re-enable SSO and set up configuration in Self-Service - steps 6-10.

Attribute name not found for this application (ID:1)

The expected User Identifier GUID attribute name can't be found in the SAML2 response.

Impact*

Critical. No SSO logins will be possible.

Customer Resolution

Check the Attribute Name specified in Self-Service (step 10) matches the attribute name setup on the IdP application (step 9)

Please raise a Support request if the authentication fails and the suggested resolutions fail to resolve the problem.

17. Generate/Link all remaining user GUID to IdP user profiles in the IdP

Once a successful authentication is achieved (step 16) this gives assurance that the SAML2 configuration is correct in Self-Service and at the IdP.

All users that are required to have Self-Service SSO authentication should be set up in a similar way to the test user in step 12.

You may not want all your users to have SSO logins, in that situation please advise your Implementation Consultant which of your users you require traditional (username/password) logins.

Attachments (6)

png

675855d08c0b....png
31.2 KB

png

675855d08c0c....png
61.9 KB

png

675855d08c0c....png
14.2 KB

png

675855d08c0c....png
81 KB

png

675855d08c0c....png
52.3 KB

png

675855d08c0c....png
80.5 KB

Was this article helpful?