Introduction
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.
Background
Self-Service has 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-Service allows 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-Service is 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.
3. Requirements
This section describes customer/IdP SAML2 requirements to integrate with Self-Service.
3.1 Standard SAML2 Requirements.
This list contains general requirements that are common in SAML2 integrations.
3.2 Self-Service Specific Requirements
This list contains requirements that are specific to Self-Service.
3.4 SAML2 Configuration Exchange Requirements
SAML2 configuration data that should be made available by the IdP:
SAML2 configuration data that is available in Self-Service:
3.5 Testing Requirements
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.
4. Details for Integration with Self-Service
4.1 Typical SSO Implementation Checklist for a New Customer
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.
4.2 Enable SSO in Self-Service
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-Service provides the information and certificates required by the IdP and also the ability to enter IdP configuration details.
4.3 Agree the attribute name for the User Identifier GUID
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 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:
- https://yourcompany.org/saml2/attribute/uid
- YourCompany.Attribute.UniqueIQ
- self-service-unique-id
- CintraUID
Note:
SAML2 attribute names are case sensitive.
4.4 Create Self-Service SAML2 Application in the IdP
We have some guides for creating new SAML2 applications with common Identity Providers:
- AzureAD
- Okta
- ADFS
4.5 Add the User Identifier GUID attribute to the IdP application
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.
4.6 Generate and Add GUID to the Nominated Test User's IdP Profile
The
User Identifier GUIDs assigned to each user profile should follow a specific structure as defined in
RFC 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==
Tools for generating GUIDs
Important
It is recommended not 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 in PowerShell
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.
4.7 Provide the Test User GUID to Cintra
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.
4.8 Generate/Link all Remaining Required User GUIDs to IdP User Profiles
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.
4.9 Populate GUIDs in the Bulk Account Creation Spreadsheet
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.
6. Certificates
6.1 Signing and Encryption
Self-Service DOES require SAML2 messages to be signed.
Self-Service DOES NOT require 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-Service includes 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.
6.2 Certificate Security
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.
Important
Self-Service does not monitor the IdP metadata URL for changes.
7. Common Questions
7.1 Why do you use a GUID and not the user’s email address?
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.