---
title: "SSO setup guide for Self-Service"
slug: "sso-setup-guide-for-self-service"
updated: 2026-06-10T11:26:25Z
published: 2026-06-10T11:26:25Z
canonical: "help.cintra.co.uk/sso-setup-guide-for-self-service"
---
> ## Documentation Index
> Fetch the complete documentation index at: https://help.cintra.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.
# SSO setup guide for Self-Service
Before you begin: Please read the SSO and Self Service - Technical Factsheet to see the background and requirements needed for a successful integration.
Remember that instead of creating a new account for SSO for returning employees, you should edit their existing one.
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
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.
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.
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:
Note: 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.
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 withinSSO 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.
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.
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) |
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.
