This document specifies the requirements that a customer must meet in order to use Single Sign-On(SSO) feature within Self-Service together with integration and implementation details. SSO authentication in Self-Service is provided by SAML2 federated authentication and all SSO integrations will require the customer to be familiar with SSO and SAML2 concepts and terminology. Self-Service (the Service Provider/SP) has been tested and is in use with the most popular workplace Identity Provider (IdP) services - AzureAD, Okta, OneLogin, Auth0 and on-prem ADFS.
Self-Servicehas evolved to meet the demand for federated authentication and SAML2 was chosen based on open standards and being well supported by the most widely used Identity Provider services. With the introduction of SSO capabilities in Self-Service, there has been no change to AD and standard username/password authentication capabilities. There is no requirement that all user accounts be SSO, Self-Service will accommodate a combination of SSO, AD and standard logins, however only one can be active at a time per user account.
Self-Serviceallows the customer to configure Self-Service for the initial SAML2 data exchange and for any changes required after SSO go-live. This means configuration changes at the IdP can be immediately made in Self-Service by the customer. For example, a change to the IdP public certificate can be immediately uploaded in Self-Service. Cintra will provide the customer with System Administrator credentials which allows these updates and some other administrative changes to be made to Self-Service.
Self-Serviceis able to provide both SP-Initiated or IdP-initiated logins. Depending on their type of account, users can login via the Self-Service login page, or via an application dashboard provided by the customer's IdP.
It should be noted that there are some intentional constraints that may differ from standard SAML2 integrations. Some environments can allow a new IdP user to self-identify, and through various challenges, allow them to be matched to the application account. This is not the case in Self-Service. All users must be pre-provisioned in Self-Service before a federated login attempt will succeed. Also, we require a unique and immutable token to be stored against the IdP user profile and passed in the SAML2 response to act as the unique identifier for the users identity.
This section describes customer/IdP SAML2 requirements to integrate with Self-Service.
This list contains general requirements that are common in SAML2 integrations.
Ref No. | Description |
|---|---|
1 | Create a new application in the IdP. |
2 | Associate IdP users with the new IdP application. |
3 | Add the SP site metadata URL or enter SP SAML2 configuration data and base64 encoded public certificate to the IdP application. |
4 | Add the IdP metadata URL or enter IdP SAML2 configuration data and base64 encoded public certificate to the SP. |
This list contains requirements that are specific to Self-Service.
Ref No. | Description |
|---|---|
5 | Store a unique user identifier GUID against each users profile in the IdP. Attach the GUID as an attribute in the SAML response. |
6 | Select a user to test the integration with. Add the GUID to the users profile. |
7 | Populate a spreadsheet of users with their corresponding GUID. Upload spreadsheet to create accounts. |
SAML2configuration data that should be made available by the IdP:
Ref. | Description |
|---|---|
1 | IdP Entity ID |
2 | IdP Sign On Service URL |
3 | IdP public signing certificate file (base64 cer file) |
4 | SAML2 SP Metadata URL (optional) |
SAML2configuration data that is available in Self-Service:
Ref. | Description |
|---|---|
1 | SAML2 SP Metadata URL |
2 | SP Entity ID, also known as Audience URI |
3 | SP Single Sign On URL, also known as Assertion Consumer Service or ACS URL |
4 | SP Single Logout URL |
5 | SP public signing certificate file (base64 cer file) |
All SSO login testing is done on the production Self-Service web application.
This applies to new implementations and existing customers requiring some or all Self-Service users to move to SSO authentication.
Testing the SAML2 configuration and validating the authentication involves setting up a single user with SSO. This nominated user should be someone who is readily available to perform authentication when needed. This user should be a real person (not a test account in the IdP), and is often a user from the customer's IT, Payroll or HR departments.
Unfortunately we cannot create temporary user account in Self-Service to test the SSO login. This is because all user accounts must be linked to real person data in Cintra iQ.
Note: For customers already using Self-Service: While testing with the nominated test user, all other existing non-SSO Self-Service users can continue to log in and use Self-Service as they normally would.
From Self-Service v76, customers are able to view and update the SAML2 configuration data directly in Self-Service.
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.
Ref No. | Description | Who? | Required/Optional | Ref. |
|---|---|---|---|---|
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 | Self-Service SSO Setup Guide URL provided to customer | Cintra | Required | |
6 | Enable SSO in Self-Service | Customer | Required | 4.2 |
7 | Agree the attribute name for the User Identifier GUID (or use the default) | Customer/Cintra | Required | 4.3 |
8 | Create Self-Service SAML2 application in the IdP | Customer | Required | 4.4 |
9 | Add the User Identifier GUID attribute to the IdP application | Customer | Required | 4.5 |
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 | 4.6 |
13 | Create the test user SSO account in Self-Service | Customer | Required | 4.7 |
14 | Test user login attempt | Customer | Required | |
15 | Evaluate failed test login attempt(s) in the Testing Error Log | Customer | Optional | |
16 | Generate/Link all remaining user GUID to IdP user profiles in the IdP | Customer | Required | 4.8 |
By logging in to the Self-Service site with the System Administrator credentials and following the SSO Setup Guide, the customer can configure SSO to work with their IdP.
Self-Serviceprovides the information and certificates required by the IdP and also the ability to enter IdP configuration details.
Each SSO user account in Self-Service must be assigned a GUID generated by the customer. The GUID should be sent as an attribute in the SAML2 Response message.
The default SAML2 attribute name is: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier
The default attribute name and User Identifier GUID value as it appears in a SAML2 Response message:
If it's not possible for the IdP to use the default SAML2 attribute name, then any other URI or simple string can be used. The following list shows examples of valid attribute names:
YourCompany.Attribute.UniqueIQ
self-service-unique-id
CintraUID
SAML2 attribute names are case sensitive.
The agreed GUID attribute 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, the below screenshot shows the section within the SAML2 settings of the application that allows this.
The agreed attribute name is PPID (not the Self-Service default).
The value being used is the user_guid parameter on the user profile. 
The User IdentifierGUIDs assigned to each user profile should follow a specific structure as defined inRFC 4122
The format should be 36 characters (32 hexadecimal characters and 4 hyphens) OR a base64 encoded version of the GUID.
Examples of a valid User Identifier GUID values: 123e4567-e89b-12d3-a456-426614174000 czEFTCp7b0SAZWhTOA717w==
OS/Language | Example Command | Further Information |
|---|---|---|
Windows (powershell) | [guid]::NewGuid() | PowerTip: Create a New GUID by Using PowerShell - Scripting Blog (microsoft.com) |
Linux | uuidgen | |
Python 3 | uuid.uuid4() | uuid — UUID objects according to RFC 4122 — Python 3.10.2 documentation |
C# | Guid.NewGuid() | |
Node JS | import { randomUUID } from 'crypto';const uuid = randomUUID(); |
Warning: You shouldnot to use online GUID generation tools provided by unknown third parties
In AzureAD and ADFS/AD environments it is possible to link to the user's ObjectGUID, and use that as the User Identifier GUID. These are GUID values are created when AzureAD/AD objects are created and don't change during the life of the object.You should be aware that if you use the ObjectGUID for this purpose and need to move or recreate an AD User, their ObjectGUID will change and they will no longer be able to log in to Self-Service. To obtain the Object ID for an account, run this command against Azure Active Directory inPowerShell
Connect-AzureAD
Get-AzureADUser -ObjectID "example.user@yourcompany.co.uk"
Note: Please be sure to replace the email address in line two. Also please check the email corresponds exactly to the email of the user doing the SAML2 login test.
Once you have created or obtained the GUID, it should be added to the test users profile in the IdP to make it available for the SAML2 attribute.
Create the test user using full name, email address and the GUID.
For each user required to have SSO logins created, create or obtain GUIDs for each of them and add them to each users IdP profile.
If SSO logins are not required for some of the users, please advise your Implementation Consultant which of your users you require traditional (username/password) logins created for.
For each user that is required to have an SSO account creating for, please enter the GUID value in column F (SSO/SAML2 GUID). The spreadsheet will look similar to the following:
For each user that do not require an SSO login created for, please leave the GUID cell empty in that row.
Also leave the GUID cell empty if it's been requested that the user will have a standard username/password login.
It can be more efficient to export a dataset from the IdP user store that includes the GUID and using populate the GUID column using Excel functions/features. Once this spreadsheet is complete, please arrange to send it securely to your Implementation Consultant.
The most convenient way to exchange SAML2 configuration data is by using metadata. This is also the most reliable as it reduces the chance of typing or copy/paste errors.
In the SSO Settings area of Self-Service, all relevant SP data is shown including the metadata URL.
Once the IdP application is created, some IdP services can also provide a metadata URL. Within Self-Service this can be pasted and parsed to extract the IdP settings.
If an IdP metadata URL is not available, there are text boxes for the values to be entered manually.
Self-Service DOES require SAML2 messages to be signed.
Self-Service DOES NOTrequire SAML2 messages to be encrypted.
When SSO is enabled in Self-Service, a private/public keypair for signing SAML2 messages is created. This certificate has a 10 year expiry date.
Self-Serviceincludes the X509 public signing certificate within the metadata content and also makes it available separately for download if required.
If using IdP metadata, the metadata content should include the X509 public signing certificate for the IdP.
If not using the IdP metadata, the IdP public certificate file will be required and can be uploaded in Self-Service.
It is good practice to check the certificate fingerprint/thumbprint is as expected, to give extra assurance that the certificate hasn’t been tampered with.
The check should be done using a different method to the one used to send the certificate. For example, if the certificate is emailed, don't use email to send the thumbprint string.
The same process should be followed when any of the certificates or metadata are refreshed.
Any configuration changes to certificates and metadata within the Idp or Self-Service should be managed by the customer.
On the Self-Service side it is possible to generate a new signing certificate at any time. However, with a 10 year expiry, this won't be required often.
If, after a new signing certificate is created, the IdP is using and is monitoring the Self-Service metadata URL, then service may continue uninterupted.
However, if not, the Self-Service public signing certificate will need to be downloaded and updated in the IdP.
Any changes to certificates and/or metadata at the IdP side will need to be updated within Self-Service.
Even though the IdP metadata URL can be entered in Self-Service, the values are only parsed, the endpoint is not monitored for changes.
Self-Service does NOT monitor the IdP metadata URL for changes.
The nature of the information within the Self-Service application is highly personal to each user - PII, salary/pay, sickness information, etc.
Therefore, we need to ensure that the Self-Service account is matched correctly after authentication, and reduce the chance of a person being given access to the wrong account.
Email addresses allocated to a person can change, or be assigned to different people over time.
Here are some examples of when this occurs:
Email addresses can contain department specific information and may change as people move within a company/organisation.
Email addresses can be changed when people change their name i.e. after marriage.
Email addresses can also be recycled when leavers and joiners share the same name.
Each change would need to have a corresponding change in Self-Service and the frequency of these changes often depends on the type or size of the organisation.
Another reason email is unsuitable relates to email addresses appearing to represent someone’s identity, and the chance of human error.
Email addresses conveniently assume an association to a real person, most of the time it seems obvious who ‘owns’ an email address from the names included in the address, but unfortunately company or organisation email is not reliable enough to be used for identity purposes. To illustrate, in larger companies, where several staff are employed with the same name, or very close names, the association to a real person becomes less obvious.
E.g. stephen.smith@xyz.com, steve.smith@xyz.com and steven.smith@xyz.com. The consequences aren’t too significant when selecting an email address to send an email to, but for account matching in SSO, getting the right email is critical to make sure access to the correct Self-Service account is given.
The GUID is naturally unique and immutable, and it doesn’t appear to represent an identity, but it can be easily linked to an identity in the Identity Provider (IdP) user store. A GUID is less likely to be given to someone else by accident and won't break the application if a person’s profile data (including email) is changed in the IdP.
There is effort required in setting up the new GUIDs for each user during implementation and for new staff, but for the reasons and risks stated we aren't able to use email or any other data as the user identifier.